Documentation
¶
Overview ¶
Package hostrelaunch implements the safety/state machine for C5 (#2060). It never binds or ends a session and knows no launcher argv. Its adapter must serialize with normal profile launches, supply a strict process proof, and launch only through C3's typed Orca profile machinery.
Index ¶
Constants ¶
const ( FailureSetupFailed = "SETUP_FAILED" FailureVerifyFailed = "VERIFY_FAILED" FailureTimeout = "TIMEOUT" FailureTerminalCreateRefused = "TERMINAL_CREATE_REFUSED" FailureLaunchExitNonzero = "LAUNCH_EXIT_NONZERO" )
const ( Planned = "planned" Applied = "applied" Skipped = "skipped" Failed = "failed" Pending = "RELAUNCH_PENDING_CONTINUITY" RateLimited = "RELAUNCH_RATE_LIMITED" IdentityChanged = "RELAUNCH_IDENTITY_CHANGED" Unproven = "RELAUNCH_UNPROVEN" AgentPresent = "RELAUNCH_AGENT_PRESENT" DuplicateAgents = "DUPLICATE_AGENTS" NoProfile = "NO_LAUNCHER_PROFILE" LaunchFailed = "RELAUNCH_FAILED" VerifyFailed = "RELAUNCH_UNVERIFIED" RollbackFailed = "RELAUNCH_CLEANUP_UNCONFIRMED" // NoExitProof: an exit pass (cli#2161) found no proof the agent ended for // a context reset of this session; the sweep's two-absence rule decides. NoExitProof = "RELAUNCH_NO_EXIT_PROOF" )
Variables ¶
ErrCensusUnavailable means a complete process census remained unavailable.
Functions ¶
This section is empty.
Types ¶
type Agent ¶
type Agent interface {
Reference() string
Verify(context.Context, Target, Observation) error
Rollback(context.Context) error
}
Agent is only the launch this attempt created. Rollback must never select other terminals by worktree or family. Verify links its pinned identity to the one process observed after the launch.
type FileJournal ¶
type FileJournal struct {
// contains filtered or unexported fields
}
FileJournal holds the run lock until Close. The caller must close it only after all Runner calls return. Linux is the Orca host platform for C5. Applying opens claim a generation before returning, including empty sweeps. Read-only opens never create directories, locks or files.
func OpenJournal ¶
func OpenJournal(path string, dry bool) (*FileJournal, error)
func OpenJournalHeld ¶ added in v0.47.0
func OpenJournalHeld(path string) (*FileJournal, error)
OpenJournalHeld takes the run lock as an applying open does but claims no generation (cli#2161): an exit pass observes one worker, not a sweep, so it must not break the absence continuity of the workers it never looked at. Its Sweep is the last sweep's generation, 0 when no sweep ever ran.
func (*FileJournal) Close ¶
func (s *FileJournal) Close() error
func (*FileJournal) Sweep ¶
func (s *FileJournal) Sweep() uint64
type LaunchError ¶
LaunchError carries only an observed closed failure classification. Unknown failures stay in local JSON/logs, never a guessed wire code.
func (*LaunchError) Error ¶
func (e *LaunchError) Error() string
func (*LaunchError) RelaunchFailureReason ¶
func (e *LaunchError) RelaunchFailureReason() string
func (*LaunchError) Unwrap ¶
func (e *LaunchError) Unwrap() error
type Observation ¶
type Observation struct {
// ForeignUIDSkipped counts identity-checked foreign exclusions in this census.
ForeignUIDSkipped int
PIDs []int
Proven bool
}
Observation is strict evidence. A default/partial result cannot prove zero.
type Prepared ¶
Prepared contains a snapshot of a typed profile; preparing it must not write files or start anything. All launch preparation belongs inside Launch.
type Record ¶
type Record struct {
AbsentFor string `json:"absentFor"`
AbsentSweep uint64 `json:"absentSweep"`
Attempts []time.Time `json:"attempts"`
Notice string `json:"notice"`
}
Record persists across processes. Attempts are per worker, across sessions.
type Result ¶
type Result struct {
// ForeignUIDSkipped is the maximum count in a completed census this attempt.
ForeignUIDSkipped int
LocalCause, NoticeCause string
Status, Reason, Reference string
FailureReason string
Attempt int
NoticeFailed bool
AbsentObservedAt time.Time
}
Result has closed status codes and optional diagnostic causes. Adapters must bound and redact causes before exposing them; causes may include launcher errors.
type Runner ¶
type Runner struct {
// BeforeAttempt rechecks transient launch prerequisites before charging budget.
BeforeAttempt func(context.Context) error
Sweep uint64
DryRun bool
Now func() time.Time
Journal Journal
Current func(context.Context, Target) (Desired, error)
Binding func(context.Context, Target) (Binding, error)
Probe func(context.Context, Target) (Observation, error)
Prepare func(context.Context, Target) (Prepared, error)
// Lock must serialize this worktree with C3 starts, not just other C5 calls.
Lock func(context.Context, Target) (func(), error)
// Notice is nil until the server's honest outcome surface is available.
// Log is the caller's structured event/session logger; dry runs call neither.
Notice func(context.Context, Target, Result) error
Log func(Target, Result)
// ExitProof, when set, makes this an exit pass (cli#2161, C12): it is
// asked under the lock, after every guard and the cap, in place of the
// two-consecutive-sweep absence rule and nothing else. True means the
// agent this host launched has exited for a context reset of this exact
// session. An exit pass never records an absence observation: it saw one
// worker, not a sweep.
ExitProof func(context.Context, Target) (bool, error)
}
Runner is one sweep. Sweep must be a persisted increasing generation for an applying run (dry runs never increment it). A skipped intervening sweep then breaks continuity even when that worker never reaches Execute.