driver

type Capabilities ¶

type Capabilities struct {
	// LoadSession: LoadSession works, so a follow-up after the worker ended
	// can continue its conversation.
	LoadSession bool
	// FollowUpPrompts: a live session takes further prompts, so a follow-up
	// is delivered into the same session rather than as a new attempt.
	FollowUpPrompts bool
	// PermissionCallback: the agent asks, and PermissionPolicy.Decide answers
	// each request. False for a spawn driver, whose permissions are frozen
	// into flags from PermissionPolicy.Rules before the process starts.
	PermissionCallback bool
}

Capabilities are what a driver advertises, as an ACP agent advertises its own at initialize.

type Command ¶

type Command struct {
	Path string
	Args []string
	Env  []string
	Dir  string
}

Command is a process to run: path, argv (without the path) and the whole environment.

type DirectLauncher ¶

type DirectLauncher struct{}

DirectLauncher runs the worker as it is, in the scope's directory.

func (DirectLauncher) Launch(_ context.Context, req LaunchRequest) (Launched, error)

func (DirectLauncher) Receipts(context.Context, string) ([]Receipt, error)

type Driver ¶

type Driver interface {
	// Name is the driver's name as connect.json and the ledger spell it:
	// "claude", "codex", "acp".
	Name() string
	// Capabilities says what the driver supports beyond NewSession and Prompt.
	Capabilities() Capabilities
	// NewSession starts a worker and opens a session in cfg.Cwd. The worker
	// is announced through cfg.Started as soon as its process exists, before
	// the session is opened on top of it (invariant 7).
	//
	// An error that wraps ErrNotStarted means no process ever existed, and
	// the connector may retry the start once. Any other error from a start
	// that launched a process wraps a *StartError carrying that process, whose
	// group the driver has already asked to end: the connector confirms it
	// gone (ConfirmGroupGone) before it settles anything, however long the
	// driver's own handshake took to fail.
	NewSession(ctx context.Context, cfg SessionConfig) (Session, error)
	// LoadSession reopens a session by the id an earlier Session reported,
	// where Capabilities().LoadSession is true. Its errors read as
	// NewSession's, and leave no process behind either.
	LoadSession(ctx context.Context, cfg SessionConfig, sessionID string) (Session, error)
}

Driver starts and reloads sessions for one kind of coding agent.

type Exit ¶

type Exit struct {
	// Code is the exit status, or -1 when a signal ended the process.
	Code int
	// Signaled is true when a signal ended it.
	Signaled bool
	// Err is a failure to wait on the process at all.
	Err error
}

Exit is how a worker ended.

type LaunchRequest ¶

type LaunchRequest struct {
	Scope   Scope
	Command Command
}

LaunchRequest is a worker command and its scope.

type Launched ¶

type Launched struct {
	Command Command
	// WorkDir is the directory the worker works in: Scope.WorkDir for the
	// direct launcher, a broker-owned scope under a sandbox.
	WorkDir string
}

Launched is what runs.

type Launcher ¶

type Launcher interface {
	// Launch returns the command that actually runs and the directory it runs
	// in. A launcher refuses a request whose scope it cannot honor.
	Launch(ctx context.Context, req LaunchRequest) (Launched, error)
	// Receipts are what the launcher confirms the worker did, for the attempt
	// the scope named. The direct launcher confirms nothing.
	Receipts(ctx context.Context, attemptID string) ([]Receipt, error)
}

Launcher wraps the worker command: the seam where a sandbox launcher (sandbox-run) takes the dispatch. Scopes in, working directory and receipts out.

type MCPServer ¶

type MCPServer struct {
	// Name is the server's name as the agent's tools will be prefixed.
	Name string
	// Command is the executable, absolute.
	Command string
	// Args are its arguments. Never a secret: argv is readable by every
	// process on the machine.
	Args []string
	// Env is the server's whole environment, KEY -> VALUE. Declared
	// explicitly, never counted on to be inherited: some agents pass their
	// own environment down and some pass almost nothing.
	Env map[string]string
}

MCPServer is one stdio MCP server handed to the agent, as ACP's mcpServers[] entry.

type PermissionDecision ¶

type PermissionDecision struct {
	Allow bool
}

PermissionDecision is the policy's answer. A driver answers with the offered option of kind AllowOnce or RejectOnce, and refuses when the kind it needs is not offered.

type PermissionMode ¶

type PermissionMode string

PermissionMode is the connector's name for an agent's permission mode. A driver maps it to the agent's own mode id and verifies the agent reports that id back.

const (
	// ModeEdits allows edits, and refuses, without asking anyone, whatever
	// the rules do not allow. It bounds where an edit may land no further
	// than the agent's own sandbox does.
	ModeEdits PermissionMode = "edits"
	// ModeAnything allows every tool the agent has, commands included,
	// without asking anyone: dangerous mode. The worker runs with the
	// operator's own authority on this computer, and nothing but the agent's
	// judgment stands between a request and a command.
	ModeAnything PermissionMode = "anything"
)

type PermissionOption ¶

type PermissionOption struct {
	ID   string
	Kind PermissionOptionKind
}

PermissionOption is one choice the agent offers.

type PermissionOptionKind ¶

type PermissionOptionKind string

PermissionOptionKind is ACP's option kind.

const (
	AllowOnce    PermissionOptionKind = "allow_once"
	AllowAlways  PermissionOptionKind = "allow_always"
	RejectOnce   PermissionOptionKind = "reject_once"
	RejectAlways PermissionOptionKind = "reject_always"
)

type PermissionPolicy ¶

type PermissionPolicy interface {
	// Decide answers one request, for drivers that ask
	// (Capabilities.PermissionCallback).
	Decide(ctx context.Context, req PermissionRequest) PermissionDecision
	// Rules is the same policy, pre-decided, for drivers whose permissions
	// are fixed before the worker starts.
	Rules() PermissionRules
}

PermissionPolicy is the connector's answer to what a worker may do. Permission answers are policy, not containment: the worker still runs with the operator's ambient authority, and nothing here is a sandbox.

type PermissionRequest ¶

type PermissionRequest struct {
	ToolCallID string
	Tool       string
	Kind       ToolKind
	// Locations are the paths the call touches, where the agent says.
	Locations []string
	// Options are the choices the agent offers. A driver selects by kind,
	// never by id or label: ids are not portable across agents.
	Options []PermissionOption
}

PermissionRequest is ACP's session/request_permission, reduced to what a policy decides on.

type PermissionRules ¶

type PermissionRules struct {
	// Mode is the asking mode the agent must run in and confirm.
	Mode PermissionMode
	// AllowKinds are the tool kinds allowed without asking, besides edits.
	AllowKinds []ToolKind
	// AllowMCPServers are the MCP servers whose every tool is allowed.
	AllowMCPServers []string
}

PermissionRules is a policy pre-decided.

It names no directory. The connector's policy bounded edits to the working directory while a project was routed to one; with the routes gone the only directory left is wherever the operator started the connector, and a bound that moves with that is a guarantee in name and an accident in behavior. What confines a worker to a directory now is the agent's own sandbox (Codex's workspace-write) or the sandbox launcher being built separately — not this.

type Preflight ¶

type Preflight struct {
	// Product is the worker's name for a person: "Claude Code".
	Product string
	// Version is what the worker said its version is; empty when it did not
	// start.
	Version string
	Checks  []PreflightCheck
}

Preflight is what a worker's preflight found.

func (p Preflight) Failed() (PreflightCheck, bool)

type PreflightCheck ¶

type PreflightCheck struct {
	Name    string
	Status  PreflightStatus
	Message string
	// Hint is the fix, where one is known.
	Hint string
}

PreflightCheck is one question a preflight asked.

type PreflightStatus ¶

type PreflightStatus string

PreflightStatus is how a check went. A warning is something the preflight could not settle; it never stops anything.

const (
	PreflightPass PreflightStatus = "pass"
	PreflightFail PreflightStatus = "fail"
	PreflightWarn PreflightStatus = "warn"
)

type Preflighter ¶

type Preflighter interface {
	Preflight(ctx context.Context, policy PermissionPolicy) Preflight
}

Preflighter is a driver that can check its worker before any work is given to it.

type ProbeResult ¶

type ProbeResult struct {
	Stdout, Stderr string
	// Exit is the exit status; -1 when the program did not exit on its own.
	Exit int
	// NotFound is a program PATH does not have.
	NotFound bool
	// TimedOut is a program that did not answer in time.
	TimedOut bool
	// Err is why the program could not be run, when it could not.
	Err error
}

ProbeResult is one short run of a worker's program.

func RunProbe(ctx context.Context, cmd Command, timeout time.Duration) ProbeResult

type Process ¶

type Process struct {
	// PID is the process's id; zero when there is none to signal.
	PID int
	// PGID is its process group, which Close signals. A driver starts every
	// worker as the leader of a new group, so PGID == PID.
	PGID int
	// StartedAt is when the process started, to tell it from a later one
	// that reused its id.
	StartedAt time.Time
	// StartedExact is true when StartedAt is the kernel's own start time for
	// the pid, which is what an identity is compared by. False is a
	// wall-clock stamp the driver took around the fork because the kernel
	// could not be asked: readable, but not an identity, and the one-owner
	// rule signals nothing and releases nothing on one (ErrIdentityUnknown).
	StartedExact bool
}

Process is a worker process the connector started.

func LookupProcess(pid int) (Process, error)

func StartedProcess(err error) Process

type PromptResult ¶

type PromptResult struct {
	Stop TurnStop
	// Refusals are the permissions refused during the turn (invariant 3).
	Refusals []Refusal
	// Usage is the turn's token use, where the agent reports it.
	Usage Usage
}

PromptResult is a finished turn.

type Receipt ¶

type Receipt struct {
	Kind string
	ID   int64
	URL  string
}

Receipt is something a launcher confirms a worker posted.

type Redaction ¶

type Redaction struct {
	// Secrets are values removed wherever they appear: a task token, an
	// agent credential.
	Secrets []string
	// Env is an environment, as KEY=VALUE, whose values are removed unless
	// BaseEnv names them.
	Env []string
	// Dirs are directories any path under which is removed: the state and
	// runtime directories.
	Dirs []string
}

Redaction names what a Redactor takes out.

func (r Redaction) With(more Redaction) Redaction

type Redactor ¶

type Redactor struct {
	// contains filtered or unexported fields
}

Redactor applies a Redaction. Build one with NewRedactor; it is safe for concurrent use.

func NewRedactor(r Redaction) *Redactor

func (r *Redactor) Err(err error) error

func (r *Redactor) Handler(h slog.Handler) slog.Handler

func (r *Redactor) Lines(text string) []string

func (r *Redactor) Sanitize(s string) string

func (r *Redactor) Stderr(text string) string

type Refusal ¶

type Refusal struct {
	// ToolCallID is the agent's id for the call.
	ToolCallID string
	// Tool is the tool's name or ACP kind; never its input.
	Tool string
}

Refusal is one permission the policy refused.

type RefusalRecorder ¶

type RefusalRecorder interface {
	RecordRefusal(ctx context.Context, r Refusal) error
}

RefusalRecorder records a refusal at the moment a driver makes or observes it (see "Refusals" above). RecordRefusal must not block for long: a driver calls it on the goroutine that reads the agent's stream.

type Scope ¶

type Scope struct {
	TaskID    int64
	AttemptID string
	// EventIDs are the events the task may cover. Only the originating event
	// has been handed to the worker when the session starts; the others are
	// exposed as they are prompted.
	EventIDs []int64
	// WorkDir is the directory the worker runs in: the connector's own, the
	// one it was started in. It is where the process starts, not a bound on
	// where it may write.
	WorkDir string
	// SocketDir holds the task token's unix socket, which the worker's MCP
	// server dials. A launcher that confines a worker must let it reach this
	// directory, or the worker's MCP server cannot be handed its token. It is
	// SessionConfig.PrivateDir in the ordinary case, and a short directory of
	// the connector's own where a socket path under PrivateDir would be
	// longer than a unix socket takes.
	SocketDir string
	Class     string
}

Scope is what a worker is for, as the launcher is told.

type Session ¶

type Session interface {
	// ID is the agent's session id (ACP sessionId, Claude Code's session_id).
	// It is known when NewSession returns.
	ID() string
	// Process is the worker's process, or the zero Process when the session
	// runs somewhere the connector cannot signal.
	Process() Process
	// Prompt sends one prompt and blocks until the turn ends. The first
	// prompt of a session is its handshake: a driver that verifies the
	// agent's mode on it returns ErrUnsafeMode and ends the session. A ctx
	// that ends makes Prompt return ctx's error without ending the turn; use
	// Cancel for that.
	Prompt(ctx context.Context, prompt string) (PromptResult, error)
	// Updates streams the session's progress. It is closed when the session
	// ends. A consumer that stops reading does not stall the agent: a driver
	// drops updates rather than block.
	Updates() <-chan Update
	// Cancel ends the turn in flight. Prompt then returns TurnCanceled.
	// With no turn in flight it does nothing.
	Cancel(ctx context.Context) error
	// Close ends the session and its worker: the process group is signaled,
	// given grace, and killed. Idempotent; safe concurrently with Prompt,
	// which then returns an error.
	Close() error
	// Done is closed once the worker has exited, however it exited.
	Done() <-chan struct{}
	// Exit is how the worker exited; meaningful once Done is closed.
	Exit() Exit
}

Session is one live conversation with a worker.

type SessionConfig ¶

type SessionConfig struct {
	// Cwd is the directory the session runs in, absolute: the connector's
	// own, the one it was started in.
	Cwd string
	// Env is the worker process's whole environment, as KEY=VALUE. Nothing
	// else is inherited (invariant 1). BuildEnv makes one from an allowlist.
	Env []string
	// MCPServers are the only MCP servers the agent gets. A driver makes the
	// agent ignore every other MCP configuration it would otherwise load.
	MCPServers []MCPServer
	// Policy answers permissions.
	Policy PermissionPolicy
	// Launcher wraps the worker command. Nil means DirectLauncher.
	Launcher Launcher
	// Scope is what the launcher is told the worker is for.
	Scope Scope
	// SocketDir is the directory holding the task token's unix socket, which
	// the worker's MCP server dials. It is PrivateDir in the ordinary case
	// and a short directory of the connector's own where a socket path under
	// PrivateDir would be longer than a unix socket takes. It is in Scope
	// too, which is what a launcher is given.
	SocketDir string
	// PrivateDir is an owner-only directory the driver may write session
	// files into (an MCP config, say). The driver removes what it wrote when
	// the session is closed; the dispatcher sweeps the directory on start.
	PrivateDir string
	// Refusals records every refusal at the moment it is made or observed.
	// Nil records nothing; the dispatcher always sets it.
	Refusals RefusalRecorder
	// Started is called once with the worker's process as soon as that
	// process exists — the fork has returned and the group is the worker's —
	// and before whatever handshake the driver runs on top of it (invariant
	// 7). It is how the connector learns the process group while NewSession
	// is still running, which is what arms the task token's socket in time
	// for an agent that starts its MCP servers during its own handshake:
	// arming only once NewSession returned deadlocks such an agent against a
	// token the connector cannot hand over until the handshake it is blocking
	// has finished. It must not block: a driver calls it on the goroutine
	// that is starting the session. Nil announces nothing.
	Started func(Process)
	// Redaction is what the driver takes out of every error it returns and
	// every text an update or a stderr tail carries (redact.go). The driver
	// adds the environment it builds, its MCP servers' environments and
	// PrivateDir to it.
	Redaction Redaction
}

SessionConfig is everything a driver needs to start a session. The dispatcher builds it from the task's record; the driver adds nothing of its own beyond its binary and its flags.

type StartError ¶

type StartError struct {
	Process Process
	Err     error
}

StartError is a start that failed after it launched a process. The driver has asked the process's group to end; the connector owns confirming it gone before it settles the attempt.

func (e *StartError) Error() string

func (e *StartError) Unwrap() error

type ToolKind ¶

type ToolKind string

ToolKind is ACP's tool kind.

const (
	ToolRead    ToolKind = "read"
	ToolEdit    ToolKind = "edit"
	ToolDelete  ToolKind = "delete"
	ToolMove    ToolKind = "move"
	ToolSearch  ToolKind = "search"
	ToolExecute ToolKind = "execute"
	ToolThink   ToolKind = "think"
	ToolFetch   ToolKind = "fetch"
	ToolOther   ToolKind = "other"
)

type ToolStatus ¶

type ToolStatus string

ToolStatus is a tool call's status.

const (
	ToolPending    ToolStatus = "pending"
	ToolInProgress ToolStatus = "in_progress"
	ToolCompleted  ToolStatus = "completed"
	ToolFailed     ToolStatus = "failed"
)

type TurnStop ¶

type TurnStop string

TurnStop is why a prompt turn ended: ACP v1's stop reasons.

const (
	// TurnEndTurn is the agent finishing its turn.
	TurnEndTurn TurnStop = "end_turn"
	// TurnMaxTokens is the token limit.
	TurnMaxTokens TurnStop = "max_tokens"
	// TurnMaxTurnRequests is the agent's own request budget for the turn.
	TurnMaxTurnRequests TurnStop = "max_turn_requests"
	// TurnRefusal is the agent refusing to continue.
	TurnRefusal TurnStop = "refusal"
	// TurnCanceled is a cancel the connector asked for, and only that
	// (invariant 3). The value is ACP's spelling.
	TurnCanceled TurnStop = "cancelled" //nolint:misspell // ACP's wire value
)

type Update ¶

type Update struct {
	Kind UpdateKind
	At   time.Time

	// ToolCallID, Tool, ToolKind and Status describe a tool call.
	ToolCallID string
	// Tool is the tool's name ("Bash", "mcp__basecamp__basecamp_connect").
	Tool     string
	ToolKind ToolKind
	Status   ToolStatus

	// Usage is set on UpdateUsage.
	Usage *Usage
	// Chars is the length of an agent message chunk, whose text is not
	// carried.
	Chars int
	// Allowed is set on UpdatePermission: whether the policy allowed it.
	Allowed bool
}

Update is one piece of progress. It carries no content (invariant 6): progress is for liveness, budgets and the ledger, never for reading what the agent said.

type UpdateKind ¶

type UpdateKind string

UpdateKind names a session update, as ACP's sessionUpdate does.

const (
	UpdateToolCall          UpdateKind = "tool_call"
	UpdateToolCallUpdate    UpdateKind = "tool_call_update"
	UpdateUsage             UpdateKind = "usage_update"
	UpdateAgentMessageChunk UpdateKind = "agent_message_chunk"
	// UpdatePlan is optional: no adapter the spike ran emitted one.
	UpdatePlan UpdateKind = "plan"
	// UpdatePermission is a permission decision the driver made or observed.
	UpdatePermission UpdateKind = "permission"
)

type Usage ¶

type Usage struct {
	InputTokens  int64
	OutputTokens int64
	// ContextUsed and ContextSize are ACP usage_update's {used, size}, where
	// known.
	ContextUsed int64
	ContextSize int64
}

Usage is token accounting.

type Worker ¶

type Worker struct {
	// contains filtered or unexported fields
}

One owner, one release point ¶

This is the connector's rule for a task's process tree and its ledger record. Both belong to one owner — the attempt — and are released at one point, in this order:

1. Every worker starts as the leader of its own process group (StartWorker), so the tree it makes can be signaled as one.
2. A cancel, a deadline or a shutdown ends that group: SIGTERM, a bounded wait, then SIGKILL, by process group id and never by name (Terminate).
3. The group is then CONFIRMED gone (ConfirmGroupGone). Only after that may the attempt be settled and its record made terminal.
4. A group that cannot be confirmed gone — members left, a pid whose identity cannot be established, a platform that cannot say — leaves the record HELD: live in the ledger, its conversation and a worker slot still its own, for a person to settle. Never terminal, never released.
5. A restart reaps by the same rule (TerminateRecorded, then the same confirmation), and asks OwnsWorker first: a pid is not an identity, so ownership is the pid AND the kernel's own start time for it, compared exactly. Everything that acts on a recorded worker asks OwnsWorker rather than testing a pid of its own: in this card, recovery (through TerminateRecorded) and the release point's second confirmation; any later one — status, redispatch, discard, hold — the same way. Every group signal that follows the first asks again (signalRecordedGroup): ownership established before a grace period is not ownership after it, because a pid freed during the grace can be leading another group by the time the kill goes out.

The one thing this cannot cover is a descendant that leaves the group by calling setsid: it is outside every group signal, and the connector can only avoid waiting on it (WaitDelay, CloseStdout). Containment is the sandbox launcher's job, not this rule's.

Cards that start workers or settle records use the functions here rather than writing their own.

What a driver promises, and where each promise can still be broken ¶

The rule above is about the release point. These are the promises the rest of the boundary makes, each with the paths that can still break it named, so a reader does not have to take "held everywhere" on trust.

## A worker's lifetime

• After a start returns a Session, a process group exists whose leader is the worker, and the connector owns it: Process() names it, and nobody else may signal it.
• After a start returns an ERROR, no process of that session exists. Either none was started, or the driver ended the one it started, whole group, before returning (Driver.NewSession). ErrNotStarted says more: none ever existed, so the connector may retry the start once.
• Cancel ends the turn, not the worker, and never blocks on a worker that has stopped reading its input: it gives up instead, and says so.
• Close ends the session and its group — signal, bounded wait, kill — and is idempotent. It never waits on the worker's cooperation.
• A worker that goes with a turn in flight is classified by how it went: one that exited on its own with a non-zero status FAILED, and one that vanished — signaled by someone else, or gone with no status the connector observed — is LOST.
• Descriptors have an owner too. A start that fails closes every descriptor it opened; a terminated worker's output pipe is closed by the Worker once its reader has had the same bound to drain it that Wait gives a stray descendant, whether or not the reader closed it.
• After a crash of the connector, the group survives. A later process identifies it by OwnsWorker (pid AND recorded start time), ends it with TerminateRecorded, and confirms with ConfirmGroupGone before anything is settled or released.

Where this can still be broken: a descendant that calls setsid leaves the group and no signal reaches it (there is no portable way to see it, and containment is the sandbox launcher's); a driver that returns an error after leaving a process behind breaks the start promise, which is why it is written on the method rather than left to each driver; and on a platform where process start times cannot be read — or for a worker whose start time the kernel would not give — OwnsWorker refuses to answer and nothing may be settled; the run command refuses to start on such a platform at all.

## Credentials

Two secrets exist around a worker, and each has one carriage.

• The agent's Basecamp credential stays in the CLI's credential store. It is never in any environment, argv, file or log the connector writes; the worker's MCP server, running as the agent's profile, reads it from that store itself.
• A task token lives from LaunchTask to the end of its task. The ledger keeps only its hash. It crosses only to the worker's MCP server, and never to the agent process: the dispatcher serves it over a unix socket in the attempt's owner-only runtime directory, once per start of that server (an MCP host that restarts a stdio server re-runs it, so the bridge asks again) and at most connector.MaxTokenHandoffs times, only to a peer of this user in the worker's process group or descended from its leader (connector.ServeTaskToken), and `basecamp connect worker-mcp` passes it on to `basecamp mcp` over an inherited descriptor. It is never in an environment, never in argv, never in a file, and never in a log or a dispatch line.
• The agent's own credential (ANTHROPIC_API_KEY, where one is used) is in the agent's environment because the agent needs it, and nowhere else the connector writes.

drivertest.RequireNoSecret and RequireNoSecretFilesDuring are the checks: the environment, argv, written text, and — watched continuously, so a file that lives milliseconds is still caught — every file under the working and session directories. What comes back OUT of a worker is the redaction rule's (redact.go), and drivertest.RequireRedacted is its check.

Where this can still be broken: an agent may copy what it was handed anywhere its tools can write, and any process of this user in the worker's group could take the token first — the group is the agent's own tree.

## The environment a worker and its MCP servers get

• The connector owns both. SessionConfig.Env is the worker's whole environment and MCPServer.Env is each server's, and each is an allowlist the dispatcher built by name (BuildEnv over BaseEnv, plus the variables a driver names for its own agent).
• No credential is in either: the agent's Basecamp credential stays in the CLI's store, and the task token travels over the socket.
• No secret is ever in argv, which every process on the machine can read.

Where this can still be broken: an agent may ADD to the environment it hands its MCP servers — Claude Code passes its own whole environment down, which carries the agent's own credentials — so the declared environment is a floor, not a ceiling. The bridge (`basecamp connect worker-mcp`) execs `basecamp mcp` with the declared environment only, so the connector's own server does not keep them; a third-party MCP server the operator adds to a worker would inherit them regardless, and the connector ships none.

## When an attempt may be adopted, settled or released

• Adoption links a reply to an event; it is never evidence that work finished, and never makes an outcome succeeded. It needs exactly one reply by the agent at that destination after the event's own acknowledgement and before any later instruction's, it is never the worker's own acknowledgement, and a listing the scan limit cut short adopts nothing.
• An attempt is settled and its record made terminal at one point (Dispatcher.release), and only after the group is confirmed gone and the ledger has taken the settlement.
• An attempt that cannot be confirmed or cannot be settled stays live and holds its conversation and one of the connector's worker slots, until a person settles it.

Where this can still be broken: adoption trusts Basecamp's ordering of replies against this machine's clock for "after the acknowledgement", so a clock far behind the server's could see a reply as later than it was — the exactly-one rule and the acknowledgement exclusion are what keep that from mattering; and a person who writes to the ledger by hand can of course strand anything.

Worker is a process a spawn driver started: the leader of its own process group, with its stdin and stdout piped and its stderr kept, redacted, for diagnosis. Every spawn driver starts its agent through StartWorker, so the rules for processes (invariants 1, 4 and 5) live in one place.

func StartWorker(ctx context.Context, cfg SessionConfig, cmd Command) (*Worker, error)

func (w *Worker) CloseStdout()

func (w *Worker) Done() <-chan struct{}

func (w *Worker) Exit() Exit

func (w *Worker) Process() Process

func (w *Worker) StderrLines(r *Redactor) []string

func (w *Worker) StderrTail(r *Redactor) string

func (w *Worker) Stdin() io.WriteCloser

func (w *Worker) Stdout() io.Reader

func (w *Worker) Terminate(grace time.Duration)

type WorkerProbe ¶

type WorkerProbe struct {
	// Product is the worker's name for a person: "Claude Code".
	Product string
	// Binary is the program a session starts, found on PATH as a session
	// finds it.
	Binary string
	// Env is the environment a session gets.
	Env []string
	// Help is the arguments that list the flags Flags must be among.
	Help []string
	// Flags are the flags a session passes.
	Flags []string
	// Update is how a person updates the worker.
	Update string
	// Login is the arguments that ask whether the worker is logged in, with
	// no model call.
	Login []string
	// LoggedIn reads Login's answer: whether the worker said it is logged in,
	// and whether it said anything that could be read.
	LoggedIn func(ProbeResult) (loggedIn, known bool)
	// LoginFix is what a person does when the worker is logged out.
	LoginFix string
	// LoginWarns is a login check that never fails: its answer is a guess.
	LoginWarns bool
	// Timeout bounds each run; PreflightTimeout when zero.
	Timeout time.Duration
	// Run runs one probe; RunProbe when nil. A test seam.
	Run func(ctx context.Context, cmd Command, timeout time.Duration) ProbeResult
}

WorkerProbe is how one driver's preflight runs.

func (w WorkerProbe) Check(ctx context.Context) Preflight