@agentproto/runtime 3.6.1 → 4.1.0

package/dist/index.d.ts

@@ -1,35 +1,37 @@
 import { DoctypeSpec } from '@agentproto/manifest';
-import { B as BuildHeartbeatAgent } from './heartbeat-COGpMrJS.js';
-export { H as HeartbeatAgent, a as HeartbeatRunner, R as RuntimeEvent, b as RuntimeEvents, p as parseDuration } from './heartbeat-COGpMrJS.js';
+import { B as BuildHeartbeatAgent } from './heartbeat-BJtxbDb9.js';
+export { H as HeartbeatAgent, a as HeartbeatRunner, R as RuntimeEvent, b as RuntimeEvents, p as parseDuration } from './heartbeat-BJtxbDb9.js';
 import { z } from 'zod';
 import { AcpMcpServer, AcpPermissionResolution } from '@agentproto/acp';
 import { SessionMode } from '@agentproto/acp/client';
 export { SessionMode } from '@agentproto/acp/client';
 import { ChildProcess } from 'node:child_process';
-import { R as RouteSpec, S as SessionConfig, P as Posture, C as ContextProfile, E as EffortLevel, A as AuthMethod, a as CanonicalPosture } from './session-config-DbWP9RRj.js';
-export { D as DeclaredAdapterMode, c as composeMode, d as decomposeMode } from './session-config-DbWP9RRj.js';
+import { R as RouteSpec, S as SessionConfig, P as Posture, C as ContextProfile, E as EffortLevel, A as AuthMethod, a as CanonicalPosture } from './session-config-ByfVeEQJ.js';
+export { D as DeclaredAdapterMode, c as composeMode, d as decomposeMode } from './session-config-ByfVeEQJ.js';
 import { CostBudget, AuthProfile, CostBudgetScope } from '@agentproto/auth';
 export { CostBudget, CostBudgetScope } from '@agentproto/auth';
-import { R as ResolvedContextContinuityPolicy } from './context-continuity-ib9_bVYM.js';
+import { S as SpawnBrowserMode, R as ResolveHeadlessBrowser, C as ContextContinuityPolicy, a as ResolvedContextContinuityPolicy } from './context-continuity-Bn99UtVC.js';
 import { SandboxMode } from '@agentproto/command-sandbox';
 import { AdapterHandle, SetupField, AdapterResolver, AdapterLister, CredsStore, HarnessCapabilities, AdapterEntry } from '@agentproto/provider-kit';
-import { R as ResolvedAuthSpec, D as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './spawn-defaults-CwI9Puwy.js';
-export { a as AuthEcho, b as AuthResolutionError, C as CLAUDE_CODE_OAUTH_SOURCE, c as CredentialSource, d as DefaultsAdapterAuthConfig, e as DefaultsAdapterConfig, f as ResolveSubscriptionCredentialInput, g as ResolvedSpawnAuthMaterial, h as ResolvedSpawnDefaults, S as SpawnDefaultsConfig, i as SubscriptionCredentialResolution, j as SubscriptionSourceError, k as credentialFingerprint, n as normalizeSkillsOption, r as resolveAuthSpec, l as resolveSpawnDefaults, m as resolveSubscriptionCredential } from './spawn-defaults-CwI9Puwy.js';
+import { S as SpawnDefaultsConfig, D as DefaultsAdapterAuthConfig, R as ResolvedAuthSpec, a as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './spawn-defaults-CZj39Znq.js';
+export { b as AuthEcho, c as AuthResolutionError, C as CLAUDE_CODE_OAUTH_SOURCE, d as CredentialSource, e as DefaultsAdapterConfig, f as DeferredToolsConfig, g as ResolveSubscriptionCredentialInput, h as ResolvedSpawnAuthMaterial, i as ResolvedSpawnDefaults, j as SubscriptionCredentialResolution, k as SubscriptionSourceError, l as credentialFingerprint, n as normalizeSkillsOption, r as resolveAuthSpec, m as resolveDeferredToolsGatewayOption, o as resolveSpawnDefaults, p as resolveSubscriptionCredential } from './spawn-defaults-CZj39Znq.js';
 import { CatalogModelsQuery, CatalogModelsResponse } from './catalog-models.js';
 export { CatalogAdapterInput, CatalogAdapterModelInput, CatalogPricing, CatalogProduct, CatalogRoute, CatalogRouteSummary, CatalogVendor, buildCatalogModels } from './catalog-models.js';
 import { FooterSession } from './pr-provenance.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { SandboxProvider } from '@agentproto/sandbox';
+import { SandboxProvider, SandboxSpec } from '@agentproto/sandbox';
 import { BrainManager, ExportedSessionLike } from '@agentproto/workspace-brain';
 export { BrainManager, BrainStats, IngestReport, IngestResult } from '@agentproto/workspace-brain';
 import * as _agentproto_tool from '@agentproto/tool';
 import { ToolContext } from '@agentproto/tool';
 import { DriverHandle } from '@agentproto/driver';
-export { UserPreset, UserPresetsFile, deleteUserPreset, getUserPreset, listUserPresets, loadUserPresets, saveUserPreset, userPresetsPath } from './user-presets.js';
+import { Attestation, LedgerKey, RubricDigest, ReviewPrRef, LaneResult, ReviewLaneExecutor, LaneOutcome } from '@agentproto/review';
+import { UserPreset } from './user-presets.js';
+export { UserPresetsFile, deleteUserPreset, getUserPreset, listUserPresets, loadUserPresets, saveUserPreset, userPresetsPath } from './user-presets.js';
+import { WorktreeIsolationMode, SpawnAttachMode, SpawnDedupeMode } from './config.js';
 import { ResolvedModel } from '@agentproto/model-catalog';
 import { FrameSink, E2eFrameSink } from '@agentproto/acp/tunnel';
 import { DaemonIdentity } from '@agentproto/secrets/identity';
-import { WorktreeIsolationMode } from './config.js';
 import { WorkspaceFs } from './workspace-fs.js';
 export { createWorkspaceFs } from './workspace-fs.js';
 export { ConversationMeta, ConversationStore, ConversationTurn, fileConversationStore } from './conversations.js';
@@ -449,13 +451,64 @@ type UsageSource = "adapter" | "computed" | "no-pricing" | "none";
 interface TokenPricing {
     inputPer1M: number;
     outputPer1M: number;
+    /** Multiplier on `inputPer1M` for cache-read tokens (Anthropic: ~0.1).
+     *  Absent = 1 (no discount), same default as the catalog. */
+    cacheReadMultiplier?: number;
+    /** Multiplier on `inputPer1M` for cache-creation tokens (Anthropic:
+     *  ~1.25). Absent = 1. */
+    cacheWriteMultiplier?: number;
+}
+/**
+ * Token-detail and activity fields shared by every usage shape below. All
+ * optional and never zero-filled: absent means "this source doesn't report
+ * it", a present 0 is a measured zero.
+ *
+ *   - `cacheReadTokens` / `cacheWriteTokens`: prompt-cache reads / cache
+ *     creation, cumulative. Kept OUT of `tokensIn` (which is uncached input
+ *     only when a cache split is known).
+ *   - `reasoningTokens`: thinking/reasoning tokens, cumulative. A subset of
+ *     `tokensOut` for providers that bill them as output (Anthropic).
+ *   - `turns`: completed turns (the descriptor's `turnsCompleted`).
+ *   - `toolCalls`: tool calls the daemon observed, cumulative.
+ *   - `durationMs`: wall time spent inside turns, cumulative.
+ */
+interface UsageDetail {
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+    turns?: number;
+    toolCalls?: number;
+    durationMs?: number;
 }
+/** Copy only the present (`number`) `UsageDetail` fields of `src`. */
+declare function pickUsageDetail(src: UsageDetail): UsageDetail;
 /** Pluggable pricing accessor — defaults to the in-repo catalog's
  *  `resolvePricing`, overridable in tests. Returns undefined for an
  *  unknown model (the caller then tags `no-pricing`). */
 type PricingResolver = (model: string) => TokenPricing | undefined;
+/**
+ * What an adapter's usage reader (`readUsage`: hermes state.db, opencode.db,
+ * the claude-code transcript JSONL) returns. Every field is cumulative for
+ * the session and optional; `null` from the reader means "nothing found".
+ */
+interface UsageReadResult {
+    model?: string;
+    costUsd?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+/** Where a reader should look for the session's native store — the spawn's
+ *  cwd and isolated provider config dir (`CLAUDE_CONFIG_DIR` for
+ *  claude-code). Readers that key only on the session id ignore it. */
+interface UsageReadContext {
+    cwd?: string;
+    configDir?: string;
+}
 /** Raw signals gathered over a turn, handed to `deriveSessionUsage`. */
-interface UsageComputeInput {
+interface UsageComputeInput extends UsageDetail {
     /** Requested model id — needed to look up per-token prices. */
     model?: string;
     /** Cost the adapter reported directly (readUsage or usage_update.cost).
@@ -469,7 +522,7 @@ interface UsageComputeInput {
 /** The resolved usage snapshot — the shape `session_usage` returns and the
  *  durable `usage_snapshot` transcript record carries. Cost/token fields are
  *  omitted when absent so a missing value never reads as a measured zero. */
-interface SessionUsage {
+interface SessionUsage extends UsageDetail {
     model?: string;
     costUsd?: number;
     tokensIn?: number;
@@ -486,7 +539,7 @@ interface SessionUsage {
  */
 declare function deriveSessionUsage(input: UsageComputeInput, resolve?: PricingResolver): SessionUsage;
 /** Descriptor-shaped fields `projectSessionUsage` reads. */
-interface UsageDescriptorFields {
+interface UsageDescriptorFields extends Omit<UsageDetail, "turns"> {
     model?: string;
     costUsd?: number;
     tokensIn?: number;
@@ -494,6 +547,8 @@ interface UsageDescriptorFields {
     contextSize?: number;
     contextUsed?: number;
     usageSource?: UsageSource;
+    /** Surfaced as `turns`. */
+    turnsCompleted?: number;
 }
 /**
  * Project a session descriptor's persisted usage fields into the
@@ -502,6 +557,37 @@ interface UsageDescriptorFields {
  */
 declare function projectSessionUsage(desc: UsageDescriptorFields): SessionUsage;
 
+/**
+ * McpAppsHostService — the daemon as the MCP client that fetches MCP App
+ * UIs (spec 2026-01-26) on behalf of a session's chat UI.
+ *
+ * In a session the MCP client is the harness (claude-code, codex, …); it
+ * keeps a tool's `_meta.ui.resourceUri` and the `ui://` resource to itself,
+ * and the transcript only carries `mcp__<server>__<tool>` + input + result.
+ * So the chat asks the daemon, which resolves `<server>` for that session
+ * (mcp-app-resolve.ts), connects through a config-keyed pool
+ * (mcp-client-pool.ts), and answers three questions:
+ *
+ *   uiIndex   which of this server's tools declare a UI (+ app-only tools)
+ *   readUi    the HTML + `_meta.ui` of one of those `ui://` resources
+ *   callTool  an iframe-initiated `tools/call`, allowlisted and recorded
+ *
+ * None of these throw: every failure is a `status` (or an `isError`
+ * result). Failures are cached per (session, alias) for 60s so a
+ * transcript full of calls to a dead server costs one attempt a minute.
+ */
+
+/** Durable record of an iframe-initiated call, appended to the session's
+ *  events.jsonl as `kind: "mcp_app_tool_call"`. Never carries args or
+ *  results. */
+interface McpAppToolCallRecord {
+    server: string;
+    tool: string;
+    originToolCallId: string;
+    isError: boolean;
+    durationMs: number;
+}
+
 /**
  * ONE normalized shape for a finished tool/command call — the unification
  * target for the two disjoint logs this repo has today: `recordCommand`'s
@@ -1685,6 +1771,41 @@ declare function createTaskLedger(opts: {
     persist?: boolean;
 }): TaskLedger;
 
+/**
+ * The single place every stable `SessionDescriptor.endedReason` /
+ * `SessionOutcome.termination.reason` value is declared, so a UI can render
+ * a label for each one without chasing the call site that set it.
+ *
+ * Two families:
+ *   - operator-issued — set ONLY by an explicit `POST /sessions/:id/kill`
+ *     or the `agent_kill` MCP tool, distinguishing an operator's deliberate
+ *     stop from every automatic teardown below;
+ *   - internal/automatic — set by the daemon itself, without an operator
+ *     in the loop, for a reason the operator couldn't have expressed.
+ *
+ * Backward compatible by construction: this is a value list, not a closed
+ * validator. A descriptor persisted by an older daemon (or a newer one an
+ * older UI doesn't know about yet) carries a `reason` string outside this
+ * list — {@link isKnownSessionEndReason} says so, and callers should fall
+ * back to a generic label rather than throw.
+ */
+declare const SESSION_END_REASONS: readonly ["daemon-restart", "idle-reaped", "crashed", "operator-completed", "operator-stopped", "cost-cap-exceeded", "policy-cleanup", "parent-exited", "provider-limit", "forgotten"];
+type SessionEndReason = (typeof SESSION_END_REASONS)[number];
+/** True when `reason` is one of {@link SESSION_END_REASONS}. A label
+ *  lookup, not a wire-format gate — an unrecognized string is still a
+ *  valid `endedReason` from a daemon version this build doesn't know
+ *  about; callers should render it with a generic fallback, never reject
+ *  it. */
+declare function isKnownSessionEndReason(reason: string | undefined): reason is SessionEndReason;
+/**
+ * Classify a driver-reported error message as a provider/subscription
+ * usage cap rather than an ordinary tool/turn failure. Used wherever the
+ * daemon would otherwise tag a dead session with the generic `"crashed"` /
+ * `"error"` reason, so an operator sees "wait for your quota to reset"
+ * instead of chasing a phantom bug.
+ */
+declare function isProviderLimitError(message: string | undefined): boolean;
+
 /**
  * In-process pub/sub bus for session lifecycle events. Separate from
  * RuntimeEvents (global daemon bus) — session events are scoped to
@@ -1695,7 +1816,7 @@ declare function createTaskLedger(opts: {
  * and session_monitor MCP tool (long-poll multiplexed).
  */
 
-type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:awaiting-input-flagged" | "session:awaiting-question-answered" | "session:permission-request" | "session:permission-resolved" | "session:exited" | "session:reaped" | "session:stalled" | "session:stall-cleared" | "session:watcher-attached" | "session:watcher-detached" | "session:bg-tasks-parked" | "session:bg-tasks-cleared" | "session:resumed" | "session:spawned" | "session:command-done" | "session:model-changed" | "session:config-changed" | "session:renamed" | "session:pinned-changed" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed" | "cron:fired" | "cron:succeeded" | "cron:failed" | "activity:changed" | "task:changed" | "workflow:gate-report" | "workflow:suspended" | "workflow:suspend-resumed" | "session:harness-warning";
+type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:awaiting-input-flagged" | "session:awaiting-question-answered" | "session:permission-request" | "session:permission-resolved" | "session:exited" | "session:reaped" | "session:stalled" | "session:stall-cleared" | "session:watcher-attached" | "session:watcher-detached" | "session:bg-tasks-parked" | "session:bg-tasks-cleared" | "session:bg-task" | "session:resumed" | "session:spawned" | "session:command-done" | "session:model-changed" | "session:config-changed" | "session:renamed" | "session:pinned-changed" | "session:message" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed" | "cron:fired" | "cron:succeeded" | "cron:failed" | "activity:changed" | "task:changed" | "workflow:gate-report" | "workflow:suspended" | "workflow:suspend-resumed" | "session:harness-warning";
 /**
  * Fixed severity vocabulary for a judge-gate finding (WP-D). Deliberately
  * small and fixed so `policy_status` output is comparable across different
@@ -1769,6 +1890,25 @@ interface SessionTurnEndEvent {
      * a normal, productive turn.
      */
     empty?: boolean;
+    /**
+     * The in-band `error` stream event's message text observed during this
+     * turn, when one occurred (see `SessionDescriptor.lastTurnErrorMessage`'s
+     * doc). Present whenever `reason` is `"error"` AND the adapter emitted an
+     * `error`-kind event before ending the stream — including the case where
+     * the generator simply returned with no explicit turn-end and no thrown
+     * exception, which is exactly what left an errored turn indistinguishable
+     * from a clean one before this field existed. Absent when the adapter
+     * reported `reason:"error"` on its own turn-end without a preceding
+     * `error` event, and absent (not empty string) on every non-error turn.
+     */
+    error?: string;
+    /**
+     * True when the turn was not started by a prompt: the agent woke on its
+     * own (Claude Code's task-notification cycle after a background task
+     * settled) and the registry tracked that work as a turn. Absent on an
+     * ordinary prompted turn.
+     */
+    autonomous?: boolean;
 }
 interface SessionAwaitingInputEvent {
     type: "session:awaiting-input";
@@ -1865,15 +2005,14 @@ interface SessionExitedEvent {
     status: "exited" | "killed" | "error";
     label?: string;
     ts: string;
-    /** Mirrors `SessionDescriptor.endedReason` — set when this exit was NOT an
-     *  operator targeting the session: `"daemon-restart"` (the daemon dying
-     *  underneath it — crash-discovered-at-boot or a forced shutdown kill) or
-     *  `"idle-reaped"` (the idle-session reaper retiring a long-idle row to free
-     *  the adapter process, PR-6), or `"crashed"` (the crash-detect sweep found
-     *  the adapter's OS process gone between turns). Lets a watcher
-     *  (completion-policy supervisor, `session_monitor`) tell an automatic
-     *  teardown apart from a deliberate kill. Absent otherwise. */
-    reason?: "daemon-restart" | "idle-reaped" | "crashed";
+    /** Mirrors `SessionDescriptor.endedReason` — see {@link SessionEndReason}
+     *  for the full, single-source enum (automatic teardowns like
+     *  `"daemon-restart"` / `"idle-reaped"` / `"crashed"` / `"cost-cap-exceeded"`
+     *  / `"provider-limit"`, and operator-issued `"operator-completed"` /
+     *  `"operator-stopped"`). Lets a watcher (completion-policy supervisor,
+     *  `session_monitor`) tell WHY this exit happened rather than just that it
+     *  did. Absent for a plain natural exit or an ordinary turn error. */
+    reason?: SessionEndReason;
 }
 /**
  * Emitted when the idle-session reaper (PR-6) retires a long-idle agent-cli
@@ -2024,6 +2163,29 @@ interface SessionBgTasksClearedEvent {
     label?: string;
     ts: string;
 }
+/**
+ * One lifecycle edge of an agent's background task (a backgrounded Bash
+ * command, a monitor, ...) as the agent itself reported it — over ACP, the
+ * AIR `asyncTasks` extension (see @agentproto/acp's `background-task`
+ * StreamEvent). Unlike {@link SessionBgTasksParkedEvent} (a turn-end
+ * heuristic) this is the real lifecycle: `"started"` when the task is
+ * announced, `"settled"` when it reaches a terminal `status`. Mid-life
+ * progress updates only refresh `SessionDescriptor.backgroundTasks` and are
+ * not emitted. Same bus distribution as every other lifecycle event.
+ */
+interface SessionBgTaskEvent {
+    type: "session:bg-task";
+    sessionId: string;
+    phase: "started" | "settled";
+    taskId: string;
+    taskKind?: string;
+    description?: string;
+    outputFile?: string;
+    status?: string;
+    summary?: string;
+    label?: string;
+    ts: string;
+}
 /**
  * Emitted when a dead agent-cli row is brought back IN PLACE — same session
  * id, same descriptor — by the lazy resume-on-prompt path (`maybeResumeAgent`)
@@ -2163,6 +2325,27 @@ interface SessionRenamedEvent {
     renamedByUser?: boolean;
     ts: string;
 }
+/**
+ * A typed inter-session message (`session-message.ts`) was accepted for
+ * `sessionId` (the RECIPIENT) — once at send (no `delivered`) and again when
+ * it's delivered into the recipient's context (`delivered` set). Lets
+ * `session_monitor` / SSE / the VS Code panel react without polling.
+ */
+interface SessionMessageEvent {
+    type: "session:message";
+    sessionId: string;
+    messageId: string;
+    fromSessionId?: string;
+    relation: "child" | "parent" | "sibling" | "human" | "system";
+    kind: "report" | "question" | "blocker" | "done" | "notice";
+    urgency: "fyi" | "next-turn" | "steer" | "interrupt";
+    delivered?: {
+        via: "wait" | "steer" | "turn" | "interrupt" | "inbox";
+        at: string;
+        turnSeq?: number;
+    };
+    ts: string;
+}
 /**
  * Emitted when an operator pins or unpins a session for list visibility
  * (`POST /sessions/:id/pin`, the `session_set_pinned` MCP verb). Like
@@ -2356,16 +2539,22 @@ interface WorkflowApprovalResolvedEvent {
 }
 /**
  * Emitted by the workflow runner (`workflow-runner.ts`) when a `kind:
- * "suspend"` step parks its run awaiting an external event — the run's
- * status flips to `awaiting-input` with a durable `awaitingSuspend` record
- * (AIP-15 conformance rule 7), and `workflow_escalation_resolve`'s suspend
- * form resumes it. Same bus distribution as every other lifecycle event.
+ * "suspend"` step parks its run awaiting an external event (`on` set, no
+ * `reason`) — OR when an agent-backed step signals AIP-58 §3(a)
+ * `run.requestInput` (`reason: "input-required"` + `prompt`/`schema?`, no
+ * `on`). Either way the run's status flips to `awaiting-input` with a
+ * durable `awaitingSuspend` record, and `workflow_escalation_resolve`'s
+ * suspend form resumes it. Same bus distribution as every other lifecycle
+ * event.
  */
 interface WorkflowSuspendedEvent {
     type: "workflow:suspended";
     runId: string;
     stepId: string;
-    on: readonly string[];
+    on?: readonly string[];
+    reason?: "input-required";
+    prompt?: string;
+    schema?: Record<string, unknown>;
     ts: string;
 }
 /**
@@ -2393,7 +2582,7 @@ interface SessionHarnessWarningEvent {
     label?: string;
     ts: string;
 }
-type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionAwaitingInputFlaggedEvent | SessionAwaitingQuestionAnsweredEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | SessionExitedEvent | SessionReapedEvent | SessionStalledEvent | SessionStallClearedEvent | SessionWatcherAttachedEvent | SessionWatcherDetachedEvent | SessionBgTasksParkedEvent | SessionBgTasksClearedEvent | SessionResumedEvent | SessionSpawnedEvent | SessionCommandDoneEvent | SessionModelChangedEvent | SessionConfigChangedEvent | SessionRenamedEvent | SessionPinnedEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent | ActivityChangedEvent | TaskChangedEvent | WorkflowGateReportEvent | WorkflowApprovalRequestedEvent | WorkflowApprovalResolvedEvent | WorkflowSuspendedEvent | WorkflowSuspendResumedEvent | SessionHarnessWarningEvent;
+type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionAwaitingInputFlaggedEvent | SessionAwaitingQuestionAnsweredEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | SessionExitedEvent | SessionReapedEvent | SessionStalledEvent | SessionStallClearedEvent | SessionWatcherAttachedEvent | SessionWatcherDetachedEvent | SessionBgTasksParkedEvent | SessionBgTasksClearedEvent | SessionBgTaskEvent | SessionResumedEvent | SessionSpawnedEvent | SessionCommandDoneEvent | SessionModelChangedEvent | SessionConfigChangedEvent | SessionRenamedEvent | SessionPinnedEvent | SessionMessageEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent | ActivityChangedEvent | TaskChangedEvent | WorkflowGateReportEvent | WorkflowApprovalRequestedEvent | WorkflowApprovalResolvedEvent | WorkflowSuspendedEvent | WorkflowSuspendResumedEvent | SessionHarnessWarningEvent;
 interface SessionEventBus {
     emit(ev: SessionEvent): void;
     /** Subscribe to a specific event type. Returns an unsubscribe fn. */
@@ -2639,50 +2828,276 @@ declare class TunnelRegistry {
     private loadFromDisk;
 }
 
+/**
+ * LlmEndpointRegistry — supervised-sidecar manager for the
+ * `@agentproto/llm-endpoint` proxy gateway.
+ *
+ * The daemon spawns the llm-endpoint bin as a CHILD PROCESS (never an
+ * in-process import — the runtime package has zero dependency on
+ * @agentproto/llm-endpoint, exactly like it never imports cloudflared).
+ * This is the single-sidecar analog of {@link TunnelRegistry}: one endpoint,
+ * one port, an in-memory descriptor that tracks pid / port / status /
+ * startedAt, and a start / stop / status lifecycle exposed over MCP.
+ *
+ * Lifecycle (mirrors RemoteController's singleton style — created fresh each
+ * boot, state in memory; the child dies with the daemon so there is nothing
+ * to reconcile on restart):
+ *   start(input) → assemble env, spawn `node <bin> serve`, health-probe to
+ *                  readiness, store descriptor. Idempotent: a call while the
+ *                  endpoint is already running+healthy returns the existing
+ *                  descriptor without spawning (like `start_browser`).
+ *   status()     → descriptor + live `GET /v1/models` health probe.
+ *   stop()       → SIGTERM the child, mark stopped (mirrors tunnel stop).
+ *   shutdown()   → stop the child on daemon exit.
+ *
+ * Env on spawn (see {@link assembleLlmEndpointEnv}): the provider API keys
+ * via `injectProviderKeysIntoEnv` (the same store llm-endpoint's own cli.ts
+ * reads), `LLM_ENDPOINT_PORT` (default 18090), and `LLM_ENDPOINT_ACCESS_TOKENS`
+ * when configured. Explicit env passed to `start` always wins.
+ */
+type LlmEndpointStatus = "starting" | "running" | "stopped" | "error";
+/** The `llm_endpoint_status` MCP contract — see {@link LlmEndpointRegistry.status}. */
+interface LlmEndpointStatusReport {
+    running: boolean;
+    pid: number | null;
+    port: number | null;
+    baseUrl: string | null;
+    healthy: boolean;
+    startedAt: string | null;
+    status: LlmEndpointStatus | "never-started";
+    /** Who is actually serving this endpoint. `"daemon"` — this registry's own
+     *  spawn (or nothing at all). `"external"` — a healthy process on the same
+     *  port that this registry did NOT spawn (e.g. a launchd KeepAlive
+     *  sidecar); `pid` is unknown (always `null`) and `injectedProviders`, if
+     *  present, was DERIVED by probing `/v1/models` rather than read off our
+     *  own key-injection bookkeeping. */
+    owner: "daemon" | "external";
+    /** Whether upstream links persisted via `llm_endpoint_set_upstream_link`
+     *  are actually applied to the process answering this port. Always
+     *  `false` for `owner:"external"` — this registry never spawned it, so it
+     *  never injected `LLM_ENDPOINT_PROFILE_<UPSTREAM>`; the operator must
+     *  configure the external service's own env directly. */
+    linksApplied: boolean;
+    lastError?: string;
+    injectedProviders?: string[];
+    linkedProviders?: string[];
+    /** `@agentproto/llm-endpoint`'s own package version, read from the
+     *  resolved bin's `package.json` — best-effort, present only for
+     *  `owner:"daemon"` (the version of the code this registry would spawn /
+     *  did spawn). Undefined when unresolvable, or for `owner:"external"`
+     *  (an adopted process exposes no version of its own to probe). */
+    version?: string;
+}
+interface LlmEndpointDescriptor {
+    pid: number | null;
+    port: number;
+    baseUrl: string;
+    status: LlmEndpointStatus;
+    startedAt: string;
+    stoppedAt?: string;
+    lastError?: string;
+    /** Provider names whose keys were injected into the child's env (never values). */
+    injectedProviders?: string[];
+    /** Upstream names mapped to an auth-profile link (`LLM_ENDPOINT_PROFILE_<P>`)
+     *  in the child's env. Profile IDS, not secrets — but only the provider names
+     *  are surfaced here, mirroring `injectedProviders`. */
+    linkedProviders?: string[];
+    /**
+     * Only populated on the value returned by {@link LlmEndpointRegistry.start}
+     * (never stored on the in-memory descriptor): `true` when the call reused an
+     * already-running/starting child instead of spawning — so the caller can
+     * tell a fresh `start` (new port/tokens applied) from a no-op idempotent hit
+     * (old descriptor returned, nothing new applied). Mirrors `start_browser`.
+     */
+    wasAlreadyRunning?: boolean;
+}
+
+/**
+ * RemoteController — owns the gateway's "publish to the internet" state.
+ *
+ * One singleton per gateway. Holds:
+ *   - the current tunnel provider's child process (cloudflared, …)
+ *   - the bearer token gating /mcp once the tunnel is up
+ *   - persisted state in `<workspace>/.agentproto/remote.json`
+ *
+ * The controller is the *only* component that mutates auth at runtime.
+ * The HTTP server reads auth via a getter (see `AuthSource` in
+ * http-server.ts), so flipping `enable() / disable()` here takes effect
+ * on the next request — no restart, no race.
+ *
+ * ## Provider model
+ *
+ * Each provider implements `RemoteProvider` (start / stop / status).
+ * v1 ships only `quick` (Cloudflare Quick Tunnel — no API key, no DNS,
+ * ephemeral `*.trycloudflare.com` URL). Named CF Tunnel and Tailscale
+ * land as additional implementations.
+ *
+ * ## Token model
+ *
+ * On enable we generate a 32-byte random bearer token, return it once
+ * to the caller, and persist only its sha256 hash to disk. Same model
+ * as a Stripe API key — losing the plaintext means rotating, not
+ * recovering. This keeps `.agentproto/remote.json` safe to commit by
+ * accident (it leaks the URL, not the credential).
+ *
+ * ## Security note
+ *
+ * The CF API token (when used by named-tunnel provider) is *never*
+ * accepted as MCP tool input. The controller reads it from
+ * `~/.config/agentproto/cloudflare.json` or `$CLOUDFLARE_API_TOKEN`.
+ * Otherwise a remote agent could exfiltrate it through `remote_enable`.
+ */
+
+interface EnableInput {
+    provider?: "quick";
+    /**
+     * Local port to expose. Defaults to the gateway's own port — i.e.
+     * "publish this MCP server." Pass any other port to expose a
+     * different local service (Supabase 54371, a Vite dev server, …)
+     * without spinning up a separate tunnel manager.
+     */
+    targetPort?: number;
+    /**
+     * Host the tunnel forwards to. Defaults to `127.0.0.1`. Setting it
+     * to `localhost` resolves through DNS (IPv6 first on most systems);
+     * keep `127.0.0.1` unless the target is explicitly IPv6-bound.
+     */
+    targetHost?: string;
+}
+interface EnableResult {
+    publicUrl: string;
+    /**
+     * Bearer token issued by this gateway. Only meaningful when the
+     * tunnel exposes the gateway itself (default). For arbitrary-target
+     * tunnels (`targetPort != gateway.port`) the daemon does not gate
+     * the proxied service, and this is omitted.
+     */
+    bearerToken?: string;
+    /**
+     * `<publicUrl>/mcp`. Only emitted when exposing the gateway.
+     */
+    mcpEndpoint?: string;
+    /**
+     * Paste-ready `.mcp.json` snippet. Only emitted when exposing the
+     * gateway.
+     */
+    mcpConfigSnippet?: string;
+    /**
+     * A single link to open on a phone (PHONE-PLAN.md P1.2) — the token rides
+     * in a URL *fragment* (`#token=`), never a `?` query string, since
+     * fragments never reach a server (no Referer, no access/proxy log, no CDN
+     * cache key). Two shapes, chosen by whether this daemon has the
+     * `@agentik/session-chat` app installed with a UI:
+     *   - installed: `<publicUrl>/apps/@agentik/session-chat/ui#token=<t>` —
+     *     the phone lands directly in Control Center.
+     *   - not installed: `https://cli.agentproto.sh/panel#daemon=<publicUrl>&token=<t>`
+     *     — the hosted panel, which speaks the same fragment shape (see
+     *     agentproto/cli-site's `readFragmentConnection`).
+     * Only emitted when exposing the gateway (same condition as `bearerToken`)
+     * — a passthrough tunnel has no daemon UI to link to.
+     */
+    phoneUrl?: string;
+    provider: "quick";
+    target: {
+        host: string;
+        port: number;
+    };
+    exposesGateway: boolean;
+    /**
+     * Present ONLY for passthrough tunnels (`exposesGateway === false`):
+     * the daemon does not gate that traffic, so the public URL reaches the
+     * upstream service with no auth from the daemon. A machine-readable flag
+     * so UIs/agents can surface the exposure instead of it being buried in
+     * the tool's prose description.
+     */
+    warning?: string;
+}
+interface RemoteStatus {
+    enabled: boolean;
+    provider?: "quick";
+    publicUrl?: string;
+    pid?: number | null;
+    createdAt?: string;
+    target?: {
+        host: string;
+        port: number;
+    };
+    exposesGateway?: boolean;
+    /** Last error from the provider, if any (since last enable). */
+    lastError?: string;
+}
+
 /**
  * Daemon-side pairing registry (design: DESIGN §3/§4, PLAN deliverable 2).
  *
  * Owns everything the daemon needs to be *paired with* over an untrusted
  * rendezvous:
  *
- *   - **Offer store** — in-memory, single-use, expiry-checked one-time tokens
- *     minted by `pair offer`. A daemon restart voids outstanding offers
- *     (acceptable + documented). The P1 `verifyOfferToken` predicate plugs in
- *     here and SPENDS the token on the first successful handshake.
+ *   - **Offer store** — in-memory, single-use, expiry-checked one-time offer
+ *     secrets minted by `pair offer`. A daemon restart voids outstanding offers
+ *     (acceptable + documented). The daemon parks on the offer's ROUTE token and
+ *     the handshake's `verifyAuthToken` predicate checks the sealed AUTH token,
+ *     SPENDING the offer on the first successful handshake (a wrong token spends
+ *     nothing).
  *   - **Pairings store** — `~/.agentproto/pairings.json` (0600, atomic write),
  *     one record per paired client: `{clientPub, name, fingerprint, createdAt,
  *     lastSeen, pairRoot, rendezvousUrl}`. `pairRoot` is the long-term shared
  *     secret (`derivePairRoot`) from which reconnect routing tokens derive.
  *   - **Rendezvous connections** — for a fresh offer, and for every persisted
  *     pairing on boot (autoconnect), the daemon dials the rendezvous *outbound*
- *     (`side=daemon&t=<token>`), runs `daemonHandshakeOverSink` with the P1
+ *     (`side=daemon&t=<route>`), runs `daemonHandshakeOverSink` with the P1
  *     crypto, and — on success — serves the spliced, E2E-wrapped channel exactly
  *     like `serve --connect` serves a tunnel host. The serving path itself is
  *     injected (`serve`) so this module stays free of pty/adapter concerns and
  *     the CLI can reuse its `createTunnelServer` config verbatim.
- *   - **Reconnect epochs** — a persisted pairing's standing connection uses the
- *     pairing-derived routing token `t' = HKDF(pairRoot, "rv-route"‖epoch)`,
- *     rotated per UTC day. The daemon parks on BOTH the current and previous
+ *   - **Reconnect epochs** — a persisted pairing's standing connection parks on
+ *     the pairing-derived route `HKDF(pairRoot, "rv-route"‖epoch)`, rotated per
+ *     UTC day. The daemon parks on BOTH the current and previous
  *     epoch tokens so a client whose clock straddles midnight still finds it;
  *     reconnect-with-backoff keeps the standing connection alive.
- *   - **Revocation** — removing a pairing drops its rendezvous connections and
- *     stops the daemon parking on its tokens, so it can no longer be reached.
+ *   - **Revocation** — removing a pairing drops its rendezvous connections, so
+ *     it can no longer be served. For a grace period (`revokedGraceMs`, default
+ *     14 days) the daemon keeps a *tombstone*: it still parks on the pairing's
+ *     epoch ROUTES, completes the (daemon-signed) handshake only for a hello
+ *     carrying that epoch's AUTH token, and answers with a single E2E-encrypted
+ *     `error{code:"pairing_revoked"}` frame before closing — never serving the
+ *     channel. That is what lets a client tell "unpaired" from "daemon
+ *     offline" (which both otherwise look like a park timeout at the broker)
+ *     and stop retrying. The signal is authenticated like every tunnel frame:
+ *     it arrives inside the AEAD channel of a handshake whose transcript the
+ *     client verified against the pinned daemon key, so the broker can't forge
+ *     it; and the broker, which knows the routes, can't elicit it either (no
+ *     auth token). A tombstone keeps only the per-epoch route + auth tokens for
+ *     its window — the pair root is dropped at revoke.
  *
  * ## Reconnect authentication (why no stable client key)
  *
- * P1's handshake carries only a client *ephemeral* key (regenerated per
- * handshake) — there is no persistent client identity key, and the PLAN forbids
- * changing the handshake. So a reconnect authenticates the client by
- * **possession of the epoch routing token**, which derives from `pairRoot` — a
- * secret only the paired client and daemon share (it fell out of the original
- * ECDH). The daemon dials a pairing's epoch token, and on that connection the
- * `verifyOfferToken` predicate accepts a hello whose offer-token field equals
- * that same epoch token (constant-time). Token possession ⇒ paired party. The
- * stored `fingerprint` (of the first handshake's ephemeral key) is a stable
- * display/revocation handle, not an authentication input.
+ * The handshake carries only a client *ephemeral* key (regenerated per
+ * handshake) — there is no persistent client identity key. So a reconnect
+ * authenticates the client by **possession of the epoch AUTH token**
+ * `HKDF(pairRoot, "rv-auth"‖epoch)`, which derives from `pairRoot` — a secret
+ * only the paired client and daemon share (it fell out of the original ECDH).
+ * The daemon parks on the pairing's epoch ROUTE, and on that connection the
+ * `verifyAuthToken` predicate accepts a hello whose sealed auth equals the same
+ * epoch's auth token (constant-time). The route and auth are separate one-way
+ * HKDF outputs: the broker sees every route and can't compute an auth from it.
+ * (pair/v1 used ONE value for both, so a broker could replay a logged route as
+ * the proof and be served.) The stored `fingerprint` (of the first handshake's
+ * ephemeral key) is a stable display/revocation handle, not an auth input.
+ *
+ * ## Legacy (pair/v1) pairings
+ *
+ * A v1 `pairings.json` is loaded with every record flagged `legacy`: listed and
+ * revocable, never served. The daemon still parks on a legacy pairing's routes
+ * (the epoch route is unchanged from v1) so that pairing's not-yet-upgraded
+ * client reaches it and is told to re-pair — see `respondToLegacyHandshake` —
+ * rather than timing out. v1 records are not upgraded in place: v1 let the
+ * broker pair as a client, so any v1 record may be the broker's own.
  */
 
-declare const PAIRINGS_VERSION: 1;
+/** `pairings.json` format. v2 = pairings made under pair/v2 (route/auth
+ *  split). A v1 file still loads, every record flagged `legacy`. */
+declare const PAIRINGS_VERSION: 2;
 /** One persisted pairing. Written verbatim to `pairings.json`. */
 interface PairingRecord {
     /** The client ephemeral public key from the FIRST handshake (a snapshot —
@@ -2701,6 +3116,17 @@ interface PairingRecord {
     pairRoot: string;
     /** Rendezvous endpoint to reconnect through. */
     rendezvousUrl: string;
+    /** Set on a pairing made under the retired pair/v1 protocol: listed and
+     *  revocable, never served — its client is told to re-pair. */
+    legacy?: true;
+    /** Set when this pairing was made under an offer minted with
+     *  `agentproto pair offer --host` (PR-C) — i.e. the offering daemon's own
+     *  intent, recorded server-side at handshake time from the OfferEntry it
+     *  itself created, never from the (unauthenticated) `scope` param a client
+     *  presented in the offer URL. Absent for an ordinary remote-control
+     *  pairing. Purely informational here — it does not change how this
+     *  pairing is served. */
+    scope?: "host";
 }
 /** Mode of a served channel — first-contact offer vs. an established reconnect. */
 type PairingChannelMode = "offer" | "reconnect";
@@ -2718,8 +3144,9 @@ interface PairingChannelHandle {
     close(): Promise<void>;
 }
 interface CreatedOffer {
-    /** The one-time offer token (base64url). */
-    token: string;
+    /** The one-time offer secret (base64url) — the URL's `s`. Never on the wire:
+     *  the broker only ever sees its derived route. */
+    secret: string;
     /** Offer expiry, unix seconds. */
     exp: number;
     /** The full `agentproto://pair?…` offer URL. */
@@ -2733,12 +3160,21 @@ interface CreatedOffer {
      *  falls back to `HOSTED_RENDEZVOUS_URL`. Surfaced so `pair offer` can flag,
      *  never silently, that the daemon is relaying through our infrastructure. */
     rendezvousIsHostedDefault: boolean;
+    /** Echoes `CreateOfferInput.scope`. `"host"` when minted with `--host`;
+     *  absent for a plain offer. */
+    scope?: "host";
 }
 interface CreateOfferInput {
     /** Time-to-live in ms. Default 10 minutes. */
     ttlMs?: number;
     /** Rendezvous URL override; falls back to the configured default. */
     rendezvousUrl?: string;
+    /** Mint a HOST-scoped offer (PR-C): the accepting side may register this
+     *  daemon as a driveable host (`devices add`), not just remote-control it.
+     *  Recorded on the resulting `OfferEntry`/`PairingRecord` server-side — this
+     *  is the authoritative record of what was granted, independent of the
+     *  `scope` param an accepting client's offer URL happens to carry. */
+    scope?: "host";
 }
 interface PairingRegistryDeps {
     /** Lazily load (create on first use) the daemon identity. Kept lazy so a
@@ -2772,23 +3208,184 @@ interface PairingRegistryDeps {
     /** How long a parked daemon socket waits for a client hello before recycling
      *  the connection. Kept just under the broker's park timeout. Default 110s. */
     handshakeTimeoutMs?: number;
+    /** How long a revoked pairing is still answered with `pairing_revoked` (see
+     *  "Revocation" above). Default 14 days; `0` disables tombstones, so a
+     *  revoked client just stops finding the daemon. */
+    revokedGraceMs?: number;
 }
 interface PairingRegistry {
     /** Mint a one-time offer + start dialing the rendezvous for it. */
     createOffer(input?: CreateOfferInput): Promise<CreatedOffer>;
     /** All persisted pairings (copies). Loads `pairings.json` on first call. */
     list(): Promise<PairingRecord[]>;
+    /** Rename a pairing by fingerprint or name (cosmetic only — no effect on
+     *  auth or routing). Returns false when nothing matched; throws on an
+     *  empty `newName`. */
+    rename(idOrName: string, newName: string): Promise<boolean>;
     /** Drop a pairing by fingerprint or name; stops its rendezvous connections.
      *  Returns false when nothing matched. */
     revoke(idOrName: string): Promise<boolean>;
+    /** Is a channel (offer or reconnect) currently served for this fingerprint? */
+    isOnline(fingerprint: string): boolean;
     /** Start standing reconnect connections for every persisted pairing. Call
      *  after the gateway is up (so the injected `serve` can reach it). */
     startAutoconnect(): Promise<void>;
     /** Tear down every offer + reconnect connection and served channel. */
     shutdown(): Promise<void>;
 }
+/**
+ * Read-only snapshot of `pairings.json` for callers that just want the
+ * persisted records — no `dial`/`serve`/`loadIdentity` deps, no rendezvous
+ * connections started (e.g. `agentproto doctor`'s devices check). Mirrors
+ * `ensureLoaded`'s parse + v1-legacy flagging; never throws — a missing or
+ * malformed file just yields `[]`.
+ */
+declare function readPairingsSnapshot(path?: string): Promise<PairingRecord[]>;
 declare function createPairingRegistry(deps: PairingRegistryDeps): PairingRegistry;
 
+/**
+ * Daemon-side HOST registry (DEVICES-PLAN PR-C) — the "client" half of
+ * pair/v2, living on the daemon so it's reachable over both an HTTP route
+ * and an MCP tool, not just CLI-local bookkeeping (`client-pairings.ts` /
+ * `pair-transport.ts` are that CLI-local equivalent today).
+ *
+ * Where `pairing-registry.ts` is what a daemon uses to let OTHER machines
+ * pair with and remote-control IT, `host-registry.ts` is what a daemon uses
+ * to register and drive OTHER daemons — reverse pairing. `add()` accepts a
+ * HOST-scoped offer (`agentproto pair offer --host`, offer-url.ts's
+ * `scope`), runs the pair/v2 client handshake, and persists the resulting
+ * pair root; `forwardHttp()` dials on demand, reconnecting over the current
+ * (then previous) epoch token exactly like `pair-transport.ts`'s
+ * `openPairChannel`, forwards one HTTP request over the resulting tunnel
+ * client, and closes. There is no standing connection here — unlike
+ * `PairingRegistry`, a `HostRegistry` never autoconnects or keeps a
+ * reconnect loop parked at the broker; every reach-out is a fresh dial.
+ * That also means shutdown needs no teardown: there is nothing standing to
+ * tear down.
+ *
+ * ## The scope gate
+ *
+ * `add()` REFUSES (throws) any offer whose parsed `scope !== "host"` before
+ * ever dialing anything. This is the default-deny gate PR-C exists to add:
+ * an ordinary "remote-control me" offer (today's `pair offer`, no `--host`)
+ * must not silently become a host registration, even though the underlying
+ * wire capability is identical either way (see offer-url.ts's "Offer scope"
+ * and pairing-registry.ts's `OfferEntry.scope` doc comment for why the
+ * offering daemon's OWN server-side record — not the URL's plaintext
+ * `scope` param — is what's authoritative about what it granted). There is
+ * deliberately no override flag.
+ *
+ * Persisted to `hosts.json` (`~/.agentproto/hosts.json` by default) with the
+ * same atomic-write discipline as `pairings.json` (mkdir, write to a
+ * pid-keyed tmp file at 0600, chmod, rename) and the same lazy-load-on-
+ * first-use pattern.
+ *
+ * ## Online tracking
+ *
+ * `isOnline(fingerprint)` mirrors `PairingRegistry.isOnline`: it's true only
+ * while a `forwardHttp()` call for that fingerprint is in flight (a
+ * reference count, incremented on dial and decremented in a `finally`).
+ * There is no live probe backing `list()` — that would make `devices list`
+ * slow/flaky over N hosts — so `list()`'s `online` is only ever true
+ * immediately after (or during) an actual `forwardHttp`/`devices status`
+ * call, never a background heartbeat. That's enough to make `devices list`
+ * show the right thing right after `devices status`/`exec`, which is what
+ * matters for this PR; a standing/autoconnect host connection with a real
+ * liveness signal is PR-D's to build.
+ */
+
+/** `hosts.json` format. */
+declare const HOSTS_VERSION: 1;
+/** One persisted host — a daemon this daemon can drive. */
+interface HostRecord {
+    /** The target daemon's identity fingerprint (32 hex). */
+    fingerprint: string;
+    /** Human-facing label; defaults to the fingerprint. */
+    name: string;
+    /** Target daemon's static X25519 public key, standard base64 SPKI DER —
+     *  pinned at `add()` time. */
+    daemonX25519Pub: string;
+    /** Target daemon's static Ed25519 public key, standard base64 SPKI DER —
+     *  pinned at `add()` time. */
+    daemonEd25519Pub: string;
+    /** Rendezvous endpoint to reach the host through. */
+    rendezvousUrl: string;
+    /** Long-term shared secret (base64), from which epoch routing tokens
+     *  derive — same derivation as `PairingRecord.pairRoot`. */
+    pairRoot: string;
+    /** ISO-8601 first-add timestamp. */
+    createdAt: string;
+    /** ISO-8601 of the most recent successful `forwardHttp`. */
+    lastSeen: string;
+    /** Set on a host added under the retired pair/v1 protocol. Present for
+     *  parity with `PairingRecord`/`ClientPairing`; pair/v1 offers are refused
+     *  by `parseOfferUrl` before `add()` ever sees them, so this is currently
+     *  unreachable — kept so a future downgrade path has somewhere to flag it. */
+    legacy?: true;
+}
+interface HostRegistryDeps {
+    /** Dial a rendezvous WS and adapt it to a `FrameSink`. Same shape as
+     *  `PairingRegistryDeps.dial` — the CLI's `daemonDialRendezvous` satisfies
+     *  it directly. Rejects if the dial fails or `signal` aborts. */
+    dial: (wsUrl: string, signal: AbortSignal) => Promise<FrameSink>;
+    /** Path to `hosts.json`. Defaults to `~/.agentproto/hosts.json`. */
+    hostsPath?: string;
+    /** Injectable clock (ms). Defaults to Date.now. */
+    now?: () => number;
+    /** Diagnostic log sink. */
+    log?: (line: string) => void;
+    /** Rendezvous dial ceiling per attempt. Default 15s. */
+    dialTimeoutMs?: number;
+    /** Handshake ceiling per attempt. Default 15s. */
+    handshakeTimeoutMs?: number;
+}
+interface ForwardHttpRequest {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+}
+interface ForwardHttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: Uint8Array;
+}
+interface HostRegistry {
+    /**
+     * Accept an offer URL and register the target daemon as a driveable host.
+     * REFUSES (throws a plain `Error`) unless the parsed offer has
+     * `scope === "host"` — no dial is attempted in that case. Otherwise: dials
+     * the offer's rendezvous, runs the pair/v2 client handshake, verifies the
+     * derived peer fingerprint matches the offer's `id` (defence in depth,
+     * mirrors `pair-transport.ts`'s `acceptOffer`), derives the pair root, and
+     * persists a `HostRecord` (upserted by fingerprint — re-adding replaces).
+     */
+    add(offerUrl: string, name?: string): Promise<{
+        fingerprint: string;
+        name: string;
+        rendezvousUrl: string;
+    }>;
+    /** All persisted hosts (copies). Loads `hosts.json` on first call. */
+    list(): Promise<HostRecord[]>;
+    /** Rename a host (fingerprint or current name). Returns false when nothing
+     *  matched; throws on an empty `newName`. */
+    rename(idOrName: string, newName: string): Promise<boolean>;
+    /** Drop a host by fingerprint or name. Returns false when nothing matched. */
+    revoke(idOrName: string): Promise<boolean>;
+    /** Is a `forwardHttp` call for this fingerprint in flight right now? */
+    isOnline(fingerprint: string): boolean;
+    /**
+     * On-demand: dial the host, run the client handshake against the current
+     * epoch's tokens (falling back to the previous epoch, bridging clock
+     * skew — same two-attempt shape as `pair-transport.ts`'s
+     * `openPairChannel`), forward one HTTP request over the resulting tunnel
+     * client, then close. Throws with a re-pair hint if every attempt hangs up
+     * on the hello (likely a pair/v1 peer).
+     */
+    forwardHttp(idOrName: string, req: ForwardHttpRequest): Promise<ForwardHttpResponse>;
+}
+declare function createHostRegistry(deps: HostRegistryDeps): HostRegistry;
+
 /**
  * Shared types for pluggable sandbox providers.
  *
@@ -2832,6 +3429,17 @@ interface SandboxProviderHandle extends AdapterHandle {
      * credentials (e.g. `local`).
      */
     readonly setupFields?: readonly SetupField[];
+    /**
+     * The directory INSIDE the box a spawned agent session should default to
+     * when the caller passed no explicit `cwd` — e.g. e2b/Box's login home
+     * `/home/user`. Absent for a same-machine passthrough provider (`local`),
+     * where the HOST's own resolved cwd is already a valid path in the box
+     * (they're the same filesystem) and forwarding it as-is is correct.
+     * Presence of this field is also the signal `bootSandboxAgentSession`
+     * uses to reject an explicit HOST-only path (e.g. `/Volumes/...`) instead
+     * of forwarding it into a box where it can never resolve.
+     */
+    readonly defaultCwd?: string;
 }
 
 /**
@@ -3331,12 +3939,21 @@ interface OrchestratorGatewayDeps {
      *  spawn is rejected with `sandbox_provider_not_found`, exactly as the
      *  root gateway would be without it. */
     resolveSandboxProvider?: SandboxProviderResolver;
-    /** Forwarded to `registerSessionTools` — config.json
-     *  `defaults.agentPromptInterrupt`, the unset-default for `interrupt` on
-     *  `agent_prompt` / `message_parent`. Threaded here so a child driving its
-     *  parent/peers (or reporting up via `message_parent`) through this scoped
-     *  gateway honours the same daemon default as the root `/mcp` surface. */
+    /** EXPLICIT override for config.json `defaults.agentPromptInterrupt` —
+     *  wins over the fresh per-call resolve (`resolveMessagingDefaults`,
+     *  see the factory body below). Tests inject this to pin a value without
+     *  touching the filesystem; production leaves it unset so every request
+     *  reads the live config, hot-applying a `config_set` change with no
+     *  restart. Forwarded to `registerSessionTools`. */
     defaultAgentPromptInterrupt?: boolean;
+    /** EXPLICIT override for config.json `defaults.messaging.allowSiblings` —
+     *  see `defaultAgentPromptInterrupt` above for the override/resolve
+     *  precedence. Forwarded to `registerAgentTools`. */
+    messagingAllowSiblings?: boolean;
+    /** EXPLICIT override for config.json `defaults.messaging.agentInterrupt` —
+     *  see `defaultAgentPromptInterrupt` above for the override/resolve
+     *  precedence. Forwarded to `registerAgentTools`. */
+    messagingAgentInterrupt?: "allow" | "deny";
 }
 type OrchestratorMcpServerFactory = (scope: OrchestratorScope) => Promise<McpServer>;
 /**
@@ -3391,7 +4008,7 @@ interface OrphanReaperRegistry {
     list(opts?: {
         includeArchived?: boolean;
     }): readonly SessionDescriptor[];
-    kill(id: string, signal?: NodeJS.Signals): boolean;
+    kill(id: string, signal?: NodeJS.Signals, reason?: SessionEndReason): boolean;
 }
 /**
  * Reap a dying parent's live descendants (WP-B — orphan reaping). A
@@ -3579,6 +4196,77 @@ declare function createActivityProjector(opts: {
     resolvePrState?: PrStateResolver;
 }): ActivityProjector;
 
+/**
+ * Spawn-time role profiles — the primitive that decides whether a
+ * spawned agent may itself delegate (spawn further children).
+ *
+ * A role is 3 layers:
+ *   - `disposition`  — a system-prompt fragment. Soft: sets the mindset.
+ *   - `toolPolicy`   — whether delegation tools are injected into the
+ *     child at all. HARD: enforced by the daemon at the `agent_start`
+ *     injection point (`session-spawn.ts`), not by the child's own
+ *     behaviour. A child cannot widen its own `toolPolicy` — not via
+ *     `promptAppend`, not by requesting `orchestrator` itself.
+ *   - `skills[]`     — role-specific skill set (built-ins ship empty/
+ *     unset; a future pack-carried role can populate this).
+ *
+ * Why the asymmetry matters: a process can bring its own disposition
+ * and skills (those are portable, could live in a skill/pack), but it
+ * can never strip tools the daemon already injected into it. Only the
+ * spawner controls that — which is exactly why `toolPolicy` must be
+ * resolved and enforced here, at spawn time, rather than left to a
+ * prompt instruction the model could rationalize past.
+ */
+
+type DelegationPolicy = "allow" | "deny";
+interface RoleToolPolicy {
+    delegation: DelegationPolicy;
+}
+interface RoleProfile {
+    name: string;
+    disposition: string;
+    toolPolicy: RoleToolPolicy;
+    skills?: string[];
+    /**
+     * Privilege level in the spawn lattice. Higher = more privileged.
+     * The default spawn-gate rule (`canSpawn`) is non-escalation: a
+     * parent may spawn a child only when `child.level <= parent.level`
+     * — peers and subordinates are fine, spawning something MORE
+     * privileged than yourself is not. (Unbounded same-level recursion —
+     * e.g. supervisor spawning supervisor spawning supervisor — is a
+     * pre-existing, deliberate pattern bounded separately by
+     * `maxDepth`/`maxChildren`, not this lattice; see `spawnableRoles`
+     * below for a role that also needs to cap recursion itself.)
+     * `spawnableRoles` (below), when set, opts a role into a closed
+     * allowlist instead — level is then only used for display/ordering.
+     */
+    level: number;
+    /**
+     * Closed allowlist of role names this role may spawn, by name — the
+     * opt-in "figé pipeline" mode. When set, `canSpawn` checks name
+     * membership instead of the level comparison. Undefined (the
+     * default, open mode) ⇒ non-escalation by `level`.
+     */
+    spawnableRoles?: string[];
+    /**
+     * Role-level default for the daemon self-mount's deferred/lazy tool
+     * loading (harness-parity item 3 — see `deferred-tools.ts`). Applied to
+     * the injected `mcpServers` entry (`session-spawn.ts`'s
+     * `shouldInjectDaemonSelfMount` path) as `?deferred=1|0` when the spawn
+     * itself didn't pass an explicit `deferredTools` override. Undefined ⇒
+     * no role-level opinion, the gateway's own boot-time default
+     * (`defaults.mcp.deferredTools` in config.json) applies unchanged.
+     */
+    deferredTools?: boolean;
+    /**
+     * Role-level default for `agent_start.browser` (see `browser-mount.ts`):
+     * `"headless"` gives every spawn of this role its own isolated headless
+     * Chrome. An explicit spawn `browser` wins; undefined ⇒ no opinion (the
+     * user preset, then `defaults.spawn.browser`, decide).
+     */
+    browser?: SpawnBrowserMode;
+}
+
 /**
  * Daemon-side AGENTS.md resolution + injection (WP-R2).
  *
@@ -3607,7 +4295,44 @@ declare function createActivityProjector(opts: {
  * absent — plus a standing cd-contract sentence regardless of mode.
  */
 type AgentsMdMode = "inline" | "pointer" | "absent";
+/** The resolved AGENTS.md's absolute path; undefined when mode is "absent". */
+interface AgentsMdResolution {
+    mode: AgentsMdMode;
+    /** Absolute path of the resolved AGENTS.md. Undefined when mode is
+     *  `"absent"`. */
+    path?: string;
+    /** Full text of the AGENTS.md (inline mode only). */
+    content?: string;
+    /** The prompt block to inject (full inline text or a pointer), or
+     *  undefined when absent. Excludes the always-present cd-contract line. */
+    block?: string;
+    /** The standing cd-contract sentence, present in every mode. */
+    contractLine: string;
+}
+
+interface WorkspaceRulesResolution {
+    /** Absolute path of the resolved RULES.md. Undefined when absent (or a
+     *  read failure degraded to absent). */
+    path?: string;
+    /** Full text of the RULES.md, inlined. Present exactly when `block` is. */
+    content?: string;
+    /** The prompt block to inject, or undefined when absent. */
+    block?: string;
+}
 
+/** The `appServe` request carried on `agent_start` — an in-box app dir plus
+ *  the port to serve its UI on. */
+interface SandboxAppServeSpec {
+    /** Absolute path to the app's directory INSIDE the box (e.g.
+     *  `/home/user/apps/<slug>`). Must not contain a single quote — the
+     *  launcher shell-quotes it. */
+    dir: string;
+    /** Port `agentproto app serve` binds inside the box. Must also be exposed
+     *  by the provider (the spawn path appends it to `extraPorts` so a
+     *  boot-time exposure exists on providers that pre-resolve). Defaults to
+     *  `DEFAULT_APP_SERVE_PORT` when omitted. */
+    port?: number;
+}
 /** What a served app records on the session descriptor and echoes in the
  *  spawn result — non-secret, caller-visible. */
 interface SessionAppServeInfo {
@@ -3833,6 +4558,460 @@ declare function loadWorktreeIsolation(loadCfg?: () => Promise<{
     };
 }>): Promise<WorktreeIsolationMode>;
 
+/**
+ * Policy layer for `agent_start.attach` — the config-driven decision of WHO a
+ * spawn nests under, kept deliberately separate (and pure) from the spawn
+ * plumbing in `session-spawn.ts`, exactly as `worktree-isolation.ts` is for
+ * `agent_start.worktree`.
+ *
+ * The problem it fixes: on the plain `/mcp` path (no scoped orchestrator
+ * gateway), a spawn was attributed to a parent ONLY when the caller passed an
+ * explicit `parentSessionId` hint — so a supervisor that spawned an executor
+ * without wiring itself as an orchestrator produced a depth-0 ORPHAN. The
+ * daemon already knows the caller's own id on that path (the trusted
+ * `?callerSessionId=` query the self-ref `mcpServers` URL carries — PR 7 /
+ * Gap 7), it just wasn't being used for lineage. This module decides whether
+ * to use it.
+ *
+ * Trust boundary (unchanged from the hint): the scoped `/mcp/orchestrator`
+ * gateway's token is the UNSPOOFABLE source — when a `callerScope` is present
+ * the caller derives its parent from the token and this whole module is
+ * bypassed (see `session-spawn.ts`). Everything here is descriptor-only
+ * lineage on the anonymous root path; it never moves the gating `childDepth`
+ * and so never relaxes a depth-gated worktree/role guard.
+ */
+
+/**
+ * The `agent_start.attach` field. `true` opts in to attaching under the
+ * derived parent (the caller's own id / an explicit hint) even when the
+ * policy is `on-request`; an object additionally pins an explicit parent id;
+ * `false` forces an INDEPENDENT root (no parent, depth 0) regardless of
+ * policy or derivable identity — the deliberate "launch detached" escape
+ * hatch, mirroring `worktree: false`. Omitted ⇒ the policy mode decides.
+ */
+type AttachField = boolean | {
+    parent?: string;
+};
+
+/**
+ * Shared `agent_start` spawn logic — orchestrator scoped sub-gateway
+ * minting, `mcpServers` merge, hermes default-mcpServers safety net,
+ * depth/quota checks. Extracted from `agent-tools.ts` (the MCP tool)
+ * so the HTTP route can reuse it without re-implementing (and
+ * re-drifting from) the same behaviour.
+ */
+
+/** `agent_start.sandbox`'s inline-spec form, plus the PR3 reuse field. See
+ *  `SpawnAgentSessionInput.sandbox`. */
+type SandboxSpecInput = SandboxSpec & {
+    reuse?: string;
+};
+/** Matches `RegisterAgentToolsOptions.buildOrchestratorMcp` in
+ *  agent-tools.ts — kept as its own alias here since that's the shape
+ *  actually passed in (opts required), not the more permissive
+ *  `OrchestratorInjector` (opts optional) from orchestrator-gateway.ts. */
+type BuildOrchestratorMcp = (opts: {
+    tools?: readonly string[];
+    caller?: OrchestratorScope;
+    maxDepth?: number;
+    maxChildren?: number;
+    role?: string;
+}) => {
+    entry: AcpMcpServer;
+    bindLifecycle: (sessionId: string) => () => void;
+    /** The minted scope — only `tools` (the effective, narrowed allowlist)
+     *  is read here, to tell whether the child can actually reach
+     *  `agent_start` through it (see `delegationReachFor`). Optional so
+     *  minimal injectors (tests) needn't return it. */
+    scope?: {
+        tools: ReadonlySet<string>;
+    };
+};
+interface SpawnAgentSessionDeps {
+    registry: SessionsRegistry;
+    /** Required — callers must check for its absence themselves (the MCP
+     *  tool and HTTP route each have their own "not enabled" response
+     *  shape for the missing-resolver case). */
+    resolveAgentAdapter: AgentAdapterResolver;
+    /** Optional orchestrator-injection builder (WP3). See
+     *  `RegisterAgentToolsOptions.buildOrchestratorMcp` for the full
+     *  contract. Omitted → `orchestrator` is rejected with
+     *  `orchestrator_not_enabled`. */
+    buildOrchestratorMcp?: BuildOrchestratorMcp;
+    /** The daemon's own plain `/mcp` gateway URL. See
+     *  `RegisterAgentToolsOptions.daemonMcpUrl`. */
+    daemonMcpUrl?: string;
+    /** Calling orchestrator's scope (orchestrator WP4). See
+     *  `RegisterAgentToolsOptions.callerScope`. */
+    callerScope?: OrchestratorScope;
+    /** Optional webhook notifier — see `RegisterAgentToolsOptions.webhookNotifier`. */
+    webhookNotifier?: WebhookNotifier;
+    /** Loads config.json's `defaults` block (global + per-adapter skills/
+     *  options auto-applied at every spawn — see `resolveSpawnDefaults`).
+     *  Defaults to reading the real `~/.agentproto/config.json` via
+     *  `loadConfig` when omitted; tests inject a stub to avoid touching
+     *  the real file. */
+    loadDefaultsConfig?: () => Promise<SpawnDefaultsConfig | undefined>;
+    /** Builds the per-session headless-browser mount for `browser:
+     *  "headless"` (see `browser-mount.ts`). Defaults to the real resolver
+     *  (installs chrome-devtools-mcp on first use); tests inject a stub. */
+    resolveHeadlessBrowser?: ResolveHeadlessBrowser;
+    /** Loads the custom (pack-carried) role registry, merged with the
+     *  two built-ins by `resolveRole`/`canSpawn` — see `role.ts`'s
+     *  `mergeRoleRegistry`. Defaults to `loadDefaultRoleRegistry()`
+     *  (`~/.agentproto/roles/` + adapter-carried packs) when omitted;
+     *  tests inject a stub registry to avoid touching the real
+     *  filesystem. */
+    loadRoleRegistry?: () => Promise<Record<string, RoleProfile>>;
+    /** Resolves an `agent_start.sandbox` slug (or an inline spec's own
+     *  `.provider`) to a concrete sandbox provider handle. Required for
+     *  `input.sandbox` — omitted ⇒ `sandbox_provider_not_found`. */
+    resolveSandboxProvider?: SandboxProviderResolver;
+    /** Provision a git worktree and return the cwd the spawn should land in —
+     *  the injected port behind `agent_start.worktree` (see
+     *  `worktree-isolation.ts`). Wired at the composition root by a host that
+     *  depends on `@agentproto/worktree` (the CLI). Omitted ⇒ a spawn the
+     *  policy says to isolate fails with `worktree_provisioner_not_enabled`
+     *  rather than silently spawning unisolated. */
+    provisionWorktree?: WorktreeProvisioner;
+    /** Resolves the effective `worktrees.isolation` policy (env > config >
+     *  `on-request`). Defaults to reading the real `~/.agentproto/config.json`
+     *  via `loadWorktreeIsolation` when omitted; tests inject a stub to pin the
+     *  mode without touching the real file or env. */
+    resolveWorktreeIsolation?: () => Promise<WorktreeIsolationMode>;
+    /** Resolves the effective `spawn.attach` policy (env > config > `always`).
+     *  Defaults to `loadSpawnAttach` (reads the real config) when omitted;
+     *  tests inject a stub to pin the mode without touching env or the file. */
+    resolveSpawnAttach?: () => Promise<SpawnAttachMode>;
+    /** Resolves the effective `spawn.dedupe` policy (env > config > `always`).
+     *  Defaults to `loadSpawnDedupe` (reads the real config) when omitted;
+     *  tests inject a stub to pin the mode without touching env or the file.
+     *  See `spawn-dedupe.ts`. */
+    resolveSpawnDedupe?: () => Promise<SpawnDedupeMode>;
+    /** Resolves the effective `provenance.wrapGh` opt-in (env > config >
+     *  `false`). When it resolves true, a `gh` PATH shim is prepended to the
+     *  spawned session's env so any `gh pr create` it (or an adapter
+     *  subprocess) runs gets the daemon's provenance footer appended to the
+     *  created PR's body — see `gh-provenance-shim.ts`. Defaults to
+     *  `loadProvenanceWrapGh` (reads the real config) when omitted; tests
+     *  inject a stub to pin it without touching env or the file. */
+    resolveProvenanceWrapGh?: () => Promise<boolean>;
+    /** Resolves + shapes the AGENTS.md for a spawn's `cwd` (see
+     *  `agents-md.ts`): inline / pointer / absent, plus the standing cd-contract
+     *  line. Defaults to the real resolver over `loadAgentsMdInlineMaxKb`'s
+     *  config-derived threshold when omitted; tests inject a stub to avoid
+     *  touching the filesystem, git, and the real config on every spawn. */
+    resolveAgentsMd?: (cwd: string, inlineMaxKb?: number) => Promise<AgentsMdResolution>;
+    /** Resolves + shapes the per-workspace RULES.md for a spawn (see
+     *  `workspace-rules.ts`): the path of the workspace's `RULES.md`, inlined
+     *  in full when present, absent otherwise. Injected into EVERY spawn in
+     *  the workspace (root and nested — no depth gate). Defaults to the real
+     *  resolver over the workspace state bucket when omitted; tests inject a
+     *  stub to avoid touching the real `~/.agentproto` directory. */
+    resolveWorkspaceRules?: (slug: string | undefined) => Promise<WorkspaceRulesResolution>;
+    /** Feeds the adapter-capability spawn guard (`checkModelAdapterEligibility`)
+     *  — the SAME `listCatalogModels` the `catalog_models` MCP tool /
+     *  `GET /catalog/models` route already use (`RegisterAgentToolsOptions.
+     *  listCatalogModels`), reused here rather than re-derived. Omitted ⇒ the
+     *  guard is skipped — a spawn that would 404 upstream on an adapter's
+     *  manifest not covering the requested model still reaches the driver,
+     *  same as before this guard existed. */
+    listCatalogModels?: CatalogModelsLister;
+    /** Ensure the local `llm-endpoint` proxy sidecar (`LlmEndpointRegistry`)
+     *  is up before a spawn that bills through it. Without this hook, a spawn
+     *  whose resolved gateway is `"llm-endpoint"` assumed the sidecar was
+     *  already running (started externally, or via the `llm_endpoint_start`
+     *  MCP tool) — a fresh install with `features.llmEndpoint` on but nothing
+     *  having called that tool yet would spawn fine and only fail once the
+     *  adapter made its first request. Wired to the registry's own
+     *  (idempotent) `start()` at the composition root; omitted ⇒ unchanged
+     *  pre-existing behavior. Best-effort: a rejection here is swallowed by
+     *  the caller, not surfaced as a spawn failure — the adapter's own first
+     *  request is left to report the real connection error. */
+    ensureLlmEndpointRunning?: () => Promise<void>;
+}
+interface SpawnAgentSessionInput {
+    adapter: string;
+    /** Canonical harness slug — recorded on the descriptor; defaults to `adapter`. */
+    harness?: string;
+    cwd?: string;
+    workspaceSlug?: string;
+    /** Trusted-loopback parent-lineage hint (WP-R1). Attributes this spawn to a
+     *  logical parent session so it nests under that node in the sessions tree,
+     *  filling the gap that otherwise leaves an anonymous `agent_start` (an
+     *  agent-to-agent spawn on the root `/mcp`, or a caller that IS a session but
+     *  didn't come through the scoped orchestrator gateway) a depth-0 orphan.
+     *
+     *  Trust boundary: the scoped `/mcp/orchestrator` gateway derives parent from
+     *  its unspoofable scope token, so a hint arriving WITH a `callerScope` is
+     *  IGNORED — the scope always wins. The hint is honoured ONLY on the
+     *  anonymous root path (no `callerScope`), where there is no scope to
+     *  attribute from. `depth` is derived from the resolved parent descriptor
+     *  (parent's `depth + 1`, defaulting to 1 when the parent isn't registered)
+     *  rather than trusted from the caller. Descriptor-only: a hint never relaxes
+     *  the depth-gated worktree/role guards — declaring a logical parent is not
+     *  the same as being a nested (scoped) spawn. */
+    parentSessionId?: string;
+    /** Attach policy override for THIS spawn (`agent_start.attach`). `false`
+     *  forces an independent root even when a parent is derivable; `true` opts
+     *  in to attaching under the derived parent even under an `on-request`
+     *  policy; `{ parent }` pins an explicit parent. Omitted ⇒ the daemon's
+     *  `spawn.attach` policy decides. Resolved together with `parentSessionId`
+     *  and `autoParentSessionId` in `decideSpawnAttach` — see `spawn-attach.ts`.
+     *  Ignored WITH a `callerScope` (the scoped orchestrator token always wins). */
+    attach?: AttachField;
+    /** Daemon-DERIVED caller session id — the spawning session's own id, read
+     *  from the trusted `?callerSessionId=` query the self-ref `mcpServers` URL
+     *  carries (PR 7 / Gap 7), NOT from the caller's arguments. This is the
+     *  implicit auto-parent that makes attach-by-default work without the caller
+     *  passing its own id. Threaded from `registerAgentTools`' `callerSessionId`
+     *  option; lower precedence than an explicit `parentSessionId` hint. */
+    autoParentSessionId?: string;
+    /** Task-board pin for the spawned child, stamped onto its descriptor as
+     *  `meta.boardId`. The Task ledger's board resolution prefers this over
+     *  the `parentSessionId` lineage walk (see task-ledger.ts's
+     *  `resolveBoardId`), so a client spawning several depth-0 roots — a
+     *  cowork/operator harness fanning out executors with no shared lineage —
+     *  can join them all onto ONE board. Descriptor-only: it never enters the
+     *  depth/quota/role gates, and an explicit `boardId` on a task verb still
+     *  wins over it. */
+    boardId?: string;
+    /** Source label for this spawn (channel/harness). Descriptor-only. */
+    origin?: string;
+    /** Installed app id this spawn runs on behalf of (`app_run` sets this to
+     *  the app's own id). Forwarded to the child process as `APP_ID_ENV` — a
+     *  daemon-tool proxy the child builds (mastra-agent's `daemon-mcp-tools.ts`,
+     *  P7) auto-injects it into an `app_*` tool call that omits `appId`, since
+     *  the model driving the session has no way to know its own appId unless
+     *  told. Absent on a spawn made outside `app_run`. */
+    appId?: string;
+    /** Reattach to a pre-existing adapter-native session (claude-code's
+     *  conversation id, hermes' chat handle, …) instead of starting
+     *  blank. Not exposed on the MCP `agent_start` tool today — only the
+     *  HTTP route (`sessions restart`) passes this. */
+    resumeSessionId?: string;
+    /** The caller's initial ask — a plain string (the common case, composed
+     *  with the role/AGENTS.md/RULES.md preamble below into one string turn),
+     *  or a content block / block array (an attachment-bearing first message,
+     *  same loose shape `POST /sessions/:id/prompt` accepts). The block form
+     *  is a narrow path: composing daemon-synthesized preamble TEXT onto a
+     *  turn that opens with an image isn't meaningful string concatenation,
+     *  so it SKIPS the whole preamble composition below (role disposition,
+     *  AGENTS.md, RULES.md, parent-lineage line, posture-as-prompt fallback)
+     *  and is sent to the adapter verbatim — see `effectivePrompt`'s doc.
+     *  Acceptable because this path is human/UI-initiated (an attachment
+     *  typed into a chat composer), not the orchestrator-driven role spawns
+     *  that actually depend on the composed disposition text. */
+    prompt?: string | Record<string, unknown> | unknown[];
+    label?: string;
+    /** Explicit session title (SPEC-3 FIX C, `agentproto sessions start
+     *  --title`). When set, it wins over the first-sentence derivation from
+     *  `prompt` — so a CLI-named session isn't limited to whatever its opening
+     *  prompt happened to say. Unlike `label`, it fills the `title` slot, so a
+     *  spawner `label` still out-ranks it in the display chain. */
+    title?: string;
+    mode?: string;
+    /** Manifest-declared option id → value map (AIP-45 `options`), applied
+     *  at spawn time alongside `mode`. Forwarded verbatim to the driver's
+     *  `startSession({ options })` → `composeSpawn`'s option patches. */
+    options?: Record<string, boolean | number | string>;
+    /** Normalized, adapter-agnostic skill ids for this session. Merged with
+     *  config.json's `defaults.skills` / `defaults.adapters.<slug>.skills`
+     *  (global < per-adapter < this field, which REPLACES the union rather
+     *  than merging into it when provided — a deliberate exact set). Folded
+     *  into `options.skills` per the resolved adapter's declared `skills`
+     *  option shape (e.g. hermes' comma-joined string); adapters with no
+     *  such option (e.g. claude-code, which auto-discovers skills) ignore
+     *  it. See `resolveSpawnDefaults` / `normalizeSkillsOption`. */
+    skills?: string[];
+    model?: string;
+    effort?: string;
+    /** Decomposed route identity.  This is canonical transport; `mode` remains
+     * a legacy adapter projection only. */
+    route?: RouteSpec;
+    /** Named billing credential. Resolved from auth-profiles + keychain at the
+     * final spawn boundary; the secret never crosses HTTP/MCP. */
+    access?: {
+        profileRef?: string;
+    };
+    posture?: Posture;
+    contextProfile?: ContextProfile;
+    /** A preloaded user preset. Callers resolve its id at their boundary so a
+     * preset can also provide the adapter before this core is invoked. */
+    preset?: UserPreset;
+    /**
+     * Deterministic billing-auth mode + EXPLICIT credential for adapters that
+     * declare an env-var vocabulary for it (today: claude-code — see
+     * `AgentCliAuth.modes` in `@agentproto/driver-agent-cli`). `mode` wins over
+     * `~/.agentproto/config.json`'s `defaults.adapters.<slug>.auth.mode`
+     * (default `"subscription"`); the credential (`token` for `"subscription"`,
+     * `apiKey` for `"api-key"`) wins over the config field matching the
+     * RESOLVED mode — see `resolveSpawnDefaults`. Never read from the ambient
+     * shell env; never logged (only a fingerprint is recorded on the session
+     * descriptor — see `credentialFingerprint`). Adapters that don't declare
+     * the vocabulary ignore this field entirely.
+     */
+    auth?: DefaultsAdapterAuthConfig;
+    mcpServers?: AcpMcpServer[];
+    orchestrator?: boolean | {
+        tools?: string[];
+        maxDepth?: number;
+        maxChildren?: number;
+    };
+    notifyUrl?: string;
+    wait?: boolean;
+    maxCostUsd?: number;
+    /** Windowed cost-budget cap (phase 4). DISTINCT from the scalar `maxCostUsd`
+     *  session-kill: this is recorded on the descriptor/runtime and drives an
+     *  auto-attached governance policy (`policy:failed` on windowed overage) — it
+     *  never kills the session. Omit ⇒ no windowed budget. */
+    costBudget?: CostBudget;
+    /** Opt-in auto-restart policy (restart-scheduler, PR-2). When set, an
+     *  unexpected death (`crashed` and/or `error`, per `restartPolicy.on`) is
+     *  proactively revived in place — see `RestartPolicy`'s doc in
+     *  `sessions.ts`. Omitted ⇒ today's lazy-resume-only behaviour. */
+    restartPolicy?: RestartPolicy;
+    /** Context-continuity policy for this session — controls warning,
+     *  opportunistic compaction, fresh-continuation, and hard-stop thresholds.
+     *  Resolved from global → per-adapter → per-model → explicit override. */
+    contextContinuity?: ContextContinuityPolicy;
+    /** Spawn-time role — `"executor"` | `"supervisor"` | omitted. See
+     *  `resolveRole` in `role.ts`. Omitted ⇒ derived from spawn depth
+     *  against `defaults.defaultRoleDepthCutoff` (default 1). A resolved
+     *  role with `toolPolicy.delegation === "deny"` is a HARD gate:
+     *  `orchestrator` is ignored outright and the hermes/default
+     *  full-gateway injection excludes `DELEGATION_TOOL_NAMES` — neither
+     *  this field's own request nor `promptAppend` can re-open it. */
+    role?: string;
+    /** One-off runtime text layered ON TOP of the resolved role's
+     *  disposition (never replacing it) and prepended to `prompt`. See
+     *  `composeRoleContext`. Cannot widen `toolPolicy` — see `role` above. */
+    promptAppend?: string;
+    /** Per-spawn override for the daemon self-mount's deferred/lazy
+     *  `tools/list` loading (harness-parity item 3 — see `deferred-tools.ts`).
+     *  Wins over the resolved role's own default (`RoleProfile.deferredTools`
+     *  — on for `executor`), which in turn only applies when this is
+     *  omitted. Threaded onto the injected `mcpServers` self-mount ref as
+     *  `?deferred=1|0` (`shouldInjectDaemonSelfMount` path below); has no
+     *  effect on a caller-supplied `mcpServers` (that URL is the caller's to
+     *  compose). Omitted entirely ⇒ no override at all — the gateway's own
+     *  boot-time `defaults.mcp.deferredTools` default applies unchanged. */
+    deferredTools?: boolean;
+    /** Give the agent its own isolated headless Chrome: a per-session
+     *  chrome-devtools-mcp stdio server appended to `mcpServers` (named
+     *  `browser`), plus a short prompt hint naming its tools. Wins over the
+     *  resolved role's `browser`, then the user preset's, then config
+     *  `defaults.spawn.browser`; all unset ⇒ off. Explicit `true` with a
+     *  `sandbox` spawn is rejected (no Chrome in the box image yet). */
+    browser?: SpawnBrowserMode;
+    /** Opt this session into Langfuse tracing (prompt/completion + tool spans +
+     *  tokens/cost). Effective opt-in is `trace ?? langfuseTracingDefault ?? false`
+     *  — see `SpawnAgentInput.trace` in sessions.ts. */
+    trace?: boolean;
+    /** Run this session inside a sandbox instead of on the host — a provider
+     *  slug from `list_sandbox_providers` (e.g. `"local"`, `"e2b"`), or an
+     *  inline AIP-36 `SandboxSpec`, optionally carrying `reuse: "<sandboxId>"`
+     *  to reconnect to an existing box instead of booting fresh. When set,
+     *  this branch resolves the provider, boots (or reconnects) the box,
+     *  spawns `adapter` on the BOX's own `agent_start`, and wires a
+     *  `SandboxAgentSessionProxy` in place of the local `resolveAgentAdapter`
+     *  path — see `sandbox-agent-session-proxy.ts`. */
+    sandbox?: string | SandboxSpecInput;
+    /** WP3 — serve an agentproto app's UI from INSIDE the sandbox box and
+     *  return its public URL on the descriptor + result. Requires `sandbox`
+     *  (a non-sandbox spawn carrying `appServe` is rejected): the app dir is
+     *  resolved INSIDE the box (e.g. `/home/user/apps/<slug>` on the
+     *  workstation image), installed via the box daemon's `app_install`, and
+     *  `agentproto app serve --host 0.0.0.0 --port <port>` is launched
+     *  detached through the box's `command_execute`. The port is appended to
+     *  the spec's `extraPorts` so the provider resolves its public URL (also
+     *  stamped into `sandboxPorts`), and the serve result lands on the
+     *  descriptor's `appServe` field. See `sandbox-app-serve.ts`. */
+    appServe?: SandboxAppServeSpec;
+    /** Isolate this session into its own git worktree instead of spawning in
+     *  `cwd` directly. `true` provisions a worktree with an auto-minted branch/
+     *  slug; `{ slug?, base? }` pins the slug and/or the base ref it's cut from.
+     *  Honoured only at spawn depth 0 (a nested spawn inherits the parent's
+     *  ground) and only for a `cwd` inside a git repo (nothing to isolate
+     *  otherwise ⇒ spawns plain). The daemon's `worktrees.isolation` policy can
+     *  force this on (`always`) or off (`never`) regardless — see
+     *  `worktree-isolation.ts`. Ignored entirely for a `sandbox` spawn (the box
+     *  already isolates). Cleanup is the human's job (`agentproto worktree
+     *  rm|archive|gc`); the tree is never auto-removed on session exit. */
+    worktree?: WorktreeField;
+    /** Acknowledge that spawning IN PLACE into a shared, dirty working tree is
+     *  intended, silencing the `sharedDirtyCwd` warning a nested implicit spawn
+     *  would otherwise emit (see `decideWorktreeIsolation`). Only meaningful for
+     *  a nested (depth > 0) spawn with no `worktree` request and no `sandbox`;
+     *  ignored everywhere else. Default false — the warning fires. */
+    allowSharedCwd?: boolean;
+    /** Start this session in permission-hold mode: every ACP permission request
+     *  is surfaced + parked in the cross-session inbox (`permissions_list` /
+     *  `permissions_respond`) instead of auto-answered. Threaded to the driver's
+     *  `startSession({ permissionHold })` and recorded on the descriptor. Ignored
+     *  for sandbox spawns (the box's own daemon owns permission handling).
+     *  Default false — unchanged auto-answer behaviour. */
+    permissionHold?: boolean;
+    /** Opt this child into the direct in-band crash notification: when it
+     *  crashes (`markCrashed`), the supervisor-notify subscriber
+     *  (`supervisor-notify.ts`) delivers a `[child-crashed] …` notice into its
+     *  `parentSessionId`, if any — enqueued immediately when the parent is
+     *  alive and idle, queued for its next turn when busy (never
+     *  interrupted). Recorded verbatim onto {@link SessionDescriptor
+     *  .notifyParentOnCrash}; see that field's doc. Default false — the free
+     *  external webhook path (`notifyUrl`) already fires regardless of this
+     *  flag. */
+    notifyParentOnCrash?: boolean;
+    /** Exempt this session from the idle-reaper (`isReapable` in
+     *  idle-reaper.ts) regardless of how long it sits idle. Stamped straight
+     *  onto the descriptor — see `SessionDescriptor.keepAlive`. Default false
+     *  — unchanged reap-eligible behaviour. Toggleable later via the
+     *  `session_set_keepalive` MCP verb. */
+    keepAlive?: boolean;
+    /** Caller-declared "this is the same logical spawn" token — a PROMISE, not
+     *  a guess. A second `agent_start` with the same `(adapter, cwd,
+     *  idempotencyKey)` within `SPAWN_CLAIM_WINDOW_MS` of a SUCCESSFUL spawn
+     *  returns that spawn's descriptor instead of forking a second process —
+     *  the fix for a retried call otherwise silently duplicating a live
+     *  agent. Always wins over the daemon's own derived (implicit) key when
+     *  both would apply — see `dedupe` and `spawn-dedupe.ts`. Omitting this
+     *  does NOT mean "spawn unconditionally" anymore: when the daemon's
+     *  `spawn.dedupe` policy is `"always"` (the default) and this spawn
+     *  carries a `label`, the daemon derives an implicit key in its place —
+     *  see `dedupe` below to opt out per-call. */
+    idempotencyKey?: string;
+    /** Per-call override for the daemon's `spawn.dedupe` policy (implicit
+     *  dedupe when no `idempotencyKey` was supplied — see `spawn-dedupe.ts`).
+     *  `false` is the escape hatch: never derive an implicit key for THIS
+     *  spawn, regardless of policy — mirrors `attach: false` / `worktree:
+     *  false`. `true` forces derivation even under an `"on-request"` policy,
+     *  mirroring `attach: true`. Omitted ⇒ the policy mode decides. Has no
+     *  effect when an explicit `idempotencyKey` is supplied (it already wins
+     *  outright) or when this spawn carries no `label` (nothing to derive
+     *  from either way). */
+    dedupe?: boolean;
+    /**
+     * OS-level confinement for the adapter's OWN spawned process
+     * (`@agentproto/command-sandbox` — macOS Seatbelt / Linux bubblewrap),
+     * threaded verbatim to `resolved.startSession({ commandSandbox })` →
+     * `AgentCliRuntime.start`. NOT the AIP-36 `sandbox` field above — that
+     * boots a whole nested daemon on a different machine/box (remote-box
+     * session provider); this wraps THIS host's spawn argv so the adapter's
+     * own process tree can't read/write outside `cwd` (and, `"strict"`,
+     * reach the network), confinement an ACP permission seam can never see
+     * since it only covers tool calls the adapter chooses to report. Exposed
+     * on the `agent_start` MCP tool schema (`agent-tools.ts`) as of PR 6b —
+     * when omitted here, the driver falls back to the workspace's
+     * `.agentproto/command-sandbox.json` `adapterSpawn` key (a key distinct
+     * from the top-level `mode` that same file also carries for
+     * `command_execute` — see `@agentproto/command-sandbox`'s module doc for
+     * why the two axes are never shared), or stays unconfined if that's unset
+     * too. Ignored for a `sandbox` spawn (the box's own daemon would need to
+     * apply this itself).
+     */
+    commandSandbox?: SandboxMode;
+}
+
 /**
  * Shared kernel for the daemon's worktree-status query surface.
  *
@@ -3853,9 +5032,28 @@ interface WorktreeStatusView {
     branch: string | null;
     class: "reclaim" | "salvage" | "hold";
     reclaimable: boolean;
+    /** Uncommitted work in the tree (modified, staged or untracked paths). */
+    dirty: boolean;
+    /** Per-kind counts, present only when `dirty`. */
+    changes?: {
+        modified: number;
+        staged: number;
+        untracked: number;
+    };
+    /** Ahead/behind vs the base ref the integration check compares against
+     *  (the repo's default branch, e.g. `origin/main`). `null` for a detached
+     *  tip or when git couldn't resolve the base. */
+    base: null | {
+        ref: string;
+        ahead: number;
+        behind: number;
+    };
+    /** Integration state; `number` whenever the forge matched a PR (open,
+     *  merged, partial), `url` when the host knows the forge's web URL. */
     pr: null | {
         state: string;
         number?: number;
+        url?: string;
     };
     sessions: Array<{
         id: string;
@@ -3869,13 +5067,24 @@ interface WorktreeStatusView {
         sessionCount: number;
     };
 }
+/** Narrows a lister call. `paths` computes only those worktrees (compared
+ *  resolved) instead of every worktree of the repo: one forge round-trip for
+ *  a per-session lookup, not one per worktree. */
+interface WorktreeStatusListOptions {
+    paths?: readonly string[];
+}
 /** Injected port: the runtime asks the host to list worktrees for a repo. */
-type WorktreeStatusLister = (repoRoot: string) => Promise<WorktreeStatusView[]>;
+type WorktreeStatusLister = (repoRoot: string, options?: WorktreeStatusListOptions) => Promise<WorktreeStatusView[]>;
+interface ToWorktreeStatusViewOptions {
+    /** Web URL of PR `number` on this repo's forge, when the host can build
+     *  one (e.g. from a GitHub `origin` remote). */
+    prUrl?: (number: number) => string | undefined;
+}
 /**
  * Pure projection from a raw `WorktreeStatusEntry` to the view the daemon
  * surfaces. Kept in one place so the MCP tool and HTTP route cannot drift.
  */
-declare function toWorktreeStatusView(entry: unknown): WorktreeStatusView;
+declare function toWorktreeStatusView(entry: unknown, options?: ToWorktreeStatusViewOptions): WorktreeStatusView;
 
 /**
  * Shared kernel for the daemon's worktree-`gc` surface — the transport twin of
@@ -3910,7 +5119,7 @@ type WorktreeGcClass = "reclaim" | "salvage" | "hold";
  * registration is still there, but the working directory is gone (see
  * `WorktreeGcPlanEntryView.prunable`).
  */
-type WorktreeGcReclaimReason = "dep-bump" | "orphan" | "prunable";
+type WorktreeGcReclaimReason = "dep-bump" | "orphan" | "prunable" | "squash-merged" | "patch-merged" | "content-merged";
 /**
  * One entry of the dry-run plan — a runtime-local projection of a
  * `GcPlanEntry`. `tree` / `integration` / `liveness` are flattened to their
@@ -4002,6 +5211,13 @@ interface WorktreeGcRunInput {
      * command) omits it and gets exactly today's behavior.
      */
     protectedPaths?: string[];
+    /**
+     * Worktree-relative paths whose dirt is known noise: a worktree dirty ONLY
+     * on these reads clean (and is removed non-force after they are restored).
+     * Omitted → the engine's default (`.opencode/package-lock.json`); `[]`
+     * disables the allowlist.
+     */
+    noisePaths?: string[];
 }
 /**
  * Injected port: the runtime asks the host to plan (and, when `apply`, execute)
@@ -4011,6 +5227,161 @@ interface WorktreeGcRunInput {
  */
 type WorktreeGcRunner = (input: WorktreeGcRunInput) => Promise<WorktreeGcResult>;
 
+/**
+ * Shared kernel for the daemon's branch-`gc` surface — the sibling of
+ * `worktree-gc.ts`. The engine (`planBranchGc` / `applyBranchGc` /
+ * `recordBranchVerdict`) lives in `@agentproto/worktree`, a dependency the
+ * runtime deliberately does NOT take, so — exactly as the worktree gc surface
+ * does — the runtime only defines runtime-local structural result types and
+ * the injected ports. The CLI host wires the real runners. Repo-root
+ * resolution is shared with the worktree surfaces via
+ * `resolveWorktreeQueryRoot` in `worktree-status.ts`.
+ */
+type BranchGcKind = "local" | "remote" | "orphan";
+type BranchGcClass = "reclaim" | "review" | "hold";
+type BranchGcStatus = "pr-merged" | "merged" | "squash-merged" | "patch-merged" | "content-merged" | "unmerged";
+type BranchGcReclaimReason = Exclude<BranchGcStatus, "unmerged"> | "reviewed";
+type BranchGcHoldReason = "protected" | "worktree" | "open-pr" | "pr-check-unavailable" | "young";
+type BranchGcTriageVerdict = "obsolete" | "superseded" | "salvage" | "in-progress" | "unclear";
+interface BranchGcCoverageView {
+    residual: number;
+    covered: number;
+    ignored: number;
+    evolved: number;
+    unique: number;
+    deletes: number;
+}
+/** One classified ref — mirrors `BranchGcPlanEntry` structurally. */
+interface BranchGcPlanEntryView {
+    kind: BranchGcKind;
+    name: string;
+    ref: string;
+    sha: string;
+    date: string;
+    author: string;
+    subject: string;
+    remote?: string;
+    status: BranchGcStatus;
+    history: "current" | "pre-rewrite" | "unrelated";
+    ahead: number | null;
+    behind: number | null;
+    conflicts?: boolean;
+    compareBase?: string;
+    mergeBase?: string;
+    mergedTree?: string | null;
+    coverage?: BranchGcCoverageView;
+    residualFiles?: string[];
+    residualFileCount?: number;
+    ageDays: number;
+    class: BranchGcClass;
+    reclaimReason?: BranchGcReclaimReason;
+    mergedPr?: number;
+    holdReason?: BranchGcHoldReason;
+    holdDetail?: string;
+    pushed?: string;
+    verdict?: {
+        triage: BranchGcTriageVerdict;
+        agree: boolean | null;
+        reviewer: string;
+    };
+}
+interface BranchGcPlanView {
+    repoRoot: string;
+    repoName: string;
+    base: string;
+    baseSha: string;
+    baseTree: string;
+    remote: string | null;
+    anchor: string | null;
+    prCheck: {
+        available: boolean;
+        reason?: string;
+    };
+    scopes: BranchGcKind[];
+    minAgeDays: number;
+    includeReviewed: boolean;
+    generatedAt: string;
+    otherRemoteRefs: number;
+    /** true = base-remote `fetch --prune` succeeded; false = failed; null = skipped / no remote. */
+    fetched: boolean | null;
+    entries: BranchGcPlanEntryView[];
+}
+/** kind → class → count, and kind → (status | "protected") → count. */
+interface BranchGcSummaryView {
+    byClass: Record<BranchGcKind, Record<BranchGcClass, number>>;
+    byStatus: Record<BranchGcKind, Record<string, number>>;
+}
+interface BranchGcOutcomeView {
+    kind: BranchGcKind;
+    name: string;
+    sha: string;
+    result: "deleted" | "held" | "skipped-review" | "aborted-moved" | "aborted-vanished" | "aborted-reclassified" | "failed";
+    reclaimReason?: BranchGcReclaimReason;
+    holdReason?: BranchGcHoldReason;
+    currentSha?: string;
+    from?: BranchGcClass;
+    to?: BranchGcClass;
+    message?: string;
+}
+type BranchGcResult = {
+    mode: "plan";
+    plan: BranchGcPlanView;
+    summary: BranchGcSummaryView;
+} | {
+    mode: "apply";
+    plan: BranchGcPlanView;
+    summary: BranchGcSummaryView;
+    outcomes: BranchGcOutcomeView[];
+    /** Restore log written before the first delete; `null` when nothing was deleted. */
+    restoreLog: string | null;
+};
+/** Input to the injected runner. `apply` defaults to false at the tool/route
+ *  boundary — a bare call is a dry run — and an apply requires `scopes`. */
+interface BranchGcRunInput {
+    repoRoot: string;
+    apply: boolean;
+    base?: string;
+    scopes?: BranchGcKind[];
+    minAgeDays?: number;
+    includeReviewed: boolean;
+    anchor?: string;
+}
+type BranchGcRunner = (input: BranchGcRunInput) => Promise<BranchGcResult>;
+interface BranchGcVerdictInput {
+    repoRoot: string;
+    /** Validated by the engine (`branchVerdictSchema`) — the runtime only shapes it. */
+    verdict: unknown;
+}
+interface BranchGcVerdictRecordView {
+    repo: string;
+    name: string;
+    sha: string;
+    recordedAt: string;
+    triage: {
+        verdict: BranchGcTriageVerdict;
+        confidence: number;
+        reason: string;
+        salvage?: string;
+    };
+    gate?: {
+        agree: boolean;
+        verdict: BranchGcTriageVerdict;
+        reason: string;
+        evidence: string[];
+    };
+    reviewer: string;
+}
+/** Injected port: validate + store one reviewer verdict, keyed by repo + tip sha. Throws on an invalid verdict. */
+type BranchGcVerdictRecorder = (input: BranchGcVerdictInput) => Promise<BranchGcVerdictRecordView>;
+interface BranchGcVerdictLookupInput {
+    repoRoot: string;
+    /** Full tip sha — the store's key, together with the repo. */
+    sha: string;
+}
+/** Injected port: the stored verdict for this exact tip, or `null` — a read-only
+ *  lookup, so a caller can check one tip without re-running a whole `branch_gc` plan. */
+type BranchGcVerdictReader = (input: BranchGcVerdictLookupInput) => Promise<BranchGcVerdictRecordView | null>;
+
 /**
  * Pluggable adapter resolver — keeps the runtime package free of any
  * @agentproto/cli dep. The host (cli `serve`, playground, embedding
@@ -4136,12 +5507,10 @@ type AgentAdapterResolver = (slug: string) => Promise<{
     }): Promise<AgentSessionLike>;
     /** Display label for the descriptor's `command` field. */
     commandPreview?: string;
-    /** Best-effort per-session usage reader (adapter-specific, e.g. hermes state.db). */
-    readUsage?: (adapterSessionId: string) => Promise<{
-        costUsd?: number;
-        tokensIn?: number;
-        tokensOut?: number;
-    } | null>;
+    /** Best-effort per-session usage reader (adapter-specific, e.g. hermes
+     *  state.db, the claude-code transcript JSONL). `ctx` carries the spawn's
+     *  cwd + isolated config dir for readers that locate their store by them. */
+    readUsage?: (adapterSessionId: string, ctx?: UsageReadContext) => Promise<UsageReadResult | null>;
     /** AIP-45 `options[]` this adapter's manifest declares (id + type only —
      *  no spawn internals). Lets `session-spawn.ts` fold a config-level
      *  `defaults.skills` list into `options.skills` using the shape the
@@ -4319,6 +5688,142 @@ interface AuthOptions {
     token?: string;
 }
 
+/** One background task as mirrored onto `SessionDescriptor.backgroundTasks`. */
+interface SessionBackgroundTask {
+    taskId: string;
+    /** Friendly task type (`"shell"`, `"monitor"`, ...), when the agent says. */
+    taskKind?: string;
+    description?: string;
+    /** Where the task writes its output, when the agent says. */
+    outputFile?: string;
+    status: "running" | "paused" | "completed" | "failed" | "stopped";
+    summary?: string;
+    toolCallId?: string;
+    /** ISO 8601 — when the daemon first heard of the task. */
+    startedAt: string;
+}
+
+/**
+ * Typed inter-session message envelope (AIP-46 §Session messages).
+ *
+ * A PROMPT is an instruction from whoever drives a session; a MESSAGE is a
+ * report between sessions in the same tree whose sender the DAEMON attests.
+ * Everything in `from` is computed here from the caller's verified identity
+ * and the session forest — a send request can never set it.
+ *
+ * Pure module: no registry, no I/O. The registry (sessions.ts) carries a
+ * `SessionMessage` on a queued prompt (`QueuedPrompt.envelope`), renders it
+ * into the model's context with `renderSessionMessages`, and records it as
+ * its own `session-message` transcript record — never a `user-prompt`.
+ */
+/** Sender's position in the tree, relative to the recipient. */
+type MessageRelation = "child" | "parent" | "sibling" | "human" | "system";
+type MessageKind = "report" | "question" | "blocker" | "done" | "notice";
+type MessageUrgency = "fyi" | "next-turn" | "steer" | "interrupt";
+type MessageDeliveryVia = "wait" | "steer" | "turn" | "interrupt" | "inbox";
+declare const MESSAGE_KINDS: readonly MessageKind[];
+declare const MESSAGE_URGENCIES: readonly MessageUrgency[];
+interface SessionMessageFrom {
+    /** Absent only for relation `human` | `system`. */
+    sessionId?: string;
+    /** Registry label at send time — display only, never identity. */
+    label?: string;
+    role?: string;
+    adapter?: string;
+    relation: MessageRelation;
+}
+interface SessionMessage {
+    /** `msg_<uuid8>`, daemon-minted. */
+    id: string;
+    ts: string;
+    /** Recipient sessionId. */
+    to: string;
+    from: SessionMessageFrom;
+    kind: MessageKind;
+    /** Requested urgency. */
+    urgency: MessageUrgency;
+    /** Stamped on delivery. */
+    delivered?: {
+        via: MessageDeliveryVia;
+        at: string;
+        turnSeq?: number;
+    };
+    /** Thread id; defaults to the first message's id. */
+    correlationId?: string;
+    /** A `SessionMessage.id` this answers. */
+    replyTo?: string;
+    text: string;
+    /** Optional structured payload (≤ `MAX_MESSAGE_DATA_BYTES`). */
+    data?: Record<string, unknown>;
+    ackedAt?: string;
+}
+declare const MAX_MESSAGE_DATA_BYTES: number;
+/** The slice of a session descriptor relation/ACL resolution needs. */
+interface MessageTreeNode {
+    id: string;
+    parentSessionId?: string;
+    label?: string;
+    role?: string;
+    adapterSlug?: string;
+}
+/**
+ * Relation of `sender` to `recipient` in the session forest, or `undefined`
+ * when they're not tree neighbours (cousins, strangers, self). `sender`
+ * absent ⇒ `human` (an HTTP/CLI operator); daemon-originated notices pass
+ * `"system"` explicitly instead of calling this.
+ */
+declare function resolveRelation(sender: MessageTreeNode | undefined, recipient: MessageTreeNode): Exclude<MessageRelation, "system"> | undefined;
+/**
+ * ACL: child→parent, parent→direct child, human/system→any. Sibling↔sibling
+ * only when `allowSiblings` (config-gated, default off). Anything else — a
+ * cousin, a stranger, yourself — is refused.
+ */
+declare function isMessageAllowed(relation: MessageRelation | undefined, opts?: {
+    allowSiblings?: boolean;
+}): relation is MessageRelation;
+/** Build a `from` block from the verified sender + the resolved relation. */
+declare function messageFrom(sender: MessageTreeNode | undefined, relation: MessageRelation): SessionMessageFrom;
+declare function mintMessageId(): string;
+declare function createSessionMessage(input: {
+    to: string;
+    from: SessionMessageFrom;
+    text: string;
+    kind?: MessageKind;
+    urgency?: MessageUrgency;
+    replyTo?: string;
+    correlationId?: string;
+    data?: Record<string, unknown>;
+}): SessionMessage;
+interface MessageFilter {
+    /** Sender session ids, or `"children"` for any message whose relation is
+     *  `child` (i.e. from one of the recipient's own children). */
+    from?: readonly string[] | "children";
+    kind?: readonly MessageKind[];
+    correlationId?: string;
+}
+declare function matchesMessageFilter(msg: SessionMessage, filter: MessageFilter): boolean;
+declare const MESSAGE_TAG = "agentproto-message";
+/** Child-settable label → attribute-safe: `[A-Za-z0-9._-]`, ≤ 48 chars. */
+declare function sanitizeLabel(label: string | undefined): string | undefined;
+/** Escape every envelope/body sentinel inside a message body, so a sender
+ *  can't close the tag early and forge a second header. */
+declare function escapeMessageBody(text: string): string;
+/** A human prompt is NOT wrapped (humans keep today's UX), but a line that
+ *  starts with the envelope sentinel is escaped, so the invariant "text
+ *  outside an `<agentproto-message>` tag is the human" holds. Nothing else
+ *  in human text changes. */
+declare function escapeHumanPrompt(text: string): string;
+declare function renderSessionMessage(msg: SessionMessage): string;
+/** A coalesced batch → sibling tags, one per message, in order. */
+declare function renderSessionMessages(msgs: readonly SessionMessage[]): string;
+/** One-line typed digest of `fyi` messages that never woke the session —
+ *  prepended (as a `system-prompt` slice) to the next turn it runs anyway. */
+declare function renderInboxDigest(msgs: readonly SessionMessage[]): string;
+/** Taught once, the first time a session RECEIVES a message (recorded as a
+ *  `system-prompt`). Children also get the same invariant in their lineage
+ *  line at spawn. */
+declare const MESSAGE_PREAMBLE: string;
+
 /**
  * A per-session observer — the pluggable seam behind the runtime's transcript
  * tap. `sessions.ts` drives one observer per turn (prompt in, each stream event,
@@ -4330,15 +5835,33 @@ interface AuthOptions {
  * calls, so `TranscriptWriter` IS a `SessionObserver` (see transcript-writer.ts).
  */
 
+/** The sender-side trace of a typed message (`session-message-sent`). */
+interface SessionMessageSentRecord {
+    messageId: string;
+    to: string;
+    kind: MessageKind;
+    urgency: MessageUrgency;
+}
 interface SessionObserver {
     /** Record the outgoing message that opens a new turn. `opts.source`, when
      *  set, is the prompt's provenance — `agent:<sessionId>` for a prompt
      *  injected by another session (`agent_prompt` from a supervisor), absent
      *  for a human operator — so a transcript view can attribute the turn to
-     *  its real author instead of "you". */
+     *  its real author instead of "you". `opts.messages`, when set, marks a
+     *  typed-message turn: the writer records one `session-message` per
+     *  message instead of a `user-prompt`. */
     recordPrompt(sessionId: string, message: unknown, opts?: {
         source?: string;
+        system?: string;
+        messages?: readonly SessionMessage[];
     }): void;
+    /** Record, in the SENDER's transcript, that it sent a typed message.
+     *  Optional — observers without a transcript of their own skip it. */
+    recordSessionMessageSent?(sessionId: string, record: SessionMessageSentRecord): void;
+    /** Record a typed message delivered into `sessionId`'s context OUTSIDE a
+     *  turn prompt (e.g. as an `inbox_wait` result) — a standalone
+     *  `session-message` record. Optional, like `recordSessionMessageSent`. */
+    recordSessionMessage?(sessionId: string, message: SessionMessage): void;
     /** Record one structured stream event (text-delta, tool-call, usage_update, …). */
     recordEvent(sessionId: string, evt: AgentStreamEvent): void;
     /** Record the durable turn-boundary / exit usage snapshot. */
@@ -4361,6 +5884,106 @@ interface SessionObserver {
  */
 declare function composeSessionObservers(observers: readonly SessionObserver[]): SessionObserver;
 
+/** Where a session's `contextSize` came from — see the module doc. */
+type ContextSizeSource = "adapter" | "catalog" | "reported";
+
+/**
+ * Derived session outcome (Level 1) — what an ended agent-cli session
+ * PRODUCED, recorded by the daemon with zero agent cooperation.
+ *
+ * Two axes, never conflated:
+ *   - termination — HOW the session stopped (the descriptor's existing
+ *     `status` + `endedReason`), copied verbatim into `outcome.termination`;
+ *   - outcome — WHAT it produced: its last assistant message, the PRs it
+ *     opened, what it cost, and which run / parent it belongs to.
+ *
+ * So a killed or idle-reaped session still shows what it said and did,
+ * instead of a bare "killed".
+ *
+ * Pure by construction (plus one bounded sync tail-read helper for boot
+ * reconcile): no LLM call, no full transcript scan. The registry calls
+ * {@link deriveSessionOutcome} from its single exit funnel (`emitExited`)
+ * and from boot reconcile (`loadHistorySnapshot`).
+ */
+
+interface SessionOutcomeArtifact {
+    type: "pr" | "commit" | "url";
+    /** The artifact's canonical reference — a PR url, a commit sha, a url. */
+    ref: string;
+    title?: string;
+}
+interface SessionOutcomeLink {
+    /** `run` — the workflow run this session was a step of (`ref` = run id,
+     *  `title` = `<workflowId>/<stepId>`); `parent` — the orchestrator session
+     *  that spawned it; `review` — reserved for the review ledger (Level 2). */
+    rel: "run" | "parent" | "review";
+    ref: string;
+    title?: string;
+}
+interface SessionOutcome {
+    /** Level 1 only ever writes `"derived"`; a declared outcome (Level 2) is a
+     *  later addition. */
+    source: "derived";
+    /** `produced` — the session said something or left an artifact;
+     *  `empty` — no assistant text and no artifacts. */
+    status: "produced" | "empty";
+    /** Last assistant message of the session, trimmed to
+     *  {@link OUTCOME_SUMMARY_MAX} chars (the TAIL is kept — the conclusion,
+     *  not the preamble). Absent when the session never said anything. */
+    summary?: string;
+    /** Copy of the descriptor's end state at the moment the outcome was
+     *  recorded — the termination axis, never mixed into `status`. */
+    termination: {
+        status: string;
+        /** Copy of `SessionDescriptor.endedReason` — see {@link SessionEndReason}
+         *  for the full, single-source enum of values (operator kill, cost cap,
+         *  provider limit, …). Absent for a plain natural exit or an ordinary
+         *  turn error this file doesn't tag. A value outside the known enum is
+         *  still valid (a newer/older daemon) — never gate rendering on it being
+         *  a member; see `isKnownSessionEndReason`. */
+        reason?: SessionEndReason;
+        /** The reason this row carried BEFORE an operator's "mark as completed"
+         *  (`kill(id, signal, "operator-completed")` on an already-terminal
+         *  session — the UI's affordance for relabeling a finished-but-not-
+         *  operator-tagged row) overwrote `reason` with `"operator-completed"`.
+         *  Set ONLY by that relabel, so the true original mechanism (a natural
+         *  exit with no reason, `"crashed"`, `"idle-reaped"`, …) is never lost
+         *  under the operator's override. Absent otherwise. */
+        previousReason?: SessionEndReason;
+        exitCode?: number;
+        /** True when the session was killed with a turn in flight. */
+        midTurn?: boolean;
+    };
+    cost?: {
+        usd?: number;
+        tokensIn?: number;
+        tokensOut?: number;
+        durationMs?: number;
+    };
+    artifacts?: SessionOutcomeArtifact[];
+    links?: SessionOutcomeLink[];
+    recordedAt: string;
+}
+/** The compact list projection of an outcome (`session_list` default). */
+interface SessionOutcomeCompact {
+    status: SessionOutcome["status"];
+    summary?: string;
+}
+interface DeriveSessionOutcomeInput {
+    /** The last assistant message the registry observed (raw, untrimmed). */
+    lastAssistantText?: string;
+    now?: Date;
+}
+/**
+ * Build the derived outcome for a session that has just reached a terminal
+ * status. Reads only the descriptor + the caller-supplied last assistant
+ * text; never touches disk.
+ */
+declare function deriveSessionOutcome(desc: SessionDescriptor, input?: DeriveSessionOutcomeInput): SessionOutcome;
+/** The compact projection: status + the first
+ *  {@link OUTCOME_COMPACT_SUMMARY_MAX} chars of the summary. */
+declare function compactOutcome(o: SessionOutcome | undefined): SessionOutcomeCompact | undefined;
+
 /**
  * Minimal shape we need from a driver-agent-cli session — kept as a
  * structural type so the runtime package doesn't take a hard
@@ -4384,6 +6007,12 @@ interface AgentSessionLike {
      *  drivers that don't model held permissions (sandbox proxy, future
      *  transports). */
     respondPermission?(requestId: string, resolution: AcpPermissionResolution): boolean | Promise<boolean>;
+    /** Subscribe to events the agent emits while no turn is in flight — its
+     *  own wake-up when a background task settles, and the task lifecycle
+     *  itself. Mirrors `@agentproto/driver-agent-cli`'s
+     *  `AgentCliRuntimeSession.onOutOfTurnEvent`. Returns an unsubscribe
+     *  function. Absent for drivers that can't produce such events. */
+    onOutOfTurnEvent?(listener: (event: AgentStreamEvent) => void): () => void;
     /**
      * Switch the active model on this LIVE session — mirrors
      * `@agentproto/driver-agent-cli`'s `AgentCliRuntimeSession.setModel`
@@ -4420,6 +6049,15 @@ interface AgentSessionLike {
      * routes to restart.
      */
     readonly availableModes?: readonly SessionMode[];
+    /** Whether the agent accepts steering — mirrors
+     *  `@agentproto/driver-agent-cli`'s `AgentCliRuntimeSession.steeringSupported`
+     *  (ACP `_session/steering`, advertised at initialize). */
+    readonly steeringSupported?: boolean;
+    /** Inject content into the turn in flight — mirrors
+     *  `AgentCliRuntimeSession.steer`: `"steered"` (injected), `"promptRequired"`
+     *  (no host turn in flight — deliver as a normal prompt), `"unsupported"`.
+     *  Never throws. Absent for sessions that can't steer. */
+    steer?(content: unknown): Promise<"steered" | "promptRequired" | "unsupported">;
     close(): Promise<void>;
 }
 /** Result of `SessionsRegistry.setModel` — see that method's doc comment. */
@@ -4586,6 +6224,16 @@ interface AgentStreamEvent {
      *  but no `cost`). */
     tokensIn?: number;
     tokensOut?: number;
+    /** "usage_update" model the usage belongs to, when the adapter reports it
+     *  (claude-agent-acp's `_meta["_claude/model"]`) — see `context-window.ts`. */
+    model?: string;
+    /** "usage_update" `size` is the adapter's own guess, corrected later by a
+     *  cost-bearing frame (claude-agent-acp) — see `context-window.ts`. */
+    sizeInferred?: boolean;
+    /** "usage_update" size as the adapter reported it, recorded only when the
+     *  daemon corrected `size` (an inferred window superseded by the catalog or
+     *  an earlier authoritative frame) — see `context-window.ts`. */
+    reportedSize?: number;
     /** "permission-resolved" outcome for the "agent-prompt" it answers (same
      *  `toolCallId`) — mirrors `session:permission-resolved`'s `decision` so
      *  the durable transcript can tell an answered ask from a still-pending
@@ -4612,6 +6260,24 @@ interface AgentStreamEvent {
             qualifiedName?: string;
         };
     }>;
+    /** "background-task" lifecycle edge — see @agentproto/acp's `StreamEvent`'s
+     *  `background-task` kind. */
+    phase?: "started" | "updated" | "settled";
+    /** "background-task" task snapshot — see @agentproto/acp's
+     *  `BackgroundTaskInfo`. Only `taskId` is guaranteed. */
+    task?: {
+        taskId: string;
+        taskKind?: string;
+        description?: string;
+        outputFile?: string;
+        status?: SessionBackgroundTask["status"];
+        summary?: string;
+        toolCallId?: string;
+    };
+    /** "usage_update" origin of the cycle it closes (claude-agent-acp's
+     *  `_meta["_claude/origin"].kind`, e.g. `"task-notification"` for an
+     *  autonomous wake) — see @agentproto/acp's `StreamEvent`. */
+    origin?: string;
 }
 /**
  * Env vars the registry injects into every process it spawns on a session's
@@ -4732,6 +6398,13 @@ interface QueuedPrompt {
      *  daemon restart. Absent for legacy queued items — `promptOriginLabel`
      *  falls back to `source`, then `"user"`. */
     origin?: string;
+    /** Set when this item is a typed inter-session message (`message_parent`,
+     *  …) rather than a prompt: the daemon-attested envelope. `message` then
+     *  only carries `envelope.text` (for `previewPrompt`); the turn is built
+     *  from the envelope — rendered as an `<agentproto-message>` tag, recorded
+     *  as a `session-message` transcript record, and coalesced with any
+     *  envelope items queued right behind it (never with a plain prompt). */
+    envelope?: SessionMessage;
 }
 /** What `enqueuePrompt` resolved to — lets a caller (e.g. MCP `agent_prompt`)
  *  tell the user whether the prompt was delivered/started now or PARKED behind
@@ -4743,6 +6416,22 @@ interface QueuedPrompt {
 interface EnqueuePromptResult {
     queued: boolean;
 }
+/** What `sendMessage` did with a message — truthful, per AIP-46. */
+interface SendMessageResult {
+    messageId: string;
+    /** Set when the message already reached the recipient's context (a
+     *  waiter, a dispatched turn, an interrupt) or was parked as `fyi`
+     *  (`via: "inbox"`); `null` while it's queued behind a busy turn. */
+    delivered: {
+        via: MessageDeliveryVia;
+    } | null;
+    queued: boolean;
+    urgencyApplied: MessageUrgency;
+}
+interface WaitForMessagesResult {
+    messages: SessionMessage[];
+    timedOut: boolean;
+}
 /** One entry in the after-the-fact queue listing (`listQueuedPrompts` /
  *  `session_queue_list` / `GET /sessions/:id/queue`). `position` is the
  *  array index (0 = next to dispatch). */
@@ -4756,6 +6445,17 @@ interface QueuedPromptView {
     queuedAt: string;
     position: number;
 }
+/** Provenance stamped onto a `session_continue_fresh` target by
+ *  {@link SessionDescriptor.handoff} — which harness the checkpoint moved
+ *  from/to and when. `fromHarness === toHarness` for a same-harness
+ *  continuation; they differ for a genuine cross-harness handoff
+ *  (claude-code -> opencode, etc). */
+interface SessionHandoff {
+    fromHarness: string;
+    toHarness: string;
+    /** ISO 8601 timestamp the handoff spawn completed. */
+    at: string;
+}
 interface SessionDescriptor {
     id: string;
     kind: SessionKind;
@@ -4778,30 +6478,36 @@ interface SessionDescriptor {
     startedAt: string;
     endedAt?: string;
     exitCode?: number;
-    /** Set alongside `status: "killed"` when the session ended NOT because an
-     *  operator targeted it (`kill()`) but because of an AUTOMATIC teardown:
-     *   - `"daemon-restart"` — the daemon process it lived in went away out from
-     *     under it: a hard crash discovered at next boot
-     *     (`loadHistorySnapshot`'s wasAlive reclassification), or a graceful
-     *     shutdown/restart that force-kills whatever's still busy
-     *     (`shutdownImpl`).
-     *   - `"idle-reaped"` — the idle-session reaper (`reapIdle`, PR-6) retired a
-     *     long-idle agent-cli row to free its adapter process. Deliberately kept
-     *     lazy-resumable (adapterSessionId/cwd intact) so a later prompt revives
-     *     it, but NEVER eager-resumed on boot — the eager pass (#638) gates on
-     *     `endedReason === "daemon-restart"`, so an `"idle-reaped"` row is
-     *     naturally excluded and a resume-storm of dead work is avoided.
-     *   - `"crashed"` — the crash-detect sweep (`markCrashed`) found the
-     *     adapter's OS process gone between turns, with no exit event ever
-     *     emitted for it (agent-cli holds its child alive across turns, so a
-     *     death outside a turn is otherwise silent until the next RPC throws).
-     *     `status` is set to `"error"` (not `"killed"`) since nothing targeted
-     *     it; see `lastError`/`crashedAt` for detail.
-     *  Absent for every other terminal path (operator kill, natural exit, turn
-     *  error) — the session's own fault, or at least not an automatic sweep's.
-     *  Lets the UI show "crashed with the daemon" / "reaped while idle" instead
-     *  of a bare "killed" that reads as deliberate. */
-    endedReason?: "daemon-restart" | "idle-reaped" | "crashed";
+    /** WHY the session ended — every stable value + its meaning is declared
+     *  once, in {@link SessionEndReason} (`session-end-reason.ts`), so a UI can
+     *  render a label for each without chasing the call site that set it.
+     *  Three families:
+     *   - automatic daemon-lifecycle teardown (unchanged, pre-existing):
+     *     `"daemon-restart"` (the daemon process it lived in went away out from
+     *     under it — a hard crash discovered at next boot, or a graceful
+     *     shutdown/restart that force-kills whatever's still busy),
+     *     `"idle-reaped"` (the idle-session reaper retired a long-idle row —
+     *     deliberately kept lazy-resumable but NEVER eager-resumed on boot,
+     *     since the eager pass gates on `endedReason === "daemon-restart"`),
+     *     `"crashed"` (the crash-detect sweep found the adapter's OS process
+     *     gone between turns with no exit event ever emitted for it — `status`
+     *     is `"error"`, not `"killed"`, since nothing targeted it);
+     *   - operator-issued kill: `"operator-completed"` / `"operator-stopped"`,
+     *     set ONLY by an explicit `POST /sessions/:id/kill` or the `agent_kill`
+     *     MCP tool (never by an internal automatic teardown), so it reads as
+     *     deliberate rather than random;
+     *   - other internal/automatic reasons: `"cost-cap-exceeded"` (the
+     *     turn-granular `maxCostUsd` cap tripped), `"policy-cleanup"` (a
+     *     supervisor gate tore down its own ephemeral judge session),
+     *     `"parent-exited"` (an orchestrator's dying subtree reap),
+     *     `"provider-limit"` (a driver-reported subscription/usage-cap error,
+     *     e.g. Claude Code's "hit your session limit"), `"forgotten"` (a live
+     *     session killed as part of an operator `DELETE`).
+     *  Absent for every terminal path this file doesn't tag (a plain natural
+     *  exit, an ordinary turn error) — the session's own fault, or at least
+     *  not something worth a special label. A string outside this list is
+     *  still valid (a newer/older daemon) — see `isKnownSessionEndReason`. */
+    endedReason?: SessionEndReason;
     /** Whether a turn was actually in flight the INSTANT `status` flipped to
      *  "killed" — captured before anything else runs, because `busy` itself
      *  cannot be trusted after the fact: `runAgentTurn`'s `finally` is what
@@ -4819,6 +6525,16 @@ interface SessionDescriptor {
      *  `kill()`, `shutdownImpl`'s force-kill, and `loadHistorySnapshot`'s
      *  wasAlive reclassification; absent for every other terminal path. */
     killedMidTurn?: boolean;
+    /** What this session PRODUCED — the derived outcome (Level 1) the daemon
+     *  records once it reaches a terminal status, alongside (never instead of)
+     *  the termination fields above: last assistant message, opened PRs, cost,
+     *  run/parent links. agent-cli only. Recorded from the one exit funnel
+     *  (`emitExited`) and from boot reconcile for rows that died with the
+     *  daemon; first write wins unless a later one is for a new death or is
+     *  richer (see `shouldReplaceOutcome`). Dropped when an in-place resume
+     *  revives the row. Persisted, so it survives restarts and archiving. See
+     *  `session-outcome.ts`. */
+    outcome?: SessionOutcome;
     /** Last time anything was written to stdout/stderr. Lets the UI
      *  spot stuck sessions ("running for 2h, last output 12min ago"). */
     lastOutputAt?: string;
@@ -4926,10 +6642,23 @@ interface SessionDescriptor {
      *  session sits `busy:false`, `awaitingInput:false`, background tasks
      *  pending — a silent dead end. Detection + signal ONLY (same doctrine
      *  as `stalledSinceMs`): nothing here re-prompts or wakes the session.
+     *  Not stamped for an agent that reports its background-task lifecycle
+     *  (see `backgroundTasks`) — that one is tracked and woken for real.
      *  Cleared (deleted, never a stale value) on the next turn start and on
      *  session exit. Emits `session:bg-tasks-parked` /
      *  `session:bg-tasks-cleared`. */
     pendingBgTasks?: number;
+    /** The agent's background tasks that are still running (a backgrounded
+     *  Bash command, a monitor, ...), as the agent itself reports them — over
+     *  ACP, the AIR `asyncTasks` lifecycle. Unlike `pendingBgTasks` (a
+     *  turn-end heuristic) this is the real set: a task is added when it
+     *  starts and removed when it settles, so an idle session with a
+     *  non-empty list is "waiting on N background tasks", not parked. When
+     *  one settles while the session is idle the registry makes sure the
+     *  agent is woken (see `SessionsRegistryOptions.backgroundTaskWake`).
+     *  Absent when none are running; dropped on exit and on respawn (a new
+     *  process owns none of the old one's tasks). */
+    backgroundTasks?: SessionBackgroundTask[];
     /** ISO 8601 timestamp of the last turn that ended because the ADAPTER
      *  ITSELF reported a failure — `runAgentTurn` observed a `turn-end` event
      *  with `reason:"error"` (session-event-bus.ts's `SessionTurnEndEvent`,
@@ -4938,16 +6667,32 @@ interface SessionDescriptor {
      *  `status` to `"error"` directly (a genuinely terminal row the existing
      *  crash/error handling already catches). This is the twin gap for a
      *  turn that fails IN-BAND while the process stays alive: `status` stays
-     *  `"running"`, `lastError` stays unset (reserved for `markCrashed`), and
-     *  nothing else distinguishes the session from one that simply finished
-     *  a clean turn and is idle. Folded into the same "stalled" activity/UI
-     *  treatment a mid-turn stall gets (see sessionsTree.logic.ts's
-     *  `activityFor`) rather than a new state, on the theory that both mean
-     *  "the last thing this session did needs a look, not a re-prompt on
-     *  faith". Stamped at turn-end when `turnEndReason === "error"`; cleared
-     *  the moment a LATER turn completes without one (same reset shape as
+     *  `"running"`, `lastError` stays unset (still reserved for `markCrashed`
+     *  — see `lastTurnErrorMessage` below for the message text this field's
+     *  own turn carries), and nothing else distinguishes the session from
+     *  one that simply finished a clean turn and is idle. Folded into the
+     *  same "stalled" activity/UI treatment a mid-turn stall gets (see
+     *  sessionsTree.logic.ts's `activityFor`) rather than a new state, on
+     *  the theory that both mean "the last thing this session did needs a
+     *  look, not a re-prompt on faith". Stamped at turn-end when
+     *  `turnEndReason === "error"` — including the case where the adapter's
+     *  stream generator simply returned after emitting an in-band `error`
+     *  event with no explicit turn-end and no thrown exception, which
+     *  `runAgentTurn`'s P5 synthetic-reason fallback now classifies as
+     *  `"error"` rather than defaulting to `"exited"`. Cleared the moment a
+     *  LATER turn completes without one (same reset shape as
      *  `resumeAttempts`/`restartAttempts`). Detection + signal only. */
     lastTurnErroredAt?: string;
+    /** The captured error text for the turn `lastTurnErroredAt` timestamps —
+     *  `evt.error.message` off the in-band stream `error` event observed
+     *  during that turn (see `runAgentTurn`'s `turnErrorMessage`). Distinct
+     *  from `lastError` (reserved for `markCrashed`) and from
+     *  `rt.lastErrorMessage` (an internal, cross-turn, never-cleared runtime
+     *  field — this one is the public, turn-scoped descriptor projection of
+     *  it). Absent when the adapter reported `reason:"error"` on its own
+     *  turn-end without a preceding `error`-kind stream event. Stamped and
+     *  cleared together with `lastTurnErroredAt`. */
+    lastTurnErrorMessage?: string;
     /** True when the LAST completed turn produced zero assistant output and
      *  zero tool calls (mirrors `SessionTurnEndEvent.empty` — see that
      *  field's doc). Persisted so `monitorSessionWait`'s synchronous
@@ -4977,6 +6722,29 @@ interface SessionDescriptor {
      *  the underlying `killedMidTurn`/`endedReason`). The in-place resume path
      *  never auto-retries the interrupted prompt. */
     interrupted?: boolean;
+    /** The `SessionsRegistry.bootId` of the FIRST daemon boot that found this
+     *  row interrupted — i.e. which restart cut its turn off. Stamped by the
+     *  boot reload (`loadHistorySnapshot`) on an interrupted row that doesn't
+     *  carry one yet; dropped whenever the row is interrupted AGAIN (so the next
+     *  boot restamps it) and on the next successful turn-end (with the markers it
+     *  qualifies). `interruptedAtBoot === registry.bootId` is how the
+     *  continue-interrupted verb and boot pass pick "interrupted by the LAST
+     *  restart" apart from a stale interruption nobody picked back up. PERSISTED
+     *  (unlike the derived `interrupted`) — the boot that stamped it may not be
+     *  the one reading it. */
+    interruptedAtBoot?: string;
+    /** How many automatic continue prompts the daemon has sent this row
+     *  (`daemon.continueInterruptedOnBoot`) since its last successful turn-end.
+     *  Incremented BEFORE the prompt is sent, so a continue turn that itself
+     *  gets cut off by another restart still counts; reset on the next
+     *  successful turn-end. The boot pass stops at
+     *  `MAX_AUTO_CONTINUE_ATTEMPTS` — the no-loop bound for a turn that keeps
+     *  taking the daemon down with it. PERSISTED; absent until the first one. */
+    autoContinueAttempts?: number;
+    /** `bootId` of the boot whose pass last auto-continued this row — the
+     *  at-most-one-auto-continue-per-restart guard. Reset with
+     *  `autoContinueAttempts`. */
+    lastAutoContinueBoot?: string;
     /** How many in-place resume attempts have FAILED in a row for this session
      *  (§5 cap/backoff). Incremented on every failed `maybeResumeAgent` attempt —
      *  the resume throws, the adapter rejects the id, or the spawn returns null —
@@ -5083,6 +6851,9 @@ interface SessionDescriptor {
      *  field is. Absent (not `false`) for every descriptor from before this
      *  field existed — treated the same as `false` everywhere it's read. */
     archived?: boolean;
+    /** ISO-8601 instant `archiveSession` set `archived: true`; cleared by
+     *  `unarchiveSession`. Absent on rows archived before this field existed. */
+    archivedAt?: string;
     /** When `true`, the idle-reaper (`isReapable`, `idle-reaper.ts`) never
      *  retires this session regardless of how long it's sat idle. For a
      *  supervisor that legitimately parks — waiting on a child, waiting on a
@@ -5137,6 +6908,12 @@ interface SessionDescriptor {
      *  `worktreePath` without an id identifies a PATH, which a later worktree
      *  may reuse; the pair identifies one specific worktree. */
     worktreeId?: string;
+    /** Absolute path of the PRIMARY checkout `worktreePath` was cut from (the
+     *  repo root a `worktree_status` query targets), read at spawn from the
+     *  worktree admin dir's `commondir` file (`resolveWorktreeIdentity`).
+     *  Absent whenever `worktreePath` is, when `commondir` was unreadable, and
+     *  for every session persisted before this field existed. */
+    mainRepoPath?: string;
     /** `true` only when `worktreePath` was provisioned by the `worktrees.isolation`
      *  policy WITHOUT an explicit `worktree` request from the caller (see
      *  `decideWorktreeIsolation`'s `WorktreeDecision.provision.implicit` in
@@ -5326,15 +7103,34 @@ interface SessionDescriptor {
     /** Cumulative input / output token counts (same source + cadence as costUsd). */
     tokensIn?: number;
     tokensOut?: number;
+    /** Cumulative prompt-cache read / cache-creation / reasoning tokens, from
+     *  the adapter's usage reader (claude-code transcript, hermes state.db,
+     *  opencode.db). Absent when the adapter doesn't expose them — never
+     *  zero-filled. See `UsageDetail` in usage.ts. */
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+    /** Tool calls the daemon observed across completed turns (cumulative).
+     *  Stamped at the first turn end, so absent = no turn has finished yet. */
+    toolCalls?: number;
+    /** Wall time spent inside turns, cumulative ms. Same cadence as
+     *  `toolCalls`. */
+    durationMs?: number;
     /** Context-window size + tokens-in-context from the latest `usage_update`
      *  event (ACP adapters that report a context window). Refreshed live as
      *  usage_update events arrive, not just at turn-end. */
     contextSize?: number;
     contextUsed?: number;
+    /** Where `contextSize` came from — `"adapter"` (a cost-bearing, authoritative
+     *  usage_update; sticky), `"catalog"` (model-catalog window for the model),
+     *  or `"reported"` (the adapter's own, possibly inferred, frame size). See
+     *  `context-window.ts` for the precedence. */
+    contextSizeSource?: ContextSizeSource;
     /** Where `costUsd` came from — `"adapter"` (adapter's own reader or a
      *  usage_update cost block), `"computed"` (tokens × in-repo catalog price),
      *  `"no-pricing"` (tokens present but the model isn't in the catalog — cost
-     *  deliberately left undefined), or `"none"`. Stamped at each turn-end. */
+     *  deliberately left undefined), or `"none"`. Stamped live on each
+     *  cost-bearing usage_update / reader read, and re-derived at turn-end. */
     usageSource?: UsageSource;
     /** Latest known `available_commands_update` payload (see @agentproto/acp's
      *  `StreamEvent`'s `available-commands` kind) — the slash-commands/skills
@@ -5456,7 +7252,7 @@ interface SessionDescriptor {
      *  next assistant `text-delta` (the model has the floor, so nothing is
      *  pending), at turn start, and in the turn's finally. A claim about the
      *  present tense — anything that disproves it must clear it. */
-    blockedOn?: "subagent" | "command";
+    blockedOn?: "subagent" | "command" | "inbox";
     /** toolCallId of the tool-call that set `blockedOn`. A tool-result only
      *  clears `blockedOn` when its toolCallId matches — so a nested or
      *  interleaved tool finishing first can't clear the flag early. */
@@ -5472,9 +7268,9 @@ interface SessionDescriptor {
      *  (`markCrashed` → `session:exited` with `status:"error"`/
      *  `reason:"crashed"`), the supervisor-notify subscriber
      *  (`supervisor-notify.ts`) delivers a `[child-crashed]` notice to its
-     *  `parentSessionId`, if any — directly (enqueued prompt) when the parent
-     *  is alive and idle, or stamped onto `pendingChildCrashNotices` and
-     *  flushed at the parent's next turn when it's busy. The free external
+     *  `parentSessionId`, if any — dispatched now when the parent is alive
+     *  and idle, or parked in its `promptQueue` and drained as its own turn
+     *  when the parent's current turn ends. The free external
      *  webhook path (`notifyUrl`) already fires regardless of this flag; this
      *  only gates the additional IN-BAND signal into the parent's own
      *  session, which a caller that isn't a delegating supervisor doesn't
@@ -5483,14 +7279,42 @@ interface SessionDescriptor {
     notifyParentOnCrash?: boolean;
     /** True when the session was spawned in permission-hold mode. */
     permissionHold?: boolean;
-    /** Queued `[child-crashed] …` notices from crashed children, stamped by
-     *  the supervisor-notify subscriber when THIS session was busy at the
-     *  time a child it should be told about crashed (mid-turn is never
-     *  interrupted for this — see `notifyParentOnCrash`). Flushed and cleared
-     *  by prepending the joined notices onto the next dispatched turn's
-     *  message (`runAgentTurn`) — so delivery survives a busy parent without
-     *  ever cancelling its in-flight work. Absent when nothing is queued. */
+    /** Effective OS-level confinement of the adapter's own process
+     *  (`agent_start.commandSandbox`, else the workspace's
+     *  `.agentproto/command-sandbox.json` `adapterSpawn.mode`), resolved at
+     *  spawn with the same precedence the driver applies
+     *  (`wrapAgentCliSpawn`). Absent when neither engaged the axis (the spawn
+     *  ran unconfined without anyone choosing a mode), for a `sandbox` spawn
+     *  (confinement is the box's business), and for sessions persisted before
+     *  this field existed. Set at spawn time, immutable thereafter. */
+    commandSandbox?: "off" | "workspace" | "strict";
+    /** @deprecated Retired — child reports and `[child-crashed]` notices for a
+     *  busy session are now queued as their own `promptQueue` items
+     *  (`source:"child:<id>"`) instead of being string-prepended onto the next
+     *  prompt. Only read once, at boot, by `migratePendingChildNotices`, which
+     *  moves any notices a pre-upgrade daemon persisted into `promptQueue` and
+     *  deletes this field. Never written. */
     pendingChildCrashNotices?: string[];
+    /** True once this session has been taught the `<agentproto-message>`
+     *  invariant (`MESSAGE_PREAMBLE`) — sent as a `system-prompt` slice ahead
+     *  of the FIRST message turn it receives, never again. */
+    messagePreambleSent?: boolean;
+    /** Durable, bounded inbox of typed messages NOT yet consumed (AIP-46
+     *  §Session messages): every accepted message lands here until it's
+     *  delivered into a turn (auto-acked), returned by `inbox_wait` with
+     *  `ack`, or acked via `inbox_ack`. `fyi` messages only ever live here
+     *  (surfaced as a digest). Capped at `INBOX_CAP`, oldest dropped first
+     *  (`[inbox] dropped`). Full history lives in the transcript, not here.
+     *  New array on every mutation, like `promptQueue`. */
+    inbox?: SessionMessage[];
+    /** What the live agent session can do, read from its driver at attach
+     *  time (spawn / resume) — shown in `session_list` so a sender can predict
+     *  a message's delivery tier. `steering`: the agent accepts ACP steering
+     *  (`_session/steering`) — a `steer` message can be injected into its
+     *  running turn instead of waiting for it to end. */
+    capabilities?: {
+        steering: boolean;
+    };
     /** FIFO of prompts that arrived while this session was mid-turn and
      *  asked to be QUEUED rather than rejected (`enqueuePrompt`'s
      *  `opts.queue` arm — see its doc comment). Index 0 is next to
@@ -5505,8 +7329,7 @@ interface SessionDescriptor {
      *  `sessionDescriptorsEqual` diff is a shallow `!==` per field, so an
      *  in-place `.shift()` here would silently stop propagating queue
      *  changes to the transcript panel. `[]` (not absent) once anything
-     *  has ever been queued, matching `pendingChildCrashNotices`'s
-     *  convention above. */
+     *  has ever been queued. */
     promptQueue?: QueuedPrompt[];
     /** Best-effort context-handoff digest (Fix D), stashed on a descriptor
      *  whose resume degraded to a BLANK spawn — the adapter's own
@@ -5514,8 +7337,7 @@ interface SessionDescriptor {
      *  false` — built by `buildResumeContextDigest` from the daemon's own
      *  `events.jsonl` transcript, which survives both cases. Flushed and
      *  cleared by prepending it onto the first dispatched turn's message
-     *  (`runAgentTurn`), exactly once, same shape as
-     *  `pendingChildCrashNotices` above. Gated strictly on the blank-fallback
+     *  (`runAgentTurn`), exactly once. Gated strictly on the blank-fallback
      *  flags at the two sites that set it (`session-restart-core.ts`,
      *  `maybeResumeAgent` here) — never set for a resume that actually
      *  restored context, so a real continuation is never double-fed its own
@@ -5547,6 +7369,12 @@ interface SessionDescriptor {
     /** When this session was continued fresh into a new session, the target
      *  session id. */
     continuedTo?: string;
+    /** Set alongside `continuedFrom` on the NEW session — the harness the
+     *  checkpoint moved from/to and when. Present on every `continue_fresh`
+     *  spawn, not just a cross-harness one, so a same-harness continuation
+     *  and a genuine handoff are both traceable the same way. See
+     *  {@link SessionHandoff}. */
+    handoff?: SessionHandoff;
     /** Source label — the channel/harness this session was spawned from
      *  ("codex", "cowork", "vscode", "cron", …). Descriptor-only; groups the
      *  session under a source node in the tree. */
@@ -5678,6 +7506,9 @@ interface SessionSummary {
     endedAt?: string;
     exitCode?: number;
     killedMidTurn?: boolean;
+    /** Compact derived outcome (status + 120-char summary preview) — see
+     *  `SessionDescriptor.outcome`; the full record is on GET /sessions/:id. */
+    outcome?: SessionOutcomeCompact;
     lastOutputAt?: string;
     lastActivityAt?: string;
     currentPhase?: SessionCurrentPhase;
@@ -5697,6 +7528,9 @@ interface SessionSummary {
     renamedByUser?: boolean;
     activitySummary?: SessionActivitySummary;
     archived?: boolean;
+    /** ISO-8601 instant `archiveSession` set `archived: true`; cleared by
+     *  `unarchiveSession`. Absent on rows archived before this field existed. */
+    archivedAt?: string;
     keepAlive?: boolean;
     pinned?: boolean;
     pty?: boolean;
@@ -5705,6 +7539,7 @@ interface SessionSummary {
     cwd?: string;
     worktreePath?: string;
     worktreeId?: string;
+    mainRepoPath?: string;
     /** Resolved AGENTS.md path — see `SessionDescriptor.agentsMd`. */
     agentsMd?: string;
     /** Injection mode — see `SessionDescriptor.agentsMdMode`. */
@@ -5719,18 +7554,21 @@ interface SessionSummary {
     tokensOut?: number;
     contextSize?: number;
     contextUsed?: number;
+    contextSizeSource?: ContextSizeSource;
     usageSource?: UsageSource;
     awaitingInput?: boolean;
     awaitingQuestion?: SessionAwaitingQuestion;
     awaitingPermission?: boolean;
     turnsCompleted?: number;
     busy?: boolean;
-    blockedOn?: "subagent" | "command";
+    blockedOn?: "subagent" | "command" | "inbox";
     stalledSinceMs?: number;
     /** Parked-with-background-tasks marker — see
      *  `SessionDescriptor.pendingBgTasks`. Stamped at turn-end, cleared on the
      *  next turn start / exit. */
     pendingBgTasks?: number;
+    /** Running background tasks — see `SessionDescriptor.backgroundTasks`. */
+    backgroundTasks?: SessionBackgroundTask[];
     /** Adapter-reported turn-error marker — see
      *  `SessionDescriptor.lastTurnErroredAt`. Stamped at turn-end, cleared on
      *  the next turn that completes without one. */
@@ -5762,6 +7600,8 @@ interface SessionSummary {
     sandboxTeardown?: "kill" | "pause";
     sandboxPorts?: Record<number, string>;
     appServe?: SessionAppServeInfo;
+    /** Effective adapter confinement — see `SessionDescriptor.commandSandbox`. */
+    commandSandbox?: "off" | "workspace" | "strict";
     /** Read-time projection of the box's ledger liveness verdict — see
      *  `SessionDescriptor.sandboxAlive`. */
     sandboxAlive?: boolean;
@@ -6096,6 +7936,13 @@ interface SessionsRegistry {
         queue?: boolean;
         force?: boolean;
         queueId?: string;
+        /** A typed inter-session message (see `QueuedPrompt.envelope`). When
+         *  set, the turn is built from the envelope and `message` is ignored:
+         *  rendered as an `<agentproto-message>` tag, recorded as
+         *  `session-message` (never `user-prompt`), never matched as a
+         *  structured-question answer, and noted in the SENDER's transcript
+         *  as `session-message-sent`. */
+        envelope?: SessionMessage;
     }): Promise<EnqueuePromptResult>;
     /** Cancel one not-yet-dispatched item in `SessionDescriptor.promptQueue`
      *  by id — the composer's per-item "remove" action. Idempotent: an
@@ -6106,6 +7953,50 @@ interface SessionsRegistry {
     removeQueuedPrompt(id: string, queueId: string): {
         removed: boolean;
     };
+    /** Deliver a daemon-attested typed message (`msg.to` is the recipient;
+     *  `from` must already be computed from the verified caller), routed by
+     *  `msg.urgency` (AIP-46 §Delivery tiers):
+     *   - a matching pending `waitForMessages` wins over every tier (waiter
+     *     first — returned as that call's result, never also injected);
+     *   - `fyi` — durable inbox only, no wake;
+     *   - idle recipient — any other tier starts its own turn now;
+     *   - busy + `next-turn` — queued behind the current turn;
+     *   - busy + `steer` — injected into the running turn when the daemon's
+     *     OWN prompt is in flight (never an autonomous cycle), the agent can
+     *     steer, and the per-recipient rate limit allows; else `next-turn`;
+     *   - busy + `interrupt` — cancels the turn and delivers — only when
+     *     `allowInterrupt` (the caller's grant); otherwise downgraded to
+     *     `steer`.
+     *  `urgencyApplied` reports the tier actually used. Throws when the
+     *  recipient is missing or not alive. */
+    sendMessage(msg: SessionMessage, opts?: {
+        source?: string;
+        origin?: string;
+        allowInterrupt?: boolean;
+    }): Promise<SendMessageResult>;
+    /** Block until a message matching `filter` is in `id`'s inbox (returns at
+     *  once when one already is), or `timeoutMs` elapses. Matched messages are
+     *  consumed: stamped `delivered.via:"wait"`, removed from the prompt queue
+     *  (so they're never also injected as a turn), and — when `ack` (default)
+     *  — removed from the inbox. Sets `blockedOn:"inbox"` while parked. */
+    waitForMessages(id: string, filter: MessageFilter, opts: {
+        timeoutMs: number;
+        ack?: boolean;
+        signal?: AbortSignal;
+    }): Promise<WaitForMessagesResult>;
+    /** Read `id`'s inbox (un-consumed messages), newest last. */
+    listInbox(id: string, filter?: MessageFilter & {
+        limit?: number;
+    }): SessionMessage[] | null;
+    /** Find a message `id` RECEIVED (still in its inbox, or already consumed
+     *  and only in its transcript) — how `message_reply` routes to the
+     *  original sender. `undefined` when `id` never received `messageId`. */
+    findReceivedMessage(id: string, messageId: string): SessionMessage | undefined;
+    /** Ack (remove) messages from `id`'s inbox — and from its prompt queue, so
+     *  an acked-but-still-queued message is never delivered afterwards. */
+    ackInbox(id: string, ids: readonly string[] | "all"): {
+        acked: string[];
+    };
     /** Snapshot a session's prompt queue for inspection — the after-the-fact
      *  view of what's sitting in `SessionDescriptor.promptQueue` right now.
      *  Runs the shared preview + origin-label derivation so every consumer
@@ -6134,7 +8025,8 @@ interface SessionsRegistry {
      *
      *  Implemented as promote-to-front + interrupt: the cancelled turn's
      *  own `dispatchQueuedPrompt` (in its finally) then drains the promoted
-     *  item into a fresh turn. On an idle session (nothing to interrupt) the
+     *  item — and only that item; the rest wait for a natural turn-end —
+     *  into a fresh turn. On an idle session (nothing to interrupt) the
      *  promoted item is dispatched directly. Returns:
      *    `{ delivered: false, reason }` — `"no-session"` / `"not-in-queue"`;
      *    `{ delivered: true, interrupted: boolean }` otherwise. */
@@ -6143,6 +8035,21 @@ interface SessionsRegistry {
         reason?: string;
         interrupted?: boolean;
     }>;
+    /** A currently-RUNNING background task's info plus a tail of its output
+     *  file, for the UI's "click a live background-task row to peek at its
+     *  output" affordance. Scoped to `SessionDescriptor.backgroundTasks` on
+     *  purpose — a settled task is dropped from that list moments after it
+     *  reports terminal status (see `noteBackgroundTask`), so this never
+     *  becomes an arbitrary-file-read: the caller supplies a `taskId`, never a
+     *  path, and only a path the agent itself already reported for a task
+     *  still tracked as running is ever read. Returns `null` when the session
+     *  or the task is unknown (the caller surfaces 404); `tail` is `null` when
+     *  the task has no `outputFile` or the file can't be read (not yet
+     *  created, already rotated away, ...). */
+    readBackgroundTaskTail(id: string, taskId: string): {
+        task: SessionBackgroundTask;
+        tail: string | null;
+    } | null;
     /** Eagerly resume ONE dead-but-resumable agent-cli session IN PLACE,
      *  WITHOUT a prompt — the boot-time counterpart to the lazy resume that
      *  `sendPrompt`/`enqueuePrompt` trigger on the first prompt after a restart
@@ -6165,6 +8072,17 @@ interface SessionsRegistry {
      *  touching the adapter, so the bounded boot pass can call it per row and
      *  tally the results. */
     resumeOnBoot(id: string): Promise<EagerResumeOutcome>;
+    /** Opaque id unique to this registry instance — one per daemon boot.
+     *  Stamped as `interruptedAtBoot` on rows the boot reload finds interrupted,
+     *  so `interruptedAtBoot === bootId` means "interrupted by the restart that
+     *  preceded THIS boot" (continue-interrupted). */
+    readonly bootId: string;
+    /** Book one automatic continue prompt against `id` (increment
+     *  `autoContinueAttempts`, stamp `lastAutoContinueBoot = bootId`) and
+     *  persist. Called by the continue-on-boot pass BEFORE it sends, so the
+     *  no-loop bound holds even when the continue turn is itself cut off by the
+     *  next restart. No-op for an unknown id. */
+    recordAutoContinue(id: string): void;
     /** Cancel the in-flight turn on a live agent-cli session and leave the
      *  session itself alive and idle — the bare "interrupt, no next prompt"
      *  primitive `sendPrompt`/`enqueuePrompt`'s `opts.interrupt` arm lacks
@@ -6390,6 +8308,15 @@ interface SessionsRegistry {
      *  Initial backfill: synchronously invokes `onLine` once for each
      *  line currently in the ring buffer so attaches show context. */
     attach(id: string, onLine: (line: string, stream: "stdout" | "stderr") => void): (() => void) | null;
+    /** Append a `kind: "mcp_app_tool_call"` record (an MCP App iframe's
+     *  `tools/call`, proxied by `mcp_app_tool_call`) to the session's
+     *  events.jsonl through the same seq-numbered writer the session's own
+     *  events use. No-op-safe for an unknown id (the writer creates the dir). */
+    recordMcpAppToolCall(sessionId: string, record: McpAppToolCallRecord): void;
+    /** Tool name the transcript recorded for `toolCallId` (the latest
+     *  non-empty `toolName` across its `tool-call` records), or undefined
+     *  when the id isn't in the session's events.jsonl. */
+    findToolCallName(sessionId: string, toolCallId: string): Promise<string | undefined>;
     /** Subscribe to a session's structured events.jsonl records as they're
      *  written — the live-push half of `GET /sessions/:id/events/stream`'s
      *  replay-then-subscribe handoff. Thin passthrough to the transcript
@@ -6433,7 +8360,26 @@ interface SessionsRegistry {
      *  bytes at the end; `lastBytes` caps the returned size from the
      *  tail. Returns null when the session is missing or not a PTY. */
     readTerminalOutput(id: string, lastBytes?: number): Buffer | null;
-    kill(id: string, signal?: NodeJS.Signals): boolean;
+    /** SIGTERM the underlying child + close the agent protocol session.
+     *  `reason`, when given, is stamped onto `SessionDescriptor.endedReason`
+     *  (see {@link SessionEndReason}) — pass it from every call site that
+     *  knows WHY it's killing this session (an operator's explicit stop, a
+     *  supervisor tearing down its own judge session, …) rather than leaving
+     *  the row's cause of death unlabeled. Omitted preserves today's
+     *  behaviour: no `endedReason` is stamped by this call (the row may
+     *  already carry one from elsewhere, e.g. a prior `reapIdle`/`markCrashed`
+     *  — moot in practice since both already refuse a non-"running" row before
+     *  `kill()` would ever run on it).
+     *
+     *  A row that's ALREADY terminal (exited/killed/error) normally makes this
+     *  a no-op refusal (`false`) — EXCEPT `reason: "operator-completed"`,
+     *  which is instead treated as "mark as completed": the persisted
+     *  outcome's `termination.reason` is idempotently relabeled to
+     *  `"operator-completed"` (the true original mechanism preserved in
+     *  `termination.previousReason`) and this returns `true`. Every other
+     *  reason (including `"operator-stopped"` or none) on a terminal row
+     *  stays the plain no-op. */
+    kill(id: string, signal?: NodeJS.Signals, reason?: SessionEndReason): boolean;
     /** Retire a long-idle agent-cli session to free its adapter process — the
      *  primitive the idle-session reaper (`runIdleReapPass`, PR-6) drives on a
      *  periodic sweep. Terminates the underlying adapter/child the SAME graceful
@@ -6541,17 +8487,6 @@ interface SessionsRegistry {
      *  window keeps aging out naturally rather than being wiped by the
      *  give-up itself. Returns false (no-op) for an unknown id. */
     giveUpRestart(id: string, message: string): boolean;
-    /** Queue a `[child-crashed] …` notice on a BUSY parent's descriptor
-     *  (`SessionDescriptor.pendingChildCrashNotices`) for delivery at its next
-     *  turn (`runAgentTurn`'s flush) — the never-interrupt path
-     *  `supervisor-notify.ts` takes when the parent can't be prompted
-     *  directly right now (it's mid-turn). Idempotent: the exact same notice
-     *  string is never queued twice, so a duplicate event for the same crash
-     *  can't double-deliver. No-op (returns false) on an unknown id, a
-     *  non-agent-cli row, or a row that isn't alive (`running`/`starting`) —
-     *  nothing to flush a notice INTO. Returns true iff the notice was newly
-     *  queued. */
-    stampPendingChildCrashNotice(id: string, notice: string): boolean;
     /** List permission requests currently parked in the pending-permissions
      *  inbox across all permission-hold sessions, newest last. Optionally
      *  filtered to one session. */
@@ -6563,8 +8498,9 @@ interface SessionsRegistry {
      *  clears the session's awaiting-permission state, and emits
      *  `session:permission-resolved`. */
     respondPermission(id: string, input: PermissionRespondInput): Promise<PermissionRespondResult>;
-    /** Stop tracking a session (after it exited and the user clicked
-     *  "clear"). Doesn't kill — use `kill` first. */
+    /** Stop tracking a session. A still-live session is torn down through
+     *  `kill` first (same teardown as `agent_kill`), so forgetting never
+     *  orphans a running process tree. */
     forget(id: string): boolean;
     /** Await every best-effort fire-and-forget per-session write currently in
      *  flight — today the `CommandLogEntry` → `ToolCallRecord` chain
@@ -6656,8 +8592,10 @@ interface SpawnAgentInput {
     /** Optional initial prompt to dispatch immediately. The promise
      *  the registry returns resolves AFTER the spawn — the prompt
      *  runs in the background, projecting events into the ring
-     *  buffer. Skip to spawn idle. */
-    initialPrompt?: string;
+     *  buffer. Skip to spawn idle. A plain string, or a content-block
+     *  prompt (attachment-bearing first message) — see
+     *  `SpawnAgentSessionInput.prompt`'s doc. */
+    initialPrompt?: string | Record<string, unknown> | unknown[];
     /** The daemon-composed SYSTEM slice of {@link initialPrompt} — the part
      *  it synthesized ahead of the CALLER's ask (role disposition, lineage
      *  line, AGENTS.md, posture preamble). The adapter still receives the
@@ -6749,12 +8687,7 @@ interface SpawnAgentInput {
      *  cost/token fields on the descriptor. Adapter-specific (e.g. hermes
      *  reads its state.db keyed by the adapter session id). Omit for adapters
      *  with no usage source. */
-    readUsage?: () => Promise<{
-        model?: string;
-        costUsd?: number;
-        tokensIn?: number;
-        tokensOut?: number;
-    } | null>;
+    readUsage?: () => Promise<UsageReadResult | null>;
     /** Opt this session into Langfuse tracing (prompt/completion + tool spans +
      *  tokens/cost). Effective opt-in is `trace ?? opts.langfuseTracingDefault ?? false`. */
     trace?: boolean;
@@ -6770,6 +8703,9 @@ interface SpawnAgentInput {
     /** What session close does to the box, when `remote` is true — see
      *  `SessionDescriptor.sandboxTeardown`. */
     sandboxTeardown?: "kill" | "pause";
+    /** Effective adapter confinement, resolved by the caller — see
+     *  `SessionDescriptor.commandSandbox`. */
+    commandSandbox?: "off" | "workspace" | "strict";
     /** Port-to-URL map from the booted sandbox — see
      *  `SessionDescriptor.sandboxPorts`. */
     sandboxPorts?: Record<number, string>;
@@ -6808,15 +8744,12 @@ type PendingAgentOutcome = {
     commandPreview?: string;
     resumable?: boolean;
     nativeTerminalResume?: boolean;
-    readUsage?: () => Promise<{
-        model?: string;
-        costUsd?: number;
-        tokensIn?: number;
-        tokensOut?: number;
-    } | null>;
+    readUsage?: () => Promise<UsageReadResult | null>;
     /** Dispatched now that the tree + driver session both exist — never
-     *  passed to `spawnAgentPending`, which would race the tree. */
-    initialPrompt?: string;
+     *  passed to `spawnAgentPending`, which would race the tree. A plain
+     *  string, or a content-block prompt (attachment-bearing first
+     *  message) — see `SpawnAgentSessionInput.prompt`'s doc. */
+    initialPrompt?: string | Record<string, unknown> | unknown[];
     /** The daemon-composed SYSTEM slice of `initialPrompt` (see
      *  `SpawnAgentInput.initialPromptSystem`) — threaded through the
      *  placeholder so the deferred dispatch records it as a system turn. */
@@ -7092,6 +9025,163 @@ declare function runEagerResumePass(opts: {
     isServed?: (desc: SessionDescriptor) => boolean;
 }): Promise<EagerResumeSummary>;
 
+/**
+ * Continue-interrupted: pick back up the sessions a daemon restart cut off
+ * mid-turn, by sending each an explicit "continue" prompt.
+ *
+ * Everything below the prompt already exists — the persisted registry is the
+ * snapshot, `maybeResumeAgent` resumes a dead row in place (lazily on its first
+ * prompt, or eagerly at boot via `eager-resume.ts`), and the row keeps the
+ * derived `interrupted` marker until its next successful turn-end. What a
+ * restart does NOT do, by design, is re-run the interrupted prompt (prompts
+ * aren't idempotent). This module is the explicit, opt-in replacement for that:
+ * a NEW prompt that tells the agent its last turn was cut off and to check the
+ * state on disk before carrying on.
+ *
+ * Two callers share one eligibility rule + one sender:
+ *   - the manual verb (`session_continue_interrupted` MCP tool,
+ *     `POST /sessions/continue-interrupted`, `agentproto sessions
+ *     continue-interrupted`) — `mode: "manual"`, dry-run by default;
+ *   - the opt-in boot pass (`daemon.continueInterruptedOnBoot`) —
+ *     `mode: "boot"`, run by serve.ts right after the eager resume pass.
+ *
+ * Eligibility (both modes): an agent-cli row that is `interrupted` BY THE LAST
+ * RESTART (`interruptedAtBoot === registry.bootId` — a stale interruption from
+ * an older restart that nobody picked up is left alone), resumable under the
+ * attempt cap (`canResume`), and not already busy. The prompt goes through
+ * `enqueuePrompt`, the normal prompt path, so a dead-but-resumable row
+ * lazy-resumes with its billing auth re-resolved exactly as a human prompt
+ * would.
+ *
+ * No-loop rules (boot mode only — a human pressing the button is intent):
+ *   - never auto-continue a row whose resume has failed (`resumeAttempts > 0`:
+ *     the eager pass, or an earlier attempt, could not bring it back);
+ *   - at most one auto-continue per restart (`lastAutoContinueBoot`);
+ *   - at most `MAX_AUTO_CONTINUE_ATTEMPTS` auto-continues without a successful
+ *     turn-end in between (`autoContinueAttempts`, booked BEFORE sending), so a
+ *     continue turn that keeps getting cut off — or keeps taking the daemon
+ *     down with it — stops being retried.
+ *
+ * Ordering (boot mode): MUST run after the supervisor is re-armed, same
+ * constraint as `eager-resume.ts` — the continue turn's `turn-end` is exactly
+ * what a re-armed completion policy is waiting for — and after the eager pass,
+ * so a row whose eager resume failed is recognisable (`resumeAttempts`) and
+ * skipped rather than lazily retried.
+ */
+
+/** The prompt sent when the caller doesn't supply one. */
+declare const DEFAULT_CONTINUE_PROMPT: string;
+/** Transcript provenance for the continue prompt (`opts.source`). */
+declare const CONTINUE_PROMPT_SOURCE = "daemon:continue-interrupted";
+/** Cap on automatic continue prompts sent to one row without a successful
+ *  turn-end in between (boot mode). 2 = the original interruption gets one
+ *  auto-continue, and if a second restart cuts THAT turn off it gets one more;
+ *  after that only a human (manual verb) re-sends. */
+declare const MAX_AUTO_CONTINUE_ATTEMPTS = 2;
+type ContinueInterruptedSkipReason = 
+/** Unknown id (explicit `ids` filter only). */
+"unknown"
+/** Not interrupted at all — no turn was cut off. */
+ | "not-interrupted"
+/** Interrupted by an EARLIER restart, not the last one. */
+ | "stale-interrupt"
+/** Not in-place resumable (not agent-cli / missing adapter session / archived). */
+ | "not-resumable"
+/** Already burned through `MAX_RESUME_ATTEMPTS` failed resumes. */
+ | "resume-cap-exhausted"
+/** Mid-turn already — someone got there first. */
+ | "busy"
+/** Boot mode: a resume attempt has failed on this row. */
+ | "resume-failed"
+/** Boot mode: already auto-continued by this boot. */
+ | "already-auto-continued"
+/** Boot mode: `MAX_AUTO_CONTINUE_ATTEMPTS` reached without recovering. */
+ | "auto-continue-cap"
+/** Excluded by the cross-process `isServed` gate (another daemon's row). */
+ | "not-served";
+type ContinueInterruptedOutcome = {
+    id: string;
+    name?: string;
+    status: "eligible";
+} | {
+    id: string;
+    name?: string;
+    status: "sent";
+} | {
+    id: string;
+    name?: string;
+    status: "skipped";
+    reason: ContinueInterruptedSkipReason;
+} | {
+    id: string;
+    name?: string;
+    status: "failed";
+    error: string;
+};
+interface ContinueInterruptedResult {
+    dryRun: boolean;
+    /** The prompt that was (or, on a dry run, would be) sent. */
+    prompt: string;
+    /** The boot the candidates were interrupted before (`registry.bootId`). */
+    bootId: string;
+    /** One entry per considered row — every interrupted row when `ids` is
+     *  omitted, every requested id otherwise. Eligible-first ordering matches
+     *  the send order (newest activity first). */
+    sessions: ContinueInterruptedOutcome[];
+    /** Counts by outcome status. */
+    eligible: number;
+    sent: number;
+    skipped: number;
+    failed: number;
+}
+type ContinueInterruptedMode = "manual" | "boot";
+/** Decide one row. `undefined` ⇒ eligible. Pure — reads the descriptor only. */
+declare function continueSkipReason(desc: SessionDescriptor, bootId: string, mode: ContinueInterruptedMode): ContinueInterruptedSkipReason | undefined;
+/**
+ * List — and unless `dryRun` — continue the sessions interrupted by the last
+ * restart. See the module docblock for eligibility, the no-loop rules, and the
+ * ordering contract. No-throw per row: a send that fails admission (row went
+ * busy, resume refused) is reported as `failed` and the pass carries on.
+ */
+declare function continueInterruptedSessions(opts: {
+    registry: Pick<SessionsRegistry, "list" | "get" | "enqueuePrompt" | "bootId" | "recordAutoContinue">;
+    mode: ContinueInterruptedMode;
+    /** Default true: report what would be sent, send nothing. */
+    dryRun?: boolean;
+    /** Restrict to these session ids. Omitted ⇒ every interrupted row. */
+    ids?: readonly string[];
+    /** Custom prompt. Omitted/blank ⇒ `DEFAULT_CONTINUE_PROMPT`. */
+    prompt?: string;
+    /** Max sends in flight at once (each may lazily resume an adapter). Clamped
+     *  to ≥1. Default 4, same as the eager pass. */
+    concurrency?: number;
+    /** Cross-process gate — see `runEagerResumePass`. Omitted ⇒ all served. */
+    isServed?: (desc: SessionDescriptor) => boolean;
+    /** Extra visibility filter (a scoped orchestrator's subtree). Rows it
+     *  rejects are dropped silently — never reported, never sent. */
+    visible?: (desc: SessionDescriptor) => boolean;
+}): Promise<ContinueInterruptedResult>;
+/** Tally of the boot-time continue pass, for the boot-banner line. */
+interface ContinueOnBootSummary {
+    /** False when `daemon.continueInterruptedOnBoot` is off (nothing ran). */
+    enabled: boolean;
+    /** Rows passing eligibility at selection time — the banner's denominator. */
+    eligible: number;
+    sent: number;
+    skipped: number;
+    failed: number;
+}
+/**
+ * The boot pass: `continueInterruptedSessions` in `mode: "boot"`, not a dry
+ * run, reduced to the banner tally. Caller (the gateway handle, invoked from
+ * serve.ts) is responsible for the ordering contract in the module docblock.
+ */
+declare function runContinueOnBootPass(opts: {
+    registry: Parameters<typeof continueInterruptedSessions>[0]["registry"];
+    concurrency: number;
+    isServed?: (desc: SessionDescriptor) => boolean;
+}): Promise<ContinueOnBootSummary>;
+
 /**
  * Daemon-lane PR provenance STAMPER.
  *
@@ -7118,7 +9208,7 @@ declare function runEagerResumePass(opts: {
 
 /** A minimal `gh` runner — resolves with the captured exit code + stdout.
  *  Injected so tests drive stamping without spawning a real `gh`. */
-type GhRunner = (args: readonly string[], cwd: string) => Promise<{
+type GhRunner$1 = (args: readonly string[], cwd: string) => Promise<{
     exitCode: number;
     stdout: string;
 }>;
@@ -7206,7 +9296,7 @@ declare function createPrProvenanceReconciler(opts: {
      *  Defaults to reading the session's own events.jsonl via
      *  {@link readToolCallRecords}; injectable for tests. */
     listToolCalls?: (sessionId: string) => Promise<ToolCallRecord[]>;
-    run?: GhRunner;
+    run?: GhRunner$1;
     host?: string;
 }): PrProvenanceReconciler;
 
@@ -7297,6 +9387,87 @@ interface InboundWatcher {
     shutdown(): void;
 }
 
+/**
+ * Dynamic MCP-app panels for installed `@agentproto/app-kit` apps that ship
+ * a `ui` block (`defineApp({ ui: { html, title?, tools?, csp? } })`,
+ * `app-tools.ts`'s `performInstall`). Bridges `AppRegistry` → `AgnoMcpApp[]`
+ * so `registerMcpApps` (mcp-apps-adapter.ts) can mount them next to the
+ * built-in panels (agentproto_sessions, agents_overview, ...).
+ *
+ * `mcpServerFactory` (index.ts) rebuilds a fresh McpServer per `/mcp`
+ * request, so this module never throws — a bad app record must not take
+ * down every other request. A collided tool id is still skipped with a
+ * `console.warn` (there's nowhere else for a second panel to live). Every
+ * OTHER failure — a removed app dir, a missing/unreadable `ui.path`, a
+ * failed or in-flight `ui.build` — still mounts the panel, serving a
+ * readable HTML placeholder/error page in place of the real bundle
+ * (app-ui-placeholder.ts) instead of skipping it outright: a `ui://`
+ * resource that silently doesn't exist just shows as a JSON-RPC "resource
+ * not found" in a host, which is what motivated this file's placeholder
+ * page in the first place — a HOST-VISIBLE page, even a stand-in one, beats
+ * a resource the host has to explain away as missing.
+ */
+
+/**
+ * The MCP Apps wire (spec `2026-01-26`) over `postMessage` JSON-RPC, exposed
+ * as `window.McpApp.connect() -> Promise<{ callTool, sendMessage,
+ * updateModelContext, openLink, onTeardown }>`. No host in this stack injects
+ * an SDK global into the app iframe, so every UI panel that talks through
+ * `window.McpApp` (all of them — see each app's `ui.ts` under
+ * `packages/apps/src`) would otherwise throw `Cannot read properties of
+ * undefined (reading 'connect')` at boot. Injected here, at serve time, so
+ * every installed app's panel is covered without each app shipping its own
+ * copy of the bridge.
+ *
+ * Bridge surface:
+ * - `callTool(name, args)` — JSON-RPC `tools/call`
+ * - `sendMessage(content)` — JSON-RPC `ui/message`
+ * - `updateModelContext({content?, structuredContent?})` — JSON-RPC
+ *   `ui/update-model-context`; each call replaces the previous context.
+ * - `openLink(url)` — JSON-RPC `ui/open-link` {url}
+ * - `onTeardown(cb)` — register a cleanup callback invoked on
+ *   `ui/resource-teardown` from the host, at which point the bridge also
+ *   replies `{result:{}}` automatically.
+ * - `getHostContext()` / `onHostContext(cb)` — the host context captured
+ *   from the `ui/initialize` result and merged on every
+ *   `ui/notifications/host-context-changed` (the notification carries only
+ *   the changed keys, per the ext-apps spec).
+ * - `getToolInput()` / `onToolInput(cb)` — the arguments the panel's own tool
+ *   (`app_ui_<slug>`) was invoked with, from `ui/notifications/tool-input`,
+ *   falling back to the tool's own result (`ui/notifications/tool-result`,
+ *   which `registerMcpApps` fills with `execute()`'s return value) for a host
+ *   that forwards results but not inputs. A late subscriber is replayed the
+ *   last value, same as `onHostContext`. Lets an MCP-hosted panel resolve a
+ *   deep link (e.g. `{view: "wallets/my-profile"}`) the way the browser-served
+ *   panel resolves `location.hash`.
+ * - `displayMode` — `{get, available, request, onChange, mountToggle}`, the
+ *   shared controller from `@agentproto/app-client/display-mode` (also
+ *   published as `window.McpApp.displayMode` once connected). It is what
+ *   mounts the floating ⤢ toggle; an app that wants the control in its own
+ *   header opts the floating one out (`<meta name="agentproto-display-toggle"
+ *   content="none">`, or `connect({displayToggle: "none"})`) and calls
+ *   `displayMode.mountToggle(el)` instead.
+ */
+declare const MCP_APP_BRIDGE_SCRIPT = "<script>\n(function () {\n  window.__AGENTPROTO_UI_TRANSPORT__ = \"mcp\";\n  if (window.McpApp) return;\n  var nextId = 1, pending = {}, teardownCbs = [];\n  var hostContext = null, hostContextCbs = [];\n  var toolInput = null, toolInputCbs = [];\n  function post(m) { window.parent.postMessage(m, \"*\"); }\n  function getHostContext() { return hostContext; }\n  function onHostContext(cb) {\n    hostContextCbs.push(cb);\n    // Replay the last context so a late subscriber isn't stuck blind.\n    if (hostContext) { try { cb(hostContext); } catch (_) {} }\n  }\n  function setHostContext(ctx) {\n    if (!ctx || typeof ctx !== \"object\") return;\n    // host-context-changed carries only the changed keys \u2014 merge, matching\n    // the official ext-apps App behaviour.\n    hostContext = Object.assign({}, hostContext || {}, ctx);\n    for (var i = 0; i < hostContextCbs.length; i++) {\n      try { hostContextCbs[i](hostContext); } catch (_) {}\n    }\n  }\n  function getToolInput() { return toolInput; }\n  function onToolInput(cb) {\n    toolInputCbs.push(cb);\n    // Replay the last known input so a late subscriber isn't stuck blind \u2014\n    // same convention as onHostContext.\n    if (toolInput) { try { cb(toolInput); } catch (_) {} }\n  }\n  function setToolInput(input) {\n    if (!input || typeof input !== \"object\") return;\n    toolInput = input;\n    for (var i = 0; i < toolInputCbs.length; i++) {\n      try { toolInputCbs[i](toolInput); } catch (_) {}\n    }\n  }\n  // A ui/notifications/tool-result carries the full CallToolResult of the\n  // tool call that opened this view (spec 2026-01-26) \u2014 the same envelope\n  // registerMcpApps wraps execute()'s return value in (JSON text content, or\n  // structuredContent). Read as a fallback source of the tool's arguments\n  // for a host that forwards results but not tool-input.\n  function extractToolResultInput(result) {\n    try {\n      if (result && result.structuredContent && typeof result.structuredContent === \"object\") {\n        return result.structuredContent;\n      }\n      var c = result && Array.isArray(result.content) ? result.content[0] : null;\n      if (c && c.type === \"text\" && typeof c.text === \"string\") return JSON.parse(c.text);\n    } catch (_) {}\n    return null;\n  }\n  window.addEventListener(\"message\", function (e) {\n    var m = e.data;\n    if (typeof m === \"string\") { try { m = JSON.parse(m); } catch (_) { return; } }\n    if (!m || m.jsonrpc !== \"2.0\") return;\n    if (m.method === \"ui/resource-teardown\") {\n      for (var i = 0; i < teardownCbs.length; i++) teardownCbs[i]();\n      post({ jsonrpc: \"2.0\", id: m.id, result: {} });\n      return;\n    }\n    if (m.method === \"ui/notifications/host-context-changed\") { setHostContext(m.params || {}); return; }\n    if (m.method === \"ui/notifications/tool-input\") { setToolInput((m.params || {}).arguments); return; }\n    if (m.method === \"ui/notifications/tool-result\") { setToolInput(extractToolResultInput(m.params)); return; }\n    if (m.id != null && pending[m.id]) { var cb = pending[m.id]; delete pending[m.id]; cb(m.result, m.error); }\n  });\n  function request(method, params) {\n    return new Promise(function (resolve, reject) {\n      var id = nextId++;\n      pending[id] = function (r, err) { if (err) reject(new Error((err && err.message) || String(err))); else resolve(r); };\n      post({ jsonrpc: \"2.0\", id: id, method: method, params: params });\n    });\n  }\n  function requestDisplayMode(mode) { return request(\"ui/request-display-mode\", { mode: mode }); }\n  // The shared toggle (@agentproto/app-client/display-mode), injected right\n  // after this script. Absent only when the app ships its own\n  // window.AgentprotoUI namespace, which suppresses that injection \u2014 the\n  // fallback keeps window.McpApp.displayMode callable either way.\n  function installDisplayMode(opts) {\n    var api = { getHostContext: getHostContext, onHostContext: onHostContext, requestDisplayMode: requestDisplayMode };\n    if (window.AgentprotoUI && window.AgentprotoUI.installDisplayMode) {\n      return window.AgentprotoUI.installDisplayMode(api, opts);\n    }\n    return {\n      get: function () { return (hostContext && hostContext.displayMode) || \"inline\"; },\n      available: function () { return (hostContext && hostContext.availableDisplayModes) || []; },\n      request: requestDisplayMode,\n      onChange: function (cb) { onHostContext(function (c) { cb((c && c.displayMode) || \"inline\", c); }); return function () {}; },\n      mountToggle: function () { return null; }\n    };\n  }\n  window.McpApp = {\n    connect: function (opts) {\n      if (window.parent === window) return Promise.reject(new Error(\"no host (standalone)\"));\n      return request(\"ui/initialize\", {\n        appInfo: { name: \"agentproto-app\", version: \"1.0\" },\n        appCapabilities: { availableDisplayModes: [\"inline\", \"fullscreen\"] },\n        protocolVersion: \"2026-01-26\"\n      }).then(function (result) {\n        // The initialize result carries the initial hostContext (displayMode,\n        // availableDisplayModes, theme, safeAreaInsets) \u2014 capture it before\n        // notifying the host, so the toggle renders in the right place on\n        // its first paint rather than after a host-context-changed.\n        if (result && result.hostContext) setHostContext(result.hostContext);\n        post({ jsonrpc: \"2.0\", method: \"ui/notifications/initialized\", params: {} });\n        var displayMode = installDisplayMode((opts && opts.displayToggle) ? { toggle: opts.displayToggle } : null);\n        window.McpApp.displayMode = displayMode;\n        return {\n          callTool: function (name, args) { return request(\"tools/call\", { name: name, arguments: args || {} }); },\n          sendMessage: function (p) {\n            var params = typeof p === \"string\" ? { content: p } : (p || {});\n            var content = typeof params.content === \"string\" ? [{ type: \"text\", text: params.content }] : (params.content || []);\n            return request(\"ui/message\", { role: \"user\", content: content });\n          },\n          updateModelContext: function (p) { return request(\"ui/update-model-context\", p || {}); },\n          openLink: function (url) { return request(\"ui/open-link\", { url: url }); },\n          onTeardown: function (cb) { teardownCbs.push(cb); },\n          getHostContext: getHostContext,\n          onHostContext: onHostContext,\n          getToolInput: getToolInput,\n          onToolInput: onToolInput,\n          displayMode: displayMode\n        };\n      });\n    }\n  };\n})();\n</script>\n";
+/** Inject `MCP_APP_BRIDGE_SCRIPT` followed by the two
+ *  `window.AgentprotoUI` scripts (`DISPLAY_MODE_SCRIPT`, then
+ *  `RUNNER_SELECT_SCRIPT`) — every installed app UI gets the shared
+ *  display-mode toggle and `mountRunnerSelect` for free, same as it gets
+ *  `window.McpApp` (see `injectAfterStructuralTag` for the placement rule).
+ *  The halves are independently idempotent, so a single
+ *  `injectAfterStructuralTag` call inserts only whichever ones the document
+ *  doesn't already define — inserting them one call each would place the
+ *  second BEFORE the first (all target "right after the same structural
+ *  tag"), which is why they're concatenated first instead. `window.
+ *  AgentprotoUI` gates BOTH of its scripts as one unit: a document that
+ *  already defines that namespace brings its own, and the bridge's
+ *  `installDisplayMode` falls back to a controller with no button rather
+ *  than fighting it. The bridge guard matches an assignment only — every
+ *  app panel CONSUMES `window.McpApp.connect()`, so matching any mention
+ *  would skip injection for exactly the documents that need it, leaving
+ *  `window.McpApp` undefined in the host iframe. */
+declare function injectMcpAppBridge(html: string): string;
+
 /**
  * MCP tools that expose the per-workspace brain to agents.
  *
@@ -7420,6 +9591,326 @@ interface WorkspaceBrainSubscriber {
 }
 declare function createWorkspaceBrainSubscriber(opts: WorkspaceBrainSubscriberOptions): WorkspaceBrainSubscriber;
 
+/**
+ * Review ledger — the daemon-side record of every review attestation.
+ *
+ * Lives under the daemon state dir, NEVER in the reviewed repo's working
+ * tree: `~/.agentproto/reviews/<repo-slug>/<manifestSha>/<binding>/<rangeSha>.json`
+ * — the path IS the ledger key `(repoRemote, manifestSha, binding, rangeSha)`
+ * (the repo slug is a filesystem-safe form of the normalized remote). One
+ * file per key; a re-run of the same key overwrites it with the newer
+ * attestation.
+ *
+ * Every attestation is recorded — including `incomplete` and dirty-tree ones,
+ * so `review_ledger` shows the history honestly — but only a clean `pass` /
+ * `block` is ever served back as a cache hit (see `lookupCached`).
+ *
+ * Each file is an {@link LedgerEntry}: the self-contained attestation (what
+ * `review_export` writes out) plus host-local metadata that is NOT part of
+ * what gets attested (the checkout path, the manifest path, the manifest's
+ * `verdict.exportDir`).
+ *
+ * Beside each entry sits an optional `<rangeSha>.annotations.json`
+ * ({@link LedgerAnnotations}): the MUTABLE follow-up layer — a PR link found
+ * after the fact, and `review_pr` status snapshots appended over time. It is
+ * never hashed into (or exported with) the attestation, so annotating an
+ * entry can't disturb a signature over it.
+ *
+ * Same persistence primitives as the sibling JSON stores (`node:fs/promises`,
+ * write-tmp + rename). The root is injectable so tests never touch
+ * `~/.agentproto`.
+ */
+
+/** Host-local metadata stored beside an attestation (never exported). */
+interface LedgerHostMeta {
+    /** Absolute path of the checkout the review ran in. */
+    repoRoot: string;
+    /** Absolute path of the REVIEW.md that was used. */
+    manifestPath: string;
+    /** The manifest's `verdict.exportDir`, resolved against `repoRoot`. */
+    exportDir?: string;
+}
+interface LedgerEntry {
+    attestation: Attestation;
+    host: LedgerHostMeta;
+}
+/** One `review_pr` status fetch. */
+interface PrStatusSnapshot {
+    /** ISO timestamp of the fetch. */
+    fetchedAt: string;
+    state: "open" | "merged" | "closed";
+    reviews: Array<{
+        login: string;
+        state: string;
+        submittedAt: string;
+    }>;
+    checks?: Array<{
+        name: string;
+        conclusion: string | null;
+    }>;
+}
+/** The mutable annotations sidecar of a ledger entry. */
+interface LedgerAnnotations {
+    pr?: ReviewPrRef;
+    /** Oldest first — each `review_pr` call appends one. */
+    prStatus?: PrStatusSnapshot[];
+}
+interface ReviewLedgerFilter {
+    repoRemote?: string;
+    rangeSha?: string;
+    binding?: string;
+    manifestSha?: string;
+}
+interface ReviewLedger {
+    /** Absolute root directory of the ledger. */
+    readonly root: string;
+    put(entry: LedgerEntry): Promise<string>;
+    get(key: LedgerKey): Promise<LedgerEntry | undefined>;
+    /** A reusable verdict for `key`: a clean (not dirty) `pass`/`block` whose
+     *  rubric digests still match. `incomplete` is never reused. */
+    lookupCached(key: LedgerKey, rubrics: readonly RubricDigest[]): Promise<LedgerEntry | undefined>;
+    findByRunId(runId: string): Promise<LedgerEntry | undefined>;
+    /** Entries matching `filter`, newest first. */
+    list(filter?: ReviewLedgerFilter): Promise<LedgerEntry[]>;
+    /** The annotations sidecar of `key` (`{}` when there is none). */
+    getAnnotations(key: LedgerKey): Promise<LedgerAnnotations>;
+    /** Read-modify-write the annotations sidecar of `key`; returns the result. */
+    updateAnnotations(key: LedgerKey, update: (current: LedgerAnnotations) => LedgerAnnotations): Promise<LedgerAnnotations>;
+}
+/** Record `pr` as the entry's PR link (replacing any previous link). */
+declare const withPr: (pr: ReviewPrRef) => (a: LedgerAnnotations) => LedgerAnnotations;
+/** Append one status snapshot. */
+declare const withPrStatus: (snapshot: PrStatusSnapshot) => (a: LedgerAnnotations) => LedgerAnnotations;
+declare const defaultReviewLedgerRoot: () => string;
+/** Filesystem-safe slug of a normalized repo remote
+ *  (`github.com/agentproto/ts` → `github.com_agentproto_ts`). */
+declare function repoSlug(repoRemote: string): string;
+declare function createReviewLedger(opts?: {
+    root?: string;
+}): ReviewLedger;
+
+/**
+ * Review runner — the daemon host for `@agentproto/review`.
+ *
+ * The pure package parses REVIEW.md and compiles a binding into an ordinary
+ * AIP-15 workflow; this module supplies everything that touches the world:
+ *
+ *   1. resolve the repo + range — `merge-base(<target.base>, HEAD)..HEAD`
+ *      unless the caller pins `base`/`head`;
+ *   2. ledger pre-check — a clean `pass`/`block` already recorded for the
+ *      same `(repoRemote, manifestSha, binding, rangeSha)` (and the same
+ *      rubric digests) is returned with `cached: true`, nothing runs;
+ *   3. execute the compiled workflow through `@agentproto/workflow-runtime`'s
+ *      `compileWorkflow` + `runWorkflow` — prepare steps (the engine's own
+ *      gate runner), then the FREEZE (head resolved after prepare), then the
+ *      lanes in parallel through {@link createReviewLaneExecutor}, then the
+ *      fan-in verdict;
+ *   4. build the attestation and write it to the ledger. A CANCELLED run
+ *      (`cancel()`, or superseded by a newer head — see `supersede`) writes
+ *      nothing: nobody asked for its verdict any more.
+ *
+ * Lanes: command lanes run `sh -c <run>` in their own process group with a
+ * hard timeout; agent lanes spawn a CHILD REVIEWER SESSION through
+ * {@link ReviewerSessionHost} — in the daemon, {@link createDaemonReviewerHost},
+ * which uses the same `spawnAgentSession` core `agent_start` uses and kills
+ * the session through the registry on timeout/cancel (a child session, never
+ * an orphan pid). The reviewer gets a pointer-style prompt (range + rubric
+ * path) and writes a structured verdict file under the ledger's run dir —
+ * outside the reviewed tree.
+ *
+ * Async pattern mirrors `WorkflowRunner`: `start()` returns a run record
+ * immediately and executes in the background; `status()` polls; `wait()`
+ * blocks. Runs live in memory for the daemon's lifetime; the ATTESTATION is
+ * what persists (the ledger), and `status()` falls back to it for a run that
+ * finished before a daemon restart.
+ */
+
+/**
+ * Normalize a git remote URL so SSH and HTTPS clones of the same repo agree:
+ * `git@github.com:agentproto/ts.git` and `https://user@github.com/agentproto/ts`
+ * both become `github.com/agentproto/ts`. Credentials are always stripped.
+ */
+declare function normalizeRemote(url: string): string;
+/** Run one command lane: `sh -c <command>` in its own process group, output
+ *  captured (tail-bounded), hard-killed on timeout or cancel. */
+declare function runShellLane(input: {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<LaneOutcome>;
+/** Outcome of one reviewer session's run. */
+type ReviewerRunResult = {
+    status: "ended";
+    sessionId: string;
+    preset: string;
+    model?: string;
+} | {
+    status: "timeout";
+    sessionId: string;
+    preset: string;
+    model?: string;
+} | {
+    status: "failed";
+    error: string;
+    sessionId?: string;
+    preset?: string;
+    model?: string;
+};
+/**
+ * The agent-lane executor seam: spawn a reviewer session under a harness
+ * preset, run ONE turn with `prompt`, and stop it — killing it through the
+ * session lifecycle on timeout or cancel. The daemon wires
+ * {@link createDaemonReviewerHost}; tests wire a fake.
+ */
+interface ReviewerSessionHost {
+    run(input: {
+        preset: string;
+        cwd: string;
+        prompt: string;
+        label: string;
+        timeoutMs: number;
+        parentSessionId?: string;
+        signal?: AbortSignal;
+    }): Promise<ReviewerRunResult>;
+}
+interface ReviewLaneExecutorContext {
+    runId: string;
+    reviewId: string;
+    repoRoot: string;
+    manifestPath: string;
+    /** Directory the agent lanes' verdict files are written under. */
+    runDir: string;
+    reviewers?: ReviewerSessionHost;
+    parentSessionId?: string;
+}
+/** The daemon's {@link ReviewLaneExecutor}: subprocess command lanes, child
+ *  reviewer sessions for agent lanes. */
+declare function createReviewLaneExecutor(ctx: ReviewLaneExecutorContext): ReviewLaneExecutor;
+interface ReviewRunInput {
+    /** Any directory inside the repo to review. */
+    cwd: string;
+    /** REVIEW.md path — absolute, or relative to `cwd`. Default: `<repo root>/REVIEW.md`. */
+    manifestPath?: string;
+    /** Binding name. Default: the sole binding, or `default`. */
+    binding?: string;
+    /** Range base (ref or sha). Default: `merge-base(<target.base>, HEAD)`. */
+    base?: string;
+    /** Range head (ref or sha). Default: `HEAD`, resolved AFTER prepare. */
+    head?: string;
+    /** Ignore a cached ledger verdict and re-run. */
+    nocache?: boolean;
+    /** Session the agent lanes' reviewer sessions nest under. */
+    parentSessionId?: string;
+    /** Session that requested the review — recorded as
+     *  `attestation.requester.sessionId`. Default: `parentSessionId`. */
+    requesterSessionId?: string;
+    /** The PR the range is being reviewed for, when the caller knows it —
+     *  recorded as `attestation.pr` and as the entry's annotation link. */
+    pr?: ReviewPrRef;
+    /** Before running, cancel in-flight runs for the same repo + binding + base
+     *  whose head DIFFERS (an older push nobody will read the verdict of) — as
+     *  long as that run is the same line of work: the same checkout, or a head
+     *  that is an ancestor of this one. A sibling branch reviewed from another
+     *  worktree off the same base is never cancelled. Gates should pass
+     *  `true`; the default is `false`. */
+    supersede?: boolean;
+}
+type ReviewRunStatus = "running" | "done" | "failed" | "cancelled";
+interface ReviewRun {
+    runId: string;
+    status: ReviewRunStatus;
+    startedAt: string;
+    endedAt?: string;
+    reviewId?: string;
+    binding?: string;
+    repoRemote?: string;
+    /** The resolved range base, once known. */
+    baseSha?: string;
+    /** The range head: the pre-prepare head once resolved, then the frozen head. */
+    headSha?: string;
+    /** The checkout the run reviews, once resolved. */
+    repoRoot?: string;
+    /** Set on a run cancelled because a newer head superseded it. */
+    supersededBy?: string;
+    /** Lanes settled so far (live progress while `running`). */
+    lanes: LaneResult[];
+    /** Set once `done`. */
+    attestation?: Attestation;
+    /** True when `attestation` was served from the ledger — nothing ran. */
+    cached?: boolean;
+    /** Where the attestation was written in the ledger. */
+    ledgerPath?: string;
+    error?: string;
+}
+interface ReviewRunner {
+    start(input: ReviewRunInput): ReviewRun;
+    status(runId: string): Promise<ReviewRun | undefined>;
+    wait(runId: string): Promise<ReviewRun | undefined>;
+    cancel(runId: string): boolean;
+    readonly ledger: ReviewLedger;
+}
+interface CreateReviewRunnerOptions {
+    ledger: ReviewLedger;
+    /** Agent-lane executor. Omitted ⇒ agent lanes are `skipped` (and the
+     *  verdict therefore `incomplete`), never silently passed. */
+    reviewers?: ReviewerSessionHost;
+    /** Attestor identity. Default: `agentproto-runtime@<hostname>`. */
+    daemonId?: string;
+}
+/** Placeholder values the daemon binds for every review. `{changed}` is a
+ *  shell-quoted turbo filter for the packages changed since the range base
+ *  (compose dependents with `...{changed}`). */
+declare function hostPlaceholders(baseSha: string): Record<string, string>;
+declare function createReviewRunner(opts: CreateReviewRunnerOptions): ReviewRunner;
+
+/**
+ * PR follow-up for review attestations — the host side of `review_pr`.
+ *
+ * A review attests a git range; whether that range became a PR, and what
+ * happened to the PR afterwards, is only knowable later. This module asks
+ * GitHub through the daemon host's authed `gh` CLI (shelled out — no HTTP
+ * client, no token handling of our own):
+ *
+ *   - {@link findPrForCommit}: `headSha → PR` via
+ *     `gh api repos/{owner}/{repo}/commits/{sha}/pulls`;
+ *   - {@link fetchPrStatus}: the PR's state + reviews (+ check runs on the
+ *     PR head, best-effort) as one {@link PrStatusSnapshot}.
+ *
+ * Every failure is a {@link PrLookupError} with a stable `code` — `gh`
+ * missing, `gh` failing (auth, network, 404), a non-GitHub remote, no PR for
+ * the commit — so the tool can return it as structured data instead of
+ * throwing.
+ */
+
+type PrLookupErrorCode = "gh_unavailable" | "gh_failed" | "unsupported_remote" | "no_pr";
+declare class PrLookupError extends Error {
+    readonly code: PrLookupErrorCode;
+    constructor(code: PrLookupErrorCode, message: string);
+}
+/** Runs `gh <args>` and resolves its stdout. */
+type GhRunner = (args: readonly string[]) => Promise<string>;
+/** The real runner: `gh` from the daemon's PATH. A missing binary is
+ *  `gh_unavailable`; any non-zero exit is `gh_failed` with gh's stderr. */
+declare const execGh: GhRunner;
+/** `github.com/owner/name` → `owner/name`; `undefined` for any other host.
+ *  Also accepts the multi-account SSH host-alias convention
+ *  (`git@github.com-work:owner/name` normalizes to `github.com-work/owner/name`). */
+declare function githubRepoOf(repoRemote: string): string | undefined;
+/** Parse `https://github.com/owner/name/pull/42` (trailing path/query ok). */
+declare function parsePrUrl(url: string): {
+    repo: string;
+    number: number;
+} | undefined;
+/** The PR `headSha` belongs to, or `undefined` when GitHub knows none.
+ *  Prefers a PR whose head IS `headSha`, then an open one, then the first. */
+declare function findPrForCommit(gh: GhRunner, repo: string, headSha: string): Promise<ReviewPrRef | undefined>;
+/** The PR's head sha (for matching a `prUrl` to ledger entries). */
+declare function prHeadSha(gh: GhRunner, repo: string, number: number): Promise<string | undefined>;
+/** One status snapshot of `pr`: state, reviews, and (best-effort — omitted
+ *  when that call fails) the check runs on the PR's current head. */
+declare function fetchPrStatus(gh: GhRunner, pr: ReviewPrRef, now?: () => Date): Promise<PrStatusSnapshot>;
+
 /**
  * `~/.agentproto/harness-presets.json` — the persisted harness→profile binding
  * (mode 0600). A {@link HarnessPreset} names, per adapter harness, WHICH auth
@@ -7527,6 +10018,77 @@ declare function removeHarnessPreset(id: string): Promise<boolean>;
  */
 declare function setDefaultPreset(harnessSlug: string, presetId: string): Promise<HarnessPreset>;
 
+/**
+ * The daemon's {@link ReviewerSessionHost}: agent review lanes as CHILD
+ * SESSIONS, spawned through the same `spawnAgentSession` core `agent_start`
+ * uses, waited on with the same `monitorSessionWait` core `session_monitor` /
+ * `sessions wait` use, and stopped through `registry.kill` — the normal
+ * session lifecycle, so a timed-out or cancelled reviewer is a killed session
+ * in `session_list`, never an orphan pid.
+ *
+ * A lane's `preset` names the daemon's existing preset surface — no parallel
+ * model/auth config: first a harness preset (`harness-presets.json`: adapter
+ * harness + auth profile + default model), then a user preset
+ * (`presets.json`, handed to `spawnAgentSession` as-is so it expands the
+ * preset exactly like `agent_start.presetId` does).
+ *
+ * Reviewers spawn with role `executor` (no re-delegation), `worktree: false`
+ * (they read the reviewed checkout's history; they never edit), and
+ * `dedupe: false` (two lanes/runs with the same label are distinct
+ * reviewers, never merged).
+ */
+
+interface DaemonReviewerHostDeps {
+    registry: SessionsRegistry;
+    sessionEvents: SessionEventBus;
+    eventRing: EventRing;
+    resolveAgentAdapter: AgentAdapterResolver;
+    /** Extra spawn deps forwarded to `spawnAgentSession` (sandbox resolver,
+     *  catalog models, …). `registry`/`resolveAgentAdapter` always win. */
+    spawnDeps?: Partial<SpawnAgentSessionDeps>;
+    /** Preset lookups — injectable for tests; default to the real stores. */
+    getHarnessPreset?: (id: string) => Promise<HarnessPreset | undefined>;
+    getUserPreset?: (id: string) => Promise<UserPreset | undefined>;
+}
+/** Resolve a lane's `preset` to spawn fields — harness preset first, then a
+ *  user preset. `undefined` when neither store knows the id. */
+declare function resolveReviewerPreset(preset: string, lookups?: Pick<DaemonReviewerHostDeps, "getHarnessPreset" | "getUserPreset">): Promise<Pick<SpawnAgentSessionInput, "adapter" | "model" | "access" | "preset"> | undefined>;
+declare function createDaemonReviewerHost(deps: DaemonReviewerHostDeps): ReviewerSessionHost;
+
+/**
+ * MCP tools for the review primitive (`@agentproto/review`):
+ *
+ *   review_run     run a REVIEW.md binding over a git range → attestation
+ *                  (ledger hit ⇒ the cached verdict, `cached: true`)
+ *   review_status  poll a run started with `wait: false`
+ *   review_cancel  cancel a running review (lane sessions are killed)
+ *   review_ledger  list recorded attestations
+ *   review_export  write one attestation out as a standalone JSON file
+ *   review_pr      follow a recorded review to its GitHub PR (via `gh`):
+ *                  link it, snapshot the PR's state/reviews/checks into the
+ *                  entry's annotations, return the combined view
+ *
+ * Async pattern mirrors `workflow_start`/`workflow_status`: `review_run`
+ * blocks by default (`wait: true`) — pass `wait: false` for long reviews and
+ * poll `review_status` with the returned `runId`.
+ *
+ * Trust note: `review_run` executes the command checks the repo's own
+ * REVIEW.md declares (`sh -c`), the same trust `workflow_run_file` extends to
+ * a WORKFLOW.md's gate steps — not the `command_execute` allowlist, which
+ * governs ad-hoc commands a remote caller composes.
+ */
+
+interface RegisterReviewToolsOptions {
+    runner: ReviewRunner;
+    /** The calling session (from `?callerSessionId=`) — agent-lane reviewer
+     *  sessions nest under it, and it is the default requester. */
+    callerSessionId?: string;
+    /** `gh` runner for `review_pr` — injectable for tests. Default: the real
+     *  `gh` on the daemon's PATH. */
+    gh?: GhRunner;
+}
+declare function registerReviewTools(server: McpServer, opts: RegisterReviewToolsOptions): void;
+
 /**
  * Built-in custom-route registration (PR-5).
  *
@@ -7987,6 +10549,76 @@ declare function reapGcEntry(entry: SandboxLedgerEntry, opts: {
 /** States that still name a box the gc might act on. */
 declare const GC_REAPABLE_STATES: readonly SandboxLedgerState[];
 
+/**
+ * Sandbox ledger reconcile — closes the gap between what
+ * `~/.agentproto/sandboxes.json` believes is still booted/paused/connected
+ * and what the PROVIDER actually still has running. A failed teardown, a
+ * daemon that crashed mid-close, or a provider-side idle-reap the daemon
+ * never heard about all leave a ledger row claiming a box is alive long
+ * after the provider reaped it — real-world evidence: one daemon's ledger
+ * carried ~50 rows in "paused" while the provider had far fewer boxes left.
+ *
+ * This is read-only against the PROVIDER (`SandboxProvider.probe`, the same
+ * primitive `GET /sandboxes/:id/alive` and `agentproto sandbox list` already
+ * use per-row) and never tears a box down — it only ever flips a ledger
+ * row's `state` to `"gone"` via `recordSandboxLiveness` when the provider
+ * confirms the box no longer exists. A box a caller still wants stays
+ * completely untouched; this module has no `stop()`/`pause()`/`connect()`
+ * call anywhere in it.
+ */
+
+/** The slice of `SandboxProviderHandle` reconcile needs — just the liveness
+ *  probe, so tests (and the `local` provider, which has none) can hand back
+ *  a handle without a `probe` at all. */
+interface SandboxReconcileProviderHandle {
+    provider: {
+        probe?(sandboxId: string): Promise<{
+            alive: boolean;
+            state?: string;
+        }>;
+    };
+}
+interface SandboxReconcileDeps {
+    /** Resolve a ledger row's provider slug to a handle. Mirrors
+     *  `SandboxGcReapDeps.resolveProvider` (`sandbox-gc.ts`) — same DI shape,
+     *  narrower need (probe only, never connect/boot). */
+    resolveProvider: (slug: string) => Promise<SandboxReconcileProviderHandle | null>;
+    /** Defaults to `readSandboxLedger` — injectable so callers that already
+     *  hold a mocked/scoped ledger reader (tests, a scoped CLI mock) can reuse
+     *  it instead of this module reaching for the real `~/.agentproto/
+     *  sandboxes.json` on disk. */
+    readLedger?: (path?: string) => SandboxLedgerEntry[];
+    /** Defaults to `recordSandboxLiveness` — same injectability reasoning. */
+    recordLiveness?: (sandboxId: string, alive: boolean, path?: string) => void;
+    ledgerPath?: string;
+}
+/** Verdict for one reconciled row. `"skipped"` means the provider has no
+ *  `probe()` (e.g. Box today) — never treated as evidence of death. */
+type SandboxReconcileVerdict = "alive" | "gone" | "unknown" | "skipped";
+interface SandboxReconcileRow {
+    sandboxId: string;
+    provider: string;
+    verdict: SandboxReconcileVerdict;
+    /** Present when `verdict` is "unknown" — the resolve/probe failure message. */
+    error?: string;
+}
+interface SandboxReconcileResult {
+    checked: number;
+    alive: number;
+    gone: number;
+    unknown: number;
+    skipped: number;
+    rows: SandboxReconcileRow[];
+}
+/**
+ * Probe every ledger row still claiming to be alive against its provider,
+ * and stamp the verdict back into the ledger (`recordSandboxLiveness` flips
+ * a dead row to `"gone"`; a live or unprobeable row is left as-is). One
+ * broken row's provider resolution or probe call never aborts the pass for
+ * the rest — each row's outcome is independent and best-effort.
+ */
+declare function reconcileSandboxLedger(deps: SandboxReconcileDeps): Promise<SandboxReconcileResult>;
+
 /**
  * Idle agent-session reaper (PR-6).
  *
@@ -8247,6 +10879,108 @@ declare function formatToolCall(toolName: string, args: unknown): string;
  */
 declare function formatToolResult(toolName: string | undefined, result: unknown, isError: boolean): string | null;
 
+/**
+ * Pure sizing helper for a `tools/list` response — shared by
+ * `scripts/measure-mcp-tools.mjs` (human-readable before/after report) and
+ * the budget-guard test (`__tests__/tool-schema-budget.test.ts`) so both
+ * measure the exact same thing: the JSON bytes an MCP client actually pays
+ * for per tool (`description` + `inputSchema`), sorted biggest first.
+ */
+interface MeasuredToolEntry {
+    name: string;
+    bytes: number;
+}
+interface ToolListMeasurement {
+    entries: MeasuredToolEntry[];
+    totalBytes: number;
+}
+interface MeasurableTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+/** UTF-8 byte size of the `{description, inputSchema}` JSON a client
+ *  receives for one tool — the same two fields `tools/list` sends over the
+ *  wire, so this tracks prompt-token cost rather than just character count. */
+declare function measureTool(tool: MeasurableTool): number;
+declare function measureToolList(tools: readonly MeasurableTool[]): ToolListMeasurement;
+
+/**
+ * Long-form MCP tool documentation, read from `docs/mcp-tools/<name>.md`.
+ *
+ * The schema `description` on a tool/field is a contract: what it does, and
+ * the one rule that prevents a wrong call — kept short so `tools/list` stays
+ * cheap. Everything else (edge cases, interactions with other fields,
+ * examples, history) lives here instead, fetched on demand by the `tool_help`
+ * MCP tool (`tool-help-mcp.ts`) and the `agentproto help <tool>` CLI verb
+ * (`packages/cli/src/commands/help.ts`) — both call the two functions below,
+ * so the markdown file is the single source both surfaces read.
+ *
+ * `docs/mcp-tools/` sits at the PACKAGE root (a sibling of `src`/`dist`, not
+ * the repo-level `docs/`) so it ships inside the published npm tarball —
+ * see the `files` array in `package.json`. Resolved relative to this
+ * module's own directory rather than by package name: whether this code is
+ * running from `src` (vitest, no build) or `dist` (built/published), the
+ * module's directory is always a direct child of the package root, so one
+ * `..` reaches it either way — no `require.resolve` needed.
+ */
+/** Full markdown help text for `name`, or `undefined` when no doc exists. */
+declare function getToolHelp(name: string): string | undefined;
+/** Every tool name with a help doc available — for a "did you mean" list. */
+declare function listToolHelpTopics(): string[];
+/** Extract a `## <topic>` section (case-insensitive) up to the next `##`
+ *  heading — shared by the `tool_help` MCP tool and the `agentproto help`
+ *  CLI verb so both slice a doc identically. `undefined` when no section
+ *  with that heading exists. */
+declare function extractHelpSection(doc: string, topic: string): string | undefined;
+
+/**
+ * Subtree usage rollup: one session's own usage plus the summed usage of
+ * every session it (transitively) spawned — the shape `session_usage
+ * { includeSubtree: true }` and `GET /sessions/:id/usage?includeSubtree=1`
+ * return.
+ *
+ * Pure over a descriptor list (walked by `parentSessionId`, the same graph
+ * `collectSubtree` uses for orchestrator scoping), so it's unit-testable
+ * without a registry.
+ *
+ * Absent stays absent: a total is the sum of the sessions that REPORT the
+ * field, and is omitted entirely when none of them do — a subtree of
+ * cost-less sessions never reads as a measured $0.
+ */
+
+/** Summed usage across the root and all its descendants. */
+interface SubtreeUsageTotals {
+    /** Sessions counted, root included. */
+    sessions: number;
+    costUsd?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+/** One direct child of the root, with that child's OWN usage (its own
+ *  descendants roll up into `subtree`, not here). */
+interface SubtreeChildUsage {
+    id: string;
+    label?: string;
+    status: SessionDescriptor["status"];
+    costUsd?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+}
+interface SessionUsageWithSubtree {
+    self: SessionUsage;
+    subtree: SubtreeUsageTotals;
+    children: SubtreeChildUsage[];
+}
+/**
+ * Roll `root`'s usage up over its subtree. `all` should be the FULL
+ * descriptor list (archived included) so an archived intermediate session
+ * doesn't sever the parent→child chain.
+ */
+declare function rollupSessionSubtree(root: SessionDescriptor, all: readonly SessionDescriptor[]): SessionUsageWithSubtree;
+
 /**
  * Dependency-injection surface for MCP credential resolution.
  *
@@ -8351,6 +11085,26 @@ declare function enrichRollupWithProviderQuota(rollup: UsageRollup, window: stri
  *  such lines; skips any malformed or non-`usage_snapshot` line. Never throws. */
 declare function readUsageSnapshots(sessionId: string, baseDir?: string): Promise<UsageSnapshotRecord[]>;
 
+/**
+ * Smart default for `features.llmEndpoint` (daemon-managed-gateway): an
+ * operator who already configured a named endpoint, an upstream credential
+ * link, or an explicit `llm-endpoint` custom route is clearly USING the
+ * proxy already — booting with the sidecar off (today's default) would
+ * silently break their next `route:{gateway:"llm-endpoint"}` spawn on a
+ * fresh install. An operator who never touched any of that gets the
+ * unchanged, conservative default (off).
+ *
+ * An explicit `configured` value (`config.json`'s `features.llmEndpoint`,
+ * profile-overlaid) always wins, in either direction — this resolver only
+ * fills in the gap when the operator left the flag unset.
+ */
+/**
+ * Resolve the EFFECTIVE `features.llmEndpoint` flag. `configured` is the
+ * operator's merged config value (`undefined` when never set in either
+ * `config.json` or the active profile).
+ */
+declare function resolveEffectiveLlmEndpointFlag(configured: boolean | undefined): Promise<boolean>;
+
 /**
  * MCP tools that drive the pairing registry — the daemon's "let a client pair
  * with me over an untrusted rendezvous" surface (design: DESIGN §6).
@@ -8372,6 +11126,90 @@ interface RegisterPairingToolsOptions {
 }
 declare function registerPairingTools(server: McpServer, opts: RegisterPairingToolsOptions): void;
 
+/**
+ * Device registry — a read view over `PairingRegistry` (+, when wired,
+ * `HostRegistry`) that presents each pairing/host as a "device" (DEVICES-PLAN
+ * PR-A, hosts added PR-C). A paired CLIENT (today's `pair_offer`/`pair
+ * accept`) gets `role: "client"`; a registered HOST (`pair offer --host` +
+ * `devices add`, host-registry.ts) gets `role: "host"`.
+ *
+ * This is deliberately a thin computed view, not a second store: renaming
+ * and revoking a client device mutate the same `pairings.json`
+ * `PairingRegistry` already owns; a host device mutates the same
+ * `hosts.json` `HostRegistry` — so `pair_*`/`/pairings` and
+ * `device_*`/`/devices` are two surfaces over the same two sources of truth.
+ */
+
+type DeviceRole = "client" | "host";
+type DeviceKind = "browser" | "cli" | "daemon";
+interface Device {
+    fingerprint: string;
+    name: string;
+    role: DeviceRole;
+    kind: DeviceKind;
+    rendezvous: string;
+    createdAt: string;
+    lastSeen: string;
+    /** A channel (offer or reconnect) is served for this device right now
+     *  (client) or a `forwardHttp` call is in flight for it right now (host).
+     *  For a host this is NOT a live heartbeat — see host-registry.ts's
+     *  "Online tracking" — it only reflects actual recent/current traffic. */
+    online: boolean;
+    /** A pair/v1 pairing: listed and revocable, but can't connect until
+     *  re-paired — see `PairingRecord.legacy`. */
+    legacy?: true;
+    /** Set when this device's pairing/host record was granted under a
+     *  HOST-scoped offer (`agentproto pair offer --host`) — see
+     *  offer-url.ts's "Offer scope". Surfaced from either side of a pairing so
+     *  a user can see, from EITHER daemon, which of their pairings/hosts grant
+     *  host control. */
+    scope?: "host";
+}
+interface DeviceRegistry {
+    /** Every known device. Read-only. */
+    list(): Promise<Device[]>;
+    /** Rename a device (fingerprint or current name) to a new label. Tries the
+     *  pairing registry first, then the host registry. Returns false when
+     *  nothing matched. */
+    rename(idOrName: string, newName: string): Promise<boolean>;
+    /** Drop a device by fingerprint or name — same effect as `pair revoke` for
+     *  a client device, `devices revoke`-of-a-host for a host device. Tries
+     *  the pairing registry first, then the host registry. Returns false when
+     *  nothing matched. */
+    revoke(idOrName: string): Promise<boolean>;
+    /** Register a host from an offer URL (delegates to `HostRegistry.add`).
+     *  Rejects if no `HostRegistry` was wired into this device registry. */
+    add(offerUrl: string, name?: string): Promise<{
+        fingerprint: string;
+        name: string;
+        rendezvousUrl: string;
+    }>;
+}
+declare function createDeviceRegistry(pairing: PairingRegistry, hosts?: HostRegistry): DeviceRegistry;
+
+/**
+ * MCP tools over the device registry (DEVICES-PLAN PR-A/PR-C) — `device_list`
+ * / `device_rename` / `device_revoke` / `device_add`. A view on top of the
+ * same registries `pair_offer`/`pair_list`/`pair_revoke` (pairing-tools.ts)
+ * and host-registry.ts drive; those keep working unchanged. `device_revoke`
+ * has the exact effect of `pair_revoke` for a client device.
+ *
+ * `device_add` (PR-C) registers a HOST from a `--host`-scoped offer URL —
+ * see `HostRegistry.add`'s scope gate (host-registry.ts). It requires the
+ * gateway to have wired a `HostRegistry` into the `DeviceRegistry`; without
+ * one the call rejects with a clear message rather than a missing-tool error
+ * (this repo always wires one when `pairingRegistry` is wired, so that's
+ * only reachable via a deliberate host misconfiguration).
+ *
+ * Registered beside `pair_*` — same closure-rebind pattern; the registry
+ * singleton lives on the gateway.
+ */
+
+interface RegisterDeviceToolsOptions {
+    registry: DeviceRegistry;
+}
+declare function registerDeviceTools(server: McpServer, opts: RegisterDeviceToolsOptions): void;
+
 /**
  * Rate-limited failure logging for reconnect loops.
  *
@@ -9209,6 +12047,15 @@ interface SessionWaitResult {
      *  reported one. `"error"` means the adapter reported a failed turn.
      *  Same three-branch coverage as `empty`. */
     reason?: string;
+    /** The matched turn-end's captured error text — `SessionTurnEndEvent.error`
+     *  on the ring-replay/bus branches, `SessionDescriptor.lastTurnErrorMessage`
+     *  on the sync fast-path (no event object to read there). Present only
+     *  when `reason` is `"error"` AND the adapter emitted an in-band `error`
+     *  stream event during the turn. Same three-branch coverage as `empty`/
+     *  `reason` — this is the field a waiter (a supervisor session, `sessions
+     *  wait`, a webhook) needed to actually learn WHY a turn errored instead
+     *  of just that it did. */
+    error?: string;
 }
 /**
  * Block until one of the listed sessions fires a matching lifecycle event
@@ -9358,6 +12205,12 @@ interface CreateGatewayOptions {
      *  to an `enabled: false` summary. Also surfaced in `daemon_health` /
      *  `GET /health` so an operator can see the effective value. */
     resumeSessionsOnBoot?: boolean;
+    /** Opt-in continue-on-boot. Mirrors the `daemon.continueInterruptedOnBoot`
+     *  config knob; when true, the `continueInterruptedOnBoot()` handle method
+     *  runs the boot continue pass (see `continue-interrupted.ts`); when
+     *  false/omitted it short-circuits to an `enabled: false` summary. Surfaced
+     *  in `daemon_health` / `GET /health`. */
+    continueInterruptedOnBoot?: boolean;
     /** Idle agent-session reaper threshold in ms (PR-6). Mirrors the
      *  `daemon.idleReapAfterMs` config knob; the CLI resolves it (env >
      *  config > off) and passes it here. When positive, the gateway starts a
@@ -9558,6 +12411,16 @@ interface CreateGatewayOptions {
      * `worktree_gc` returns a clear "not enabled" error.
      */
     runWorktreeGc?: WorktreeGcRunner;
+    /**
+     * Optional branch-`gc` runner powering `branch_gc` (+ `POST /branches/gc`).
+     * Injected for the same reason as `runWorktreeGc`. Omitted → `branch_gc`
+     * returns a clear "not enabled" error.
+     */
+    runBranchGc?: BranchGcRunner;
+    /** Optional verdict recorder powering `branch_gc_verdict` (+ `POST /branches/gc/verdict`). */
+    recordBranchGcVerdict?: BranchGcVerdictRecorder;
+    /** Optional verdict reader powering `branch_gc_verdict_get`. */
+    readBranchGcVerdict?: BranchGcVerdictReader;
     /**
      * Optional best-effort exit-time reclaim of ONE policy-provisioned
      * (implicit) session's own worktree — powers `SessionDescriptor.
@@ -9601,12 +12464,41 @@ interface CreateGatewayOptions {
      * returns) so the injected `serve` can capture the finished gateway.
      */
     pairingRegistry?: PairingRegistry;
+    /**
+     * Optional HOST registry (see `createHostRegistry`, DEVICES-PLAN PR-C) —
+     * the reverse-pairing "client" half of pair/v2, living daemon-side. When
+     * wired alongside `pairingRegistry`, the gateway layers registered hosts
+     * into `device_list`/`GET /devices`, and enables the `device_add` MCP tool
+     * plus `POST /devices/add` + `POST /devices/:id/exec`. Unlike
+     * `pairingRegistry`, this registry keeps no standing connections — every
+     * `add`/`forwardHttp` dials fresh — so there is nothing for the gateway to
+     * autoconnect or tear down on shutdown.
+     */
+    hostRegistry?: HostRegistry;
     /** Enable the local LLM Endpoint proxy sidecar (route registration,
      *  MCP tools, child-process lifecycle). Default false — the endpoint is
      *  an opt-in feature; when off, the `llm-endpoint` custom route is not
      *  registered and the `llm_endpoint_*` MCP tools are not exposed. */
     llmEndpoint?: boolean;
 }
+/**
+ * Default always-on set when `deferredTools` is enabled without an
+ * explicit `alwaysOn` override: the core spawn/drive/observe/report loop
+ * most sessions need immediately — including an EXECUTOR (the role
+ * `deferredTools` defaults on for, see `role.ts`), which cannot spawn
+ * (`agent_start`/`agent_prompt` are stripped for it anyway by
+ * `toolPolicy.delegation: "deny"`, so those two names are simply absent
+ * from a deny-role's registry and cost nothing) but still needs to report
+ * back to its parent (`message_parent`), coordinate over the task ledger
+ * (`task_*`), and observe its own session/turn state
+ * (`session_context_status` alongside the pre-existing `session_list` /
+ * `session_monitor` / `session_events_poll`). Everything else (fs_*,
+ * directory_*, command_*, remote_*, browser_*, terminal_*, mcp_*,
+ * routine_*, workflow_*, policy_*, inbound_watcher_*, session_tree,
+ * agent_export, adapter_list, every `app_ui_*` panel tool, ...) starts
+ * deferred — reachable via `tool_search`, never removed from `tools/call`.
+ */
+declare const DEFAULT_ALWAYS_ON_TOOLS: readonly string[];
 interface GatewayHandle {
     url: string;
     workspace: string;
@@ -9624,6 +12516,10 @@ interface GatewayHandle {
      *  `CreateGatewayOptions.pairingRegistry`. Undefined otherwise. Exposed so
      *  the CLI can `startAutoconnect()` after boot and `shutdown()` it. */
     pairing?: PairingRegistry;
+    /** HOST registry, when one was wired via `CreateGatewayOptions.hostRegistry`
+     *  (DEVICES-PLAN PR-C). Undefined otherwise. No autoconnect/shutdown to
+     *  call on it — see that option's doc comment. */
+    hosts?: HostRegistry;
     /** Per-boot bearer token required on mutating /sessions/* routes
      *  + WS PTY upgrades. Exposed so an embedding host (e.g. the CLI
      *  shell that hosts the gateway in-process) can pass it to child
@@ -9648,6 +12544,16 @@ interface GatewayHandle {
     resumeSessionsOnBoot(opts?: {
         isServed?: (desc: SessionDescriptor) => boolean;
     }): Promise<EagerResumeSummary>;
+    /** Run the opt-in continue-on-boot pass and return its tally — a no-op
+     *  returning `{ enabled: false, ... }` when the `continueInterruptedOnBoot`
+     *  knob is off. serve.ts invokes this right AFTER `resumeSessionsOnBoot()`
+     *  (so a row whose eager resume failed is recognisable and skipped) — and
+     *  therefore, like it, after the supervisor was re-armed, so a re-armed
+     *  completion policy sees the continue turn's turn-end. Same `isServed`
+     *  cross-process gate. */
+    continueInterruptedOnBoot(opts?: {
+        isServed?: (desc: SessionDescriptor) => boolean;
+    }): Promise<ContinueOnBootSummary>;
     stop(): Promise<void>;
 }
 /**
@@ -9664,4 +12570,4 @@ interface GatewayHandle {
  */
 declare function createGateway(opts: CreateGatewayOptions): Promise<GatewayHandle>;
 
-export { type ActivityKind, type ActivityListFilter, type ActivityPolicyLister, type ActivityProjector, type ActivityProjectorRegistry, type ActivityProjectorSession, type ActivityRecord, type ActivitySource, type ActivityState, type ActivityWaitingOn, type ActivityWorkflowLister, AdapterAuthDescriptor, type AdapterCapabilitiesLister, type AdapterInstallResult, type AdapterListEntry, type AgentAdapterInstaller, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type AnthropicReaderConfig, AnthropicRemainingQuotaReader, type AttachPolicyInput, type AttachSandboxOpts, type AttachSandboxResult, AuthMethod, BUCKETS_ROOT, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, CanonicalPosture, type CatalogModelsLister, CatalogModelsQuery, CatalogModelsResponse, type CatalogProviderModel, type CatalogProviderModelsQuery, type CatalogProviderModelsResponse, type CatalogProviderPricing, type ClaudeNativeRef, type CommitSpec, type CompletionPolicySupervisor, ContextProfile, type ConversationIndexRecord, type ConversationNativeRef, type CostBudgetDecision, type CrashDetectSummary, type CrashReaperRegistry, type CreateGatewayOptions, type CreateOfferInput, type CreatedOffer, DEAD_SESSION_STATUSES, DEFAULT_BUCKET, DEFAULT_ORCHESTRATOR_TOOLS, DEFAULT_WORKTREE_ISOLATION, DeclaredAdapterOption, type DeclaredAdapterPreset, type EagerResumeFailReason, type EagerResumeOutcome, type EagerResumeSkipReason, type EagerResumeSummary, EffortLevel, GC_REAPABLE_STATES, type GateSpec, type GatewayHandle, type HarnessPreset, type HarnessPresetValidationDeps, HarnessPresetValidationError, type HarnessPresetsFile, type HermesNativeRef, INBOUND_PROVIDERS, type IdleReapSummary, type IdleReaperRegistry, type InboundEndpoint, type InboundEndpointStore, type InboundEndpointStoreOptions, type InboundEnqueuePrompt, type InboundIsSessionAlive, type InboundMessage, type InboundProvider, type InboundRestartSession, type InboundRouteMode, type InboundRouterDeps, type InboundRouterLog, type InboundSpawnForContact, type InboundWatcher, type JudgeGateSpec, LEGACY_SESSIONS_FILE, type LocatedConversation, type LocatedConversationByPath, type McpCredentialDeps, type MigrationMarker, type NormalizeInboundResult, type OnFailSpec, type OpenPrResolver, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, type OrphanReaperRegistry, PAIRINGS_VERSION, POSTURE_NATIVE_ALIASES, POSTURE_PREAMBLES, type PairingChannelContext, type PairingChannelHandle, type PairingChannelMode, type PairingRecord, type PairingRegistry, type PairingRegistryDeps, type PendingPermission, type PermissionRespondInput, type PermissionRespondResult, type PolicyRunState, type PolicyRunStatus, Posture, type PostureResolution, type PrResolvedState, type PrStateResolver, type PresetInfo, type PricingResolver, type QuotaReadableProfile, type QuotaStoreFile, type QuotaStoreOptions, type ReconnectLogGate, type RegisterBrainToolsOptions, type RegisterBrowserInput, type RegisterPairingToolsOptions, type RegisterSessionInput, type RegisterWebSearchToolsOptions, type RemainingQuota, type RemainingQuotaReader, type ResolveNativeLinkInput, ResolvedAuthSpec, ResumeDisabledError, type ReuseResolution, type RouteAwareLaunchConfig, type RouteAwareLaunchConfigInput, RouteSpec, type RuntimeMeta, SESSION_ID_ENV, type SandboxAdapterInfo, type SandboxConnectionDescriptor, type SandboxGcCandidate, type SandboxGcProviderHandle, type SandboxGcReapDeps, type SandboxGcReapResult, type SandboxLedgerEntry, type SandboxLedgerState, type SandboxProviderCapabilities, type SandboxProviderHandle, type SandboxProviderLister, type SandboxProviderResolver, type ScopeTokenRegistry, SessionConfig, type SessionCurrentPhase, type SessionDescriptor, type SessionKind, type SessionObserver, type SessionSnapshots, type SessionStatus, type SessionUsage, type SessionWaitEvent, type SessionWaitResult, type SessionsRegistry, type ShellGateSpec, type SpawnAgentInput, type SpawnSessionInput, type StallWatchdogRegistry, type StallWatchdogSummary, type StoredProfileQuota, TASK_STATUSES, type TaskCaller, type TaskChangedEvent, type TaskClaimInput, type TaskCreateInput, type TaskGateOutcome, type TaskGateRunner, type TaskLedger, type TaskLedgerRegistry, type TaskLedgerSessionSlice, type TaskListFilter, type TaskRecord, type TaskStatus, type TaskUpdateInput, type TaskVerification, type TaskVerifySupervisor, type TaskWriteResult, type TokenPricing, type TransmitterBinding, type TransmitterBindingStore, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type UsageBucket, type UsageComputeInput, type UsageRollup, type UsageSnapshotRecord, type UsageSource, WORKSPACE_SLUG_ENV, WORKTREE_ISOLATION_ENV, type WatcherDescriptor, type WatcherStartInput, type WebSearchInput, type WebSearchOutput, type WebSearchResult, type WorkspaceBrainSubscriber, type WorkspaceBrainSubscriberOptions, type WorkspaceBrains, WorkspaceFs, type WorktreeAutoReclaimer, type WorktreeDecision, type WorktreeField, type WorktreeGcClass, type WorktreeGcOutcomeView, type WorktreeGcPlanEntryView, type WorktreeGcReclaimReason, type WorktreeGcResult, type WorktreeGcRunInput, type WorktreeGcRunner, WorktreeIsolationMode, type WorktreeProvisionOutcome, type WorktreeProvisionRequest, type WorktreeProvisioner, type WorktreeRequest, type WorktreeStatusLister, type WorktreeStatusView, activityCounts, addHarnessPreset, appendConversationRecord, attachSandbox, bucketDir, bucketSessionsFile, bucketTranscriptDir, buildCatalogProviderModels, buildMcpConfigSnippet, buildRouteAwareLaunchConfig, canonicalForModeId, claudeProjectSlug, collectGcCandidates, composeSessionObservers, conversationIndexPath, createActivityProjector, createFileStepCache, createGateway, createInboundEndpointStore, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createPrProvenanceReconciler, createReconnectLogGate, createScopeTokenRegistry, createSupervisorTaskGateRunner, createTaskLedger, createWorkspaceBrainSubscriber, createWorkspaceBrains, daemonRegistryDir, decideWorktreeIsolation, declaredPresetToProviderPreset, defineBraveSearchHttpDriver, defineSerperHttpDriver, deriveSessionUsage, enrichRollupWithProviderQuota, enrichWithRemainingQuota, evaluateCostBudget, filterActivities, findConversationRecord, findNativeMode, formatToolCall, formatToolResult, getDefaultHarnessPreset, getHarnessPreset, getMcpCredentialDeps, harnessPresetsPath, isAgentCliAuthConfigured, isClosedTaskStatus, isSafeBucketSlug, isTerminalActivityState, listBuckets, listHarnessPresets, listPresets, loadHarnessPresets, loadQuotaStore, loadWorktreeIsolation, locateConversationByNativePath, locateConversationBySessionId, makeBrowserAdapterLister, makeSandboxCredsStore, makeSandboxResolver, migrateLegacySessionsFile, migrationMarkerPath, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, normalizeInbound, normalizeModeId, normalizeWorktreeField, parseAnthropicRateLimitHeaders, parseTaskStatus, parseWindow, parseWorktreeIsolationMode, policyToActivities, policyWatchesSession, prToActivities, projectSessionUsage, readConversationIndex, readDaemonRegistry, readProfileQuota, readRegisteredSlugs, readRuntimeMeta, readSandboxLedger, readSessionForBrain, readUsageSnapshots, reapGcEntry, reapOrphanedDescendants, recordProfileQuota, recordSandboxBoot, recordSandboxLiveness, recordSandboxOrigin, recordSandboxState, registerBrainTools, registerBuiltinRoutes, registerPairingTools, registerSandboxAttachTool, registerWebSearchTools, removeHarnessPreset, removeSandboxLedgerEntry, resolveBucketSlug, resolveNativeLink, resolvePosture, resolveReuseFromLedger, rollupUsage, runCrashDetectPass, runEagerResumePass, runIdleReapPass, runStallWatchdogPass, sandboxLedgerPath, setDefaultPreset, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, toWorktreeStatusView, turnToActivities, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, updateHarnessPreset, upsertSandboxLedger, verifyInboundSignature, webSearchTool, workflowToActivities, writeDaemonRegistryEntry };
+export { type ActivityKind, type ActivityListFilter, type ActivityPolicyLister, type ActivityProjector, type ActivityProjectorRegistry, type ActivityProjectorSession, type ActivityRecord, type ActivitySource, type ActivityState, type ActivityWaitingOn, type ActivityWorkflowLister, AdapterAuthDescriptor, type AdapterCapabilitiesLister, type AdapterInstallResult, type AdapterListEntry, type AgentAdapterInstaller, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type AnthropicReaderConfig, AnthropicRemainingQuotaReader, type AttachPolicyInput, type AttachSandboxOpts, type AttachSandboxResult, AuthMethod, BUCKETS_ROOT, type BranchGcClass, type BranchGcCoverageView, type BranchGcHoldReason, type BranchGcKind, type BranchGcOutcomeView, type BranchGcPlanEntryView, type BranchGcPlanView, type BranchGcReclaimReason, type BranchGcResult, type BranchGcRunInput, type BranchGcRunner, type BranchGcStatus, type BranchGcSummaryView, type BranchGcTriageVerdict, type BranchGcVerdictInput, type BranchGcVerdictLookupInput, type BranchGcVerdictReader, type BranchGcVerdictRecordView, type BranchGcVerdictRecorder, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, CONTINUE_PROMPT_SOURCE, CanonicalPosture, type CatalogModelsLister, CatalogModelsQuery, CatalogModelsResponse, type CatalogProviderModel, type CatalogProviderModelsQuery, type CatalogProviderModelsResponse, type CatalogProviderPricing, type ClaudeNativeRef, type CommitSpec, type CompletionPolicySupervisor, ContextProfile, type ContinueInterruptedMode, type ContinueInterruptedOutcome, type ContinueInterruptedResult, type ContinueInterruptedSkipReason, type ContinueOnBootSummary, type ConversationIndexRecord, type ConversationNativeRef, type CostBudgetDecision, type CrashDetectSummary, type CrashReaperRegistry, type CreateGatewayOptions, type CreateOfferInput, type CreateReviewRunnerOptions, type CreatedOffer, DEAD_SESSION_STATUSES, DEFAULT_ALWAYS_ON_TOOLS, DEFAULT_BUCKET, DEFAULT_CONTINUE_PROMPT, DEFAULT_ORCHESTRATOR_TOOLS, DEFAULT_WORKTREE_ISOLATION, type DaemonReviewerHostDeps, DeclaredAdapterOption, type DeclaredAdapterPreset, DefaultsAdapterAuthConfig, type Device, type DeviceKind, type DeviceRegistry, type DeviceRole, type EagerResumeFailReason, type EagerResumeOutcome, type EagerResumeSkipReason, type EagerResumeSummary, EffortLevel, type EnableInput, type EnableResult, type ForwardHttpRequest, type ForwardHttpResponse, GC_REAPABLE_STATES, type GateSpec, type GatewayHandle, type GhRunner, HOSTS_VERSION, type HarnessPreset, type HarnessPresetValidationDeps, HarnessPresetValidationError, type HarnessPresetsFile, type HermesNativeRef, type HostRecord, type HostRegistry, type HostRegistryDeps, INBOUND_PROVIDERS, type IdleReapSummary, type IdleReaperRegistry, type InboundEndpoint, type InboundEndpointStore, type InboundEndpointStoreOptions, type InboundEnqueuePrompt, type InboundIsSessionAlive, type InboundMessage, type InboundProvider, type InboundRestartSession, type InboundRouteMode, type InboundRouterDeps, type InboundRouterLog, type InboundSpawnForContact, type InboundWatcher, type JudgeGateSpec, LEGACY_SESSIONS_FILE, type LedgerAnnotations, type LedgerEntry, type LedgerHostMeta, type LlmEndpointDescriptor, type LlmEndpointStatus, type LlmEndpointStatusReport, type LocatedConversation, type LocatedConversationByPath, MAX_AUTO_CONTINUE_ATTEMPTS, MAX_MESSAGE_DATA_BYTES, MCP_APP_BRIDGE_SCRIPT, MESSAGE_KINDS, MESSAGE_PREAMBLE, MESSAGE_TAG, MESSAGE_URGENCIES, type McpCredentialDeps, type MeasurableTool, type MeasuredToolEntry, type MessageDeliveryVia, type MessageFilter, type MessageKind, type MessageRelation, type MessageTreeNode, type MessageUrgency, type MigrationMarker, type NormalizeInboundResult, type OnFailSpec, type OpenPrResolver, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, type OrphanReaperRegistry, PAIRINGS_VERSION, POSTURE_NATIVE_ALIASES, POSTURE_PREAMBLES, type PairingChannelContext, type PairingChannelHandle, type PairingChannelMode, type PairingRecord, type PairingRegistry, type PairingRegistryDeps, type PendingPermission, type PermissionRespondInput, type PermissionRespondResult, type PolicyRunState, type PolicyRunStatus, Posture, type PostureResolution, PrLookupError, type PrLookupErrorCode, type PrResolvedState, type PrStateResolver, type PrStatusSnapshot, type PresetInfo, type PricingResolver, type QuotaReadableProfile, type QuotaStoreFile, type QuotaStoreOptions, type ReconnectLogGate, type RegisterBrainToolsOptions, type RegisterBrowserInput, type RegisterDeviceToolsOptions, type RegisterPairingToolsOptions, type RegisterReviewToolsOptions, type RegisterSessionInput, type RegisterWebSearchToolsOptions, type RemainingQuota, type RemainingQuotaReader, type RemoteStatus, type ResolveNativeLinkInput, ResolvedAuthSpec, ResumeDisabledError, type ReuseResolution, type ReviewLedger, type ReviewLedgerFilter, type ReviewRun, type ReviewRunInput, type ReviewRunStatus, type ReviewRunner, type ReviewerRunResult, type ReviewerSessionHost, type RouteAwareLaunchConfig, type RouteAwareLaunchConfigInput, RouteSpec, type RuntimeMeta, SESSION_END_REASONS, SESSION_ID_ENV, type SandboxAdapterInfo, type SandboxConnectionDescriptor, type SandboxGcCandidate, type SandboxGcProviderHandle, type SandboxGcReapDeps, type SandboxGcReapResult, type SandboxLedgerEntry, type SandboxLedgerState, type SandboxProviderCapabilities, type SandboxProviderHandle, type SandboxProviderLister, type SandboxProviderResolver, type SandboxReconcileDeps, type SandboxReconcileProviderHandle, type SandboxReconcileResult, type SandboxReconcileRow, type SandboxReconcileVerdict, type ScopeTokenRegistry, SessionConfig, type SessionCurrentPhase, type SessionDescriptor, type SessionEndReason, type SessionKind, type SessionMessage, type SessionMessageFrom, type SessionMessageSentRecord, type SessionObserver, type SessionOutcome, type SessionOutcomeArtifact, type SessionOutcomeCompact, type SessionOutcomeLink, type SessionSnapshots, type SessionStatus, type SessionUsage, type SessionUsageWithSubtree, type SessionWaitEvent, type SessionWaitResult, type SessionsRegistry, type ShellGateSpec, type SpawnAgentInput, SpawnDefaultsConfig, type SpawnSessionInput, type StallWatchdogRegistry, type StallWatchdogSummary, type StoredProfileQuota, type SubtreeChildUsage, type SubtreeUsageTotals, TASK_STATUSES, type TaskCaller, type TaskChangedEvent, type TaskClaimInput, type TaskCreateInput, type TaskGateOutcome, type TaskGateRunner, type TaskLedger, type TaskLedgerRegistry, type TaskLedgerSessionSlice, type TaskListFilter, type TaskRecord, type TaskStatus, type TaskUpdateInput, type TaskVerification, type TaskVerifySupervisor, type TaskWriteResult, type TokenPricing, type ToolListMeasurement, type TransmitterBinding, type TransmitterBindingStore, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type UsageBucket, type UsageComputeInput, type UsageDetail, type UsageReadContext, type UsageReadResult, type UsageRollup, type UsageSnapshotRecord, type UsageSource, UserPreset, WORKSPACE_SLUG_ENV, WORKTREE_ISOLATION_ENV, type WatcherDescriptor, type WatcherStartInput, type WebSearchInput, type WebSearchOutput, type WebSearchResult, type WorkspaceBrainSubscriber, type WorkspaceBrainSubscriberOptions, type WorkspaceBrains, WorkspaceFs, type WorktreeAutoReclaimer, type WorktreeDecision, type WorktreeField, type WorktreeGcClass, type WorktreeGcOutcomeView, type WorktreeGcPlanEntryView, type WorktreeGcReclaimReason, type WorktreeGcResult, type WorktreeGcRunInput, type WorktreeGcRunner, WorktreeIsolationMode, type WorktreeProvisionOutcome, type WorktreeProvisionRequest, type WorktreeProvisioner, type WorktreeRequest, type WorktreeStatusLister, type WorktreeStatusView, activityCounts, addHarnessPreset, appendConversationRecord, attachSandbox, bucketDir, bucketSessionsFile, bucketTranscriptDir, buildCatalogProviderModels, buildMcpConfigSnippet, buildRouteAwareLaunchConfig, canonicalForModeId, claudeProjectSlug, collectGcCandidates, compactOutcome, composeSessionObservers, continueInterruptedSessions, continueSkipReason, conversationIndexPath, createActivityProjector, createDaemonReviewerHost, createDeviceRegistry, createFileStepCache, createGateway, createHostRegistry, createInboundEndpointStore, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createPrProvenanceReconciler, createReconnectLogGate, createReviewLaneExecutor, createReviewLedger, createReviewRunner, createScopeTokenRegistry, createSessionMessage, createSupervisorTaskGateRunner, createTaskLedger, createWorkspaceBrainSubscriber, createWorkspaceBrains, daemonRegistryDir, decideWorktreeIsolation, declaredPresetToProviderPreset, defaultReviewLedgerRoot, defineBraveSearchHttpDriver, defineSerperHttpDriver, deriveSessionOutcome, deriveSessionUsage, enrichRollupWithProviderQuota, enrichWithRemainingQuota, escapeHumanPrompt, escapeMessageBody, evaluateCostBudget, execGh, extractHelpSection, fetchPrStatus, filterActivities, findConversationRecord, findNativeMode, findPrForCommit, formatToolCall, formatToolResult, getDefaultHarnessPreset, getHarnessPreset, getMcpCredentialDeps, getToolHelp, githubRepoOf, harnessPresetsPath, hostPlaceholders, injectMcpAppBridge, isAgentCliAuthConfigured, isClosedTaskStatus, isKnownSessionEndReason, isMessageAllowed, isProviderLimitError, isSafeBucketSlug, isTerminalActivityState, listBuckets, listHarnessPresets, listPresets, listToolHelpTopics, loadHarnessPresets, loadQuotaStore, loadWorktreeIsolation, locateConversationByNativePath, locateConversationBySessionId, makeBrowserAdapterLister, makeSandboxCredsStore, makeSandboxResolver, matchesMessageFilter, measureTool, measureToolList, messageFrom, migrateLegacySessionsFile, migrationMarkerPath, mintMessageId, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, normalizeInbound, normalizeModeId, normalizeRemote, normalizeWorktreeField, parseAnthropicRateLimitHeaders, parsePrUrl, parseTaskStatus, parseWindow, parseWorktreeIsolationMode, pickUsageDetail, policyToActivities, policyWatchesSession, prHeadSha, prToActivities, projectSessionUsage, readConversationIndex, readDaemonRegistry, readPairingsSnapshot, readProfileQuota, readRegisteredSlugs, readRuntimeMeta, readSandboxLedger, readSessionForBrain, readUsageSnapshots, reapGcEntry, reapOrphanedDescendants, reconcileSandboxLedger, recordProfileQuota, recordSandboxBoot, recordSandboxLiveness, recordSandboxOrigin, recordSandboxState, registerBrainTools, registerBuiltinRoutes, registerDeviceTools, registerPairingTools, registerReviewTools, registerSandboxAttachTool, registerWebSearchTools, removeHarnessPreset, removeSandboxLedgerEntry, renderInboxDigest, renderSessionMessage, renderSessionMessages, repoSlug, resolveBucketSlug, resolveEffectiveLlmEndpointFlag, resolveNativeLink, resolvePosture, resolveRelation, resolveReuseFromLedger, resolveReviewerPreset, rollupSessionSubtree, rollupUsage, runContinueOnBootPass, runCrashDetectPass, runEagerResumePass, runIdleReapPass, runShellLane, runStallWatchdogPass, sandboxLedgerPath, sanitizeLabel, setDefaultPreset, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, toWorktreeStatusView, turnToActivities, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, updateHarnessPreset, upsertSandboxLedger, verifyInboundSignature, webSearchTool, withPr, withPrStatus, workflowToActivities, writeDaemonRegistryEntry };