hostrelaunch

package
v0.47.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 15 Imported by: 0

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

View Source
const (
	FailureSetupFailed           = "SETUP_FAILED"
	FailureVerifyFailed          = "VERIFY_FAILED"
	FailureTimeout               = "TIMEOUT"
	FailureTerminalCreateRefused = "TERMINAL_CREATE_REFUSED"
	FailureLaunchExitNonzero     = "LAUNCH_EXIT_NONZERO"
)
View Source
const (
	Planned           = "planned"
	Applied           = "applied"
	Skipped           = "skipped"
	Failed            = "failed"
	Pending           = "RELAUNCH_PENDING_CONTINUITY"
	RateLimited       = "RELAUNCH_RATE_LIMITED"
	IdentityChanged   = "RELAUNCH_IDENTITY_CHANGED"
	Unproven          = "RELAUNCH_UNPROVEN"
	CensusUnavailable = "RELAUNCH_CENSUS_UNAVAILABLE"
	AgentPresent      = "RELAUNCH_AGENT_PRESENT"
	DuplicateAgents   = "DUPLICATE_AGENTS"
	NoProfile         = "NO_LAUNCHER_PROFILE"
	LaunchFailed      = "RELAUNCH_FAILED"
	VerifyFailed      = "RELAUNCH_UNVERIFIED"
	RollbackFailed    = "RELAUNCH_CLEANUP_UNCONFIRMED"
	StateUnavailable  = "RELAUNCH_STATE_UNAVAILABLE"
	// 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

View Source
var ErrCensusUnavailable = errors.New("complete relaunch census unavailable")

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 Binding

type Binding struct {
	AppID, WorkerID, SessionID, Server string
	Usable                             bool
}

Binding is the identity read from the target worktree, never the caller's.

type Desired

type Desired struct {
	Target
	SweepMode, State, Reason string
}

Desired is a fresh server answer. The adapter canonicalizes its worktree.

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) Load

func (s *FileJournal) Load(worker string) (Record, error)

func (*FileJournal) Save

func (s *FileJournal) Save(worker string, rec Record) error

func (*FileJournal) Sweep

func (s *FileJournal) Sweep() uint64

type Journal

type Journal interface {
	Load(string) (Record, error)
	Save(string, Record) error
}

Journal is already locked by the run-level adapter; reads never create it.

type LaunchError

type LaunchError struct {
	Code string
	Err  error
}

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 {
	PIDs   []int
	Proven bool
}

Observation is strict evidence. A default/partial result cannot prove zero.

type Prepared

type Prepared struct {
	Fingerprint string
	Launch      func(context.Context) (Agent, error)
}

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 {
	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.

func (Runner) Execute

func (r Runner) Execute(ctx context.Context, t Target) (out Result, err error)

Execute proves a current target, requires two consecutive absent observations, persists its attempt before launching, then verifies exactly the process this launch made. A failure can roll back only the returned Agent.

type Target

type Target struct{ AppID, HostID, WorkerID, SessionID, Server, Worktree string }

Target is an exact, already-bound identity, not a request to bind one.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL