fleet

type Agent struct {
	Name        string   `yaml:"name" json:"name"` // the primary nickname
	Aliases     []string `yaml:"aliases,omitempty" json:"aliases,omitempty"`
	Display     string   `yaml:"display,omitempty" json:"display,omitempty"`
	Description string   `yaml:"description,omitempty" json:"description,omitempty"`

	// Nick is the agent's human name — the one you say out loud. Leave it
	// empty and the catalog assigns one deterministically from the binding,
	// so every agent has a memorable handle without anyone naming it.
	Nick string `yaml:"nick,omitempty" json:"nick,omitempty"`

	Tool  string `yaml:"tool" json:"tool"`   // → Tool.Name
	Model string `yaml:"model" json:"model"` // → Model.Name

	// A CASCADE agent (band_source: cascade) is not a plain tool:model binding.
	// It runs a cheap Base agent and, when the base gets stuck, escalates through
	// Escalation (a ladder of agent names, tried in order — e.g. an L3 then an L4)
	// for a content-full steer. It SERVES at Band via that ladder while running
	// cheap most of the time. When Base is set, Model is ignored.
	Base       string   `yaml:"base,omitempty" json:"base,omitempty"`
	Escalation []string `yaml:"escalation,omitempty" json:"escalation,omitempty"`

	// Band + BandSource are the SERVED band of a cascade agent (BandSource
	// "cascade") — the level the ladder REACHES, not the base model's peg. This
	// is the one legitimate agent-level band: it is the cascade's contract, not a
	// stored model peg that would rot. For a plain tool:model agent these are
	// empty and the band is inherited from the model, as always.
	Band       int    `yaml:"band,omitempty" json:"band,omitempty"`
	BandSource string `yaml:"band_source,omitempty" json:"band_source,omitempty"`

	Role        *AgentRole        `yaml:"role,omitempty" json:"role,omitempty"`
	Ledger      *AgentLedger      `yaml:"ledger,omitempty" json:"ledger,omitempty"`
	Instruction *AgentInstruction `yaml:"instruction,omitempty" json:"instruction,omitempty"`
	Functions   []string          `yaml:"functions,omitempty" json:"functions,omitempty"`

	// ClonedFrom and ClonedAt record that this agent was BRANCHED off another,
	// and when.
	//
	// An agent is a singleton identity — one conversation store, one kb
	// attribution, one bus cursor — so two concurrent tasks cannot be given to
	// one agent without mixing their context, and mixed context produces
	// confidently wrong answers. Parallelism is therefore expressed as MORE
	// AGENTS, and a clone is how you get one that starts from somewhere rather
	// than from nothing: it inherits its parent's context as of ClonedAt and
	// diverges from that moment on.
	//
	// The provenance is kept because the alternative is a fleet of same-binding
	// agents with no way to tell which was the original, which was branched off
	// what, or when their histories parted.
	ClonedFrom string `yaml:"cloned_from,omitempty" json:"cloned_from,omitempty"`
	ClonedAt   string `yaml:"cloned_at,omitempty" json:"cloned_at,omitempty"`

	// Ephemeral marks a clone minted for ONE task, to be removed when that task
	// closes. It is hidden from `agents list` unless --all, because a fleet
	// roster listing every in-flight task's worker is a roster nobody reads.
	// Task, when set, names the work it was minted for.
	Ephemeral bool   `yaml:"ephemeral,omitempty" json:"ephemeral,omitempty"`
	Task      string `yaml:"task,omitempty" json:"task,omitempty"`

	// AutoNick and Derived are computed by the catalog at load: the
	// assigned human name (when Nick is empty) and the floating family
	// alias (`claude-opus` for a binding on `opus5`). Both are functions
	// of the whole catalog, so neither is ever persisted.
	AutoNick string   `yaml:"-" json:"auto_nick,omitempty"`
	Derived  []string `yaml:"-" json:"derived,omitempty"`

	Ring assetring.Ring `yaml:"-" json:"ring"`
}

type AgentFile struct {
	New      bool    `yaml:"new,omitempty" json:"new,omitempty"`
	LogLevel string  `yaml:"log_level,omitempty" json:"log_level,omitempty"`
	Agents   []Agent `yaml:"agents" json:"agents"`
}

type AgentInstruction struct {
	Content string `yaml:"content,omitempty" json:"content,omitempty"`
}

type AgentLedger struct {
	Reliability string `yaml:"reliability,omitempty" json:"reliability,omitempty"`
	Notes       string `yaml:"notes,omitempty" json:"notes,omitempty"`
}

type AgentRole struct {
	Skills       []string `yaml:"skills,omitempty" json:"skills,omitempty"`
	AllowedTools []string `yaml:"allowed_tools,omitempty" json:"allowed_tools,omitempty"`
	Scope        string   `yaml:"scope,omitempty" json:"scope,omitempty"`
}

type AliasCollision struct {
	Kind  string
	Name  string
	Holds []string // canonical names of the entries claiming it
}

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

type Check struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
	OK   bool   `json:"ok"`
	// Skipped marks an entry that was never a candidate — a harness we
	// recognize but do not drive, say. Not usable and not a failure: a
	// healthy host must not report an error for a tool it never intended
	// to launch.
	Skipped bool   `json:"skipped,omitempty"`
	Reason  string `json:"reason"`
	Detail  string `json:"detail,omitempty"` // version, target id, launch argv
	// Warn carries something true but not disqualifying — an entry that
	// works yet is missing something a caller may be counting on. It never
	// affects OK: a warning that failed the check would just get silenced.
	Warn string `json:"warn,omitempty"`
}

type CloudClient struct {
	BaseURL string
	Token   string
	HTTP    *http.Client
}

type CloudConfig struct {
	URL   string
	Token string
}

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

type ContextCloner func(parent, clone Agent) (note string, err error)

type EventsDone struct {
	// Field is the JSON key carrying the event kind — "type" for most, "event"
	// for agy. Empty defaults to "type", which is the majority spelling.
	Field string `yaml:"field,omitempty" json:"field,omitempty"`
	// Values are the kinds that mean the turn ENDED. Any match is a boundary.
	Values []string `yaml:"values,omitempty" json:"values,omitempty"`
}

type EventsOutcome struct {
	// Path is a dotted path into the terminal event object — "is_error" for
	// claude, "result.status" for agy. Nesting differs per tool, so the path is
	// declared rather than assumed.
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
	// OK are the values at Path that MEAN success, rendered as strings so one
	// declaration covers a bool (`false`) and an enum (`SUCCESS`) alike.
	OK []string `yaml:"ok,omitempty" json:"ok,omitempty"`
}

type Host struct {
	Name    string   `yaml:"name" json:"name"`
	Aliases []string `yaml:"aliases,omitempty" json:"aliases,omitempty"`
	Display string   `yaml:"display,omitempty" json:"display,omitempty"`

	// Address is where the machine actually answers — a DNS name or an
	// address literal. Empty means "resolve the name itself".
	Address string `yaml:"address,omitempty" json:"address,omitempty"`
	// SSHUser is the account name on THIS host. It is per-host on purpose:
	// the local $USER usually does not exist on the remote box.
	SSHUser string `yaml:"ssh_user,omitempty" json:"ssh_user,omitempty"`
	SSHPort int    `yaml:"ssh_port,omitempty" json:"ssh_port,omitempty"`
	// LANEndpoint is a service URL reachable only from the same network.
	LANEndpoint string `yaml:"lan_endpoint,omitempty" json:"lan_endpoint,omitempty"`
	Notes       string `yaml:"notes,omitempty" json:"notes,omitempty"`

	Ring assetring.Ring `yaml:"-" json:"ring"`
}

type LiveProbe func(ctx context.Context, agent string, timeout time.Duration) (status, note string, ok bool)

type Model struct {
	Name    string   `yaml:"name" json:"name"` // the alias clients pass
	Aliases []string `yaml:"aliases,omitempty" json:"aliases,omitempty"`
	Display string   `yaml:"display,omitempty" json:"display,omitempty"`
	// Kind is HOW YOU AUTHENTICATE: subscription | api | local.
	Kind string `yaml:"kind,omitempty" json:"kind,omitempty"`

	// Billing is HOW YOU PAY: metered | flat | free. Optional — when empty it is
	// derived from Kind by BillingMode(), reproducing the old collapsed behaviour, so
	// no existing model needs touching.
	//
	// It exists because z.ai's GLM Coding Plan is flat-rate billing over an API key,
	// and no single value of Kind can say that. See the constants above.
	Billing string `yaml:"billing,omitempty" json:"billing,omitempty"`

	Source string `yaml:"source,omitempty" json:"source,omitempty"`

	Provider  string `yaml:"provider,omitempty" json:"provider,omitempty"`
	BaseURL   string `yaml:"base_url,omitempty" json:"base_url,omitempty"`
	APIKeyRef string `yaml:"api_key_ref,omitempty" json:"api_key_ref,omitempty"`
	// UpstreamID is the provider-side model id — the value handed to a
	// tool's --model flag. Its YAML key is `model:`, matching the asset
	// registry's column.
	UpstreamID string `yaml:"model,omitempty" json:"model,omitempty"`

	// ToolIDs override UpstreamID for a specific tool, because THE ID A MODEL
	// ANSWERS TO IS A PROPERTY OF THE TOOL, NOT OF THE MODEL.
	//
	// One model, three spellings, all live today:
	//
	//   aider/opencode  deepseek/deepseek-v4-pro   (litellm wants provider/model)
	//   ycode           deepseek-v4-pro            (it detects the provider itself)
	//   agy             Gemini 3.1 Pro (High)      (a display string, not a slug)
	//
	// Treating UpstreamID as one global value made ycode's bindings dead on
	// arrival: the registry handed it litellm's prefixed form and ycode rejected
	// it, while the same model worked perfectly when ycode was run by hand. That
	// is the whole dead-binding failure mode again, and `agents verify --live`
	// caught it within a minute of the tool being registered.
	//
	// Keyed by TOOL name. Absent → UpstreamID.
	ToolIDs map[string]string `yaml:"ids,omitempty" json:"ids,omitempty"`

	// Family and Version make the canonical name version-explicit. The
	// catalog derives the floating family alias from them: `opus` names
	// whichever member of family `opus` has the highest Version. A record
	// therefore stores `claude:opus5`, which is true forever, while the
	// convenient `opus` re-points on its own when a release lands.
	//
	// Family is declared, never parsed out of the name: `kimi-k2.7-code`
	// and `kimi-k2.6` are separate product lines, and no amount of clever
	// suffix-stripping gets that right.
	Family  string `yaml:"family,omitempty" json:"family,omitempty"`
	Version string `yaml:"version,omitempty" json:"version,omitempty"`

	// Band is the model's capability peg, 1 (basic) to MaxBand (frontier); 0 is
	// unpegged. It is normalized ACROSS providers — a provider's own tier
	// ladder is never mapped positionally, so four vendor tiers may all
	// land in one band. Agents inherit it; they never carry their own.
	Band int `yaml:"band,omitempty" json:"band,omitempty"`

	// BandSource says whether the band was MEASURED or merely DECLARED, and it
	// exists because the fleet has already been burned once by not knowing.
	//
	// "declared" is a considered guess from provider tier + priors. "measured"
	// means the model was run up a difficulty ladder and pegged at the highest
	// rung it reliably cleared — which is the only thing a band actually means.
	//
	// The distinction is load-bearing: a quiz cannot validate a band. Every agent
	// in this fleet scores 5/5 on L1-difficulty questions, so passing an easy test
	// is evidence of nothing. A band is the highest rung you CLEAR, not a score,
	// and until a model has failed something it has not been placed.
	//
	// Empty means declared. Nothing should present an unmeasured band as fact.
	BandSource string `yaml:"band_source,omitempty" json:"band_source,omitempty"`

	// Tier is the provider's own word for its tier, carried from an org
	// overlay. It is not Band and is not routable.
	Tier          string   `yaml:"tier,omitempty" json:"tier,omitempty"`
	Capabilities  []string `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
	Domain        []string `yaml:"domain,omitempty" json:"domain,omitempty"`
	ContextLength int64    `yaml:"context_length,omitempty" json:"context_length,omitempty"`
	Price         float64  `yaml:"price,omitempty" json:"price,omitempty"`

	// Quality is the model's overall capability prior in [0,1]; Spec holds
	// per-capability adjustments where a model is notably stronger or
	// weaker than its tier. CostMicro is the relative per-turn cost the
	// routing objective divides by. All three are read by the capability
	// matrix.
	Quality   float64            `yaml:"quality,omitempty" json:"quality,omitempty"`
	CostMicro int64              `yaml:"cost_micro,omitempty" json:"cost_micro,omitempty"`
	Spec      map[string]float64 `yaml:"spec,omitempty" json:"spec,omitempty"`

	XHosts []ModelHost `yaml:"x_hosts,omitempty" json:"x_hosts,omitempty"`

	// Derived holds names the catalog computed at load — today, the family
	// alias. It is a function of the whole catalog, not of this entry, so
	// it is never persisted (`yaml:"-"`): writing it back would freeze a
	// pointer that is supposed to float.
	Derived []string `yaml:"-" json:"derived,omitempty"`

	Ring assetring.Ring `yaml:"-" json:"ring"`
}

type ModelHost struct {
	Host  string `yaml:"host" json:"host"`
	Owner string `yaml:"owner,omitempty" json:"owner,omitempty"`
}

type Option func(*Config)

type Person struct {
	Handle  string   `yaml:"handle" json:"handle"`
	Aliases []string `yaml:"aliases,omitempty" json:"aliases,omitempty"`
	Display string   `yaml:"display,omitempty" json:"display,omitempty"`
	Email   string   `yaml:"email,omitempty" json:"email,omitempty"`

	// OSUsers maps a host name to this person's account name there. It is
	// deliberately per-host: assuming the local $USER exists on a remote
	// box is the single most common way a cross-host reach fails.
	OSUsers map[string]string `yaml:"os_users,omitempty" json:"os_users,omitempty"`
	// DefaultOSUser is used for hosts absent from OSUsers.
	DefaultOSUser string `yaml:"default_os_user,omitempty" json:"default_os_user,omitempty"`

	Hosts  []string `yaml:"hosts,omitempty" json:"hosts,omitempty"`
	Source string   `yaml:"source,omitempty" json:"source,omitempty"` // local | cloud

	Ring assetring.Ring `yaml:"-" json:"ring"`
}

type SyncResult struct {
	Noun    string `json:"noun"`
	Fetched int    `json:"fetched"`
	Skipped int    `json:"skipped,omitempty"`
	Dir     string `json:"dir"`
}

type Tool struct {
	Name    string   `yaml:"name" json:"name"`
	Kind    string   `yaml:"kind" json:"kind"` // cli | func | web | system
	Aliases []string `yaml:"aliases,omitempty" json:"aliases,omitempty"`
	Display string   `yaml:"display,omitempty" json:"display,omitempty"`
	// Hidden keeps a tool in the registry (still detected, still resolvable by
	// explicit name) but omits it from `bashy tools` list/help unless --all.
	Hidden bool    `yaml:"hidden,omitempty" json:"hidden,omitempty"`
	CLI    ToolCLI `yaml:"cli,omitempty" json:"cli"`
	Quirks string  `yaml:"quirks,omitempty" json:"quirks,omitempty"`

	// Harness scores the capabilities a tool governs regardless of the
	// model behind it (operability, shell, tool-use, isolation). The
	// capability matrix reads these as priors.
	Harness map[string]float64 `yaml:"harness,omitempty" json:"harness,omitempty"`

	Ring assetring.Ring `yaml:"-" json:"ring"`
}

type ToolCLI struct {
	Binary   string        `yaml:"binary,omitempty" json:"binary,omitempty"`
	Versions []ToolVersion `yaml:"versions,omitempty" json:"versions,omitempty"`
	Launch   ToolLaunch    `yaml:"launch,omitempty" json:"launch"`
}

type ToolLaunch struct {
	// Exec is the argv template. {prompt} is replaced by the task text and
	// {model} by the bound model's upstream id. When no model is bound,
	// {model} and the flag token immediately preceding it are dropped, so
	// a template with a model flag degrades exactly to one without.
	Exec string `yaml:"exec,omitempty" json:"exec,omitempty"`
	// Credential declares how this harness authenticates a bound model.
	// "model-provider" grants only the credential named by Model.APIKeyRef, or
	// by Model.Provider when no explicit key reference exists. Values remain in
	// the launcher environment; this field carries names and policy only.
	Credential string `yaml:"credential,omitempty" json:"credential,omitempty"`
	// WorkspaceArg is an optional argv fragment that binds the launched tool to
	// the orchestrator's allocated workspace. {workspace} is replaced by that
	// absolute path. It is rendered immediately after the binary, before the
	// exec template's model and prompt arguments. Tools that do not declare it
	// retain their existing argv exactly.
	WorkspaceArg string `yaml:"workspace_arg,omitempty" json:"workspace_arg,omitempty"`
	// WorkspacePreflightExec is an optional read-only launch template used to
	// ask the tool which PWD/project directory it selected. The launcher supplies
	// a reporting prompt and refuses to start the source-writing invocation
	// unless the reported path equals the allocated workspace.
	WorkspacePreflightExec string `yaml:"workspace_preflight_exec,omitempty" json:"workspace_preflight_exec,omitempty"`
	// VersionProbeExec is an optional provider-declared, read-only command used
	// by fleet capability probing instead of assuming every CLI accepts --version.
	VersionProbeExec string `yaml:"version_probe_exec,omitempty" json:"version_probe_exec,omitempty"`
	// PromptPosition records where the prompt goes for consumers that
	// cannot read the template (cloudbox conductor). Advisory here: the
	// {prompt} placeholder is authoritative.
	PromptPosition string `yaml:"prompt_position,omitempty" json:"prompt_position,omitempty"`
	// TrustPreseed names a config file the host must pre-seed so the CLI
	// does not no-op on a first-run trust prompt.
	TrustPreseed string       `yaml:"trust_preseed,omitempty" json:"trust_preseed,omitempty"`
	Watchdog     ToolWatchdog `yaml:"watchdog,omitempty" json:"watchdog"`

	// SupportsSay marks a tool that CAN be steered mid-run — a capability fact
	// about the tool, MEASURED (pkg/agentpty/steer_live_test.go), not asserted.
	SupportsSay bool `yaml:"supports_say,omitempty" json:"supports_say,omitempty"`

	// ACPExec is the argv template that launches this tool as an ACP AGENT
	// speaking JSON-RPC on stdio. Empty means the tool does not speak ACP and
	// the launcher falls to the next rung.
	//
	// NO {prompt} and NO {model}. The prompt travels in the ACP session rather
	// than argv, which is what gives the transport a real turn boundary. The
	// model is fixed by the binding before the launch: ACP carries no
	// model-selection call, and a bound model refuses the ACP rung outright
	// (see agentlaunch.ACPArgv). A {model} token here renders LITERALLY.
	ACPExec string `yaml:"acp_exec,omitempty" json:"acp_exec,omitempty"`

	// EventsArg is how this tool is told to stream STRUCTURED EVENTS, if it can.
	//
	// This is the difference between a first-party harness and a third-party one,
	// and it is not cosmetic. Without it, bashy decides a turn has ended by
	// WATCHING FOR SILENCE — 25 seconds of no output (see chat.Session.WaitIdle).
	// That heuristic is wrong in both directions: an agent that pauses to think
	// looks finished, and an agent that renders a spinner never does. Every turn
	// also pays the 25 seconds on its way out, which is why `meet --steerable` is
	// a flag and not the default.
	//
	// A tool that declares this gets a real boundary instead: it says `turn.end`,
	// and bashy believes it, because it is a fact the agent reported rather than a
	// silence bashy interpreted.
	//
	// Template with one token: {path}. e.g. `--events {path}`.
	// The events are NDJSON, one object per line, with at minimum:
	//     {"type":"turn.start"} {"type":"tool.call"} {"type":"turn.end", ...}
	EventsArg string `yaml:"events_arg,omitempty" json:"events_arg,omitempty"`

	// EventsStdout is the same capability for tools that stream on STDOUT
	// rather than into a file bashy names.
	//
	// EventsArg above was written for ycode, which takes a path and writes
	// NDJSON there. Every third-party tool measured on the wire does the
	// opposite — claude, codex and agy each stream to stdout and accept no path
	// at all — so declaring EventsArg for them would render a flag that does not
	// exist. Two fields, because they are two different plumbing paths: one
	// opens a side channel, the other means stdout is no longer a transcript to
	// scrape but a stream to parse.
	//
	// Fixed argv, no {path} token. Measured 2026-07-31:
	//
	//	claude   -p {prompt} --output-format stream-json --verbose
	//	codex    exec --json
	//	agy      -p {prompt} --output-format stream-json
	//
	// THESE ARE PRINT-MODE FLAGS, AND THAT BOUNDS WHAT THEY BUY. All three
	// belong to the one-shot Exec path (`-p`, `exec`) — claude states outright
	// that stream-json works only with --print — and none is available on
	// SteerExec, the bare interactive TUI.
	//
	// So they do NOT remove the 25-second silence tax, and it would be wrong to
	// wire them expecting that. The tax lives on the STEERING path (coach,
	// foreman, meet, herald all call Session.WaitIdle), where a session persists
	// across turns and these flags cannot be passed. A one-shot already has an
	// exact boundary: the process exits.
	//
	// What they buy instead is the fleet-evidence property — a tool call, a
	// stop_reason and an error status as STRUCTURED FACTS rather than lines
	// scraped back out of a terminal and guessed at. That is worth having, and
	// it is a different thing from turn detection.
	EventsStdout string `yaml:"events_stdout,omitempty" json:"events_stdout,omitempty"`

	// EventsDone declares how THIS tool spells "the turn ended".
	//
	// The EventsArg contract documented `{"type":"turn.end"}` and no third-party
	// tool says that. Measured on the wire, the same fact has three spellings —
	// codex `type: turn.completed`, claude `type: result`, agy `event: result` —
	// and even the KEY differs, so a matcher that assumed `type` would silently
	// never fire on agy. Silently, because a boundary that never arrives is
	// indistinguishable from a tool that is still thinking: the reader would
	// fall back to the 25-second silence tax it was trying to escape, and
	// nothing would report that the declaration was wrong.
	//
	// Declared per tool rather than inferred, for the reason this package
	// declares everything else: a guess that happens to work is a guess that
	// breaks on the next release with nobody watching.
	EventsDone EventsDone `yaml:"events_done,omitempty" json:"events_done,omitempty"`

	// EventsOutcome locates the VERDICT inside that terminal event.
	//
	// The exit code is not it. "All three harnesses EXITED 0 WHEN THEY FAILED"
	// is recorded in the umbrella's own notes, so a caller reading the status
	// learns nothing and reports success. The stream carries what the exit does
	// not. See eventsoutcome.go for why only SUCCESS is declarable.
	EventsOutcome EventsOutcome `yaml:"events_outcome,omitempty" json:"events_outcome,omitempty"`

	// SteerExec is the argv template that ACTUALLY accepts steering, and it is
	// usually NOT Exec.
	//
	// A headless one-shot has nothing to steer: `codex exec` and `agy -p` run the
	// prompt and exit. Steering needs the tool's interactive session — bare `codex`,
	// or `agy -i` ("run an initial prompt interactively and CONTINUE the session").
	//
	// Two templates, because the choice is a real trade. Exec gives a clean captured
	// answer (stdout and stderr stay apart on a pipe). SteerExec gives a session you
	// can interrupt, at the cost of a pty that merges the tool's chrome into the
	// transcript. A launcher picks by what it needs; the registry refuses to pretend
	// one launch does both.
	SteerExec string `yaml:"steer_exec,omitempty" json:"steer_exec,omitempty"`

	// ForkExec is the argv template that FORKS the tool's current session — a new,
	// independent session that inherits the live transcript — instead of starting
	// fresh. {session} = the current session id, {prompt} = the directive, {model}
	// = the model. This is what makes `delegate self` a true context-inheriting
	// fork ("delegate to yourself, no re-briefing"). ONLY a tool with a genuine
	// HEADLESS, NON-mutating fork declares this: claude has one
	// (`--resume <id> --fork-session -p`), codex does NOT — its headless `resume`
	// APPENDS to the parent thread, which would corrupt the steward's own session,
	// so codex has no ForkExec and `delegate self` falls back to a fresh instance.
	ForkExec string `yaml:"fork_exec,omitempty" json:"fork_exec,omitempty"`
	// SessionEnv names the env var(s) that carry this tool's current session id
	// when it drives a subprocess (e.g. CLAUDE_CODE_SESSION_ID). First non-empty
	// wins. Without a readable session id, a ForkExec that needs {session} cannot
	// fire, and delegate self falls back to a fresh instance.
	SessionEnv []string `yaml:"session_env,omitempty" json:"session_env,omitempty"`

	// SupportsGracefulQuit marks a tool that exits cleanly on a quit signal.
	SupportsGracefulQuit bool `yaml:"supports_graceful_quit,omitempty" json:"supports_graceful_quit,omitempty"`
	// TrustClear is the steering input that clears a trust prompt.
	TrustClear string `yaml:"trust_clear,omitempty" json:"trust_clear,omitempty"`
	// AuthHint explains an interactive sign-in the tool needs before it
	// can run headless at all.
	AuthHint string `yaml:"auth_hint,omitempty" json:"auth_hint,omitempty"`
	// Notes is the free-text launch contract commentary.
	Notes string `yaml:"notes,omitempty" json:"notes,omitempty"`
	// EnvMarkers are environment variables whose presence identifies this
	// tool as the one currently running.
	EnvMarkers []string `yaml:"env_markers,omitempty" json:"env_markers,omitempty"`
}

type ToolVersion struct {
	Version  string `yaml:"version,omitempty" json:"version,omitempty"`
	Download string `yaml:"download,omitempty" json:"download,omitempty"`
	Install  string `yaml:"install,omitempty" json:"install,omitempty"`
}

type ToolWatchdog struct {
	MaxRuntime string `yaml:"max_runtime,omitempty" json:"max_runtime,omitempty"`
	MemLimit   string `yaml:"mem_limit,omitempty" json:"mem_limit,omitempty"`
}

type Verdict string