@agentproto/runtime 2.12.0 → 3.1.0

package/dist/index.d.ts

@@ -12,7 +12,7 @@ import { CostBudget, AuthProfile, CostBudgetScope } from '@agentproto/auth';
 export { CostBudget, CostBudgetScope } from '@agentproto/auth';
 import { R as ResolvedContextContinuityPolicy } from './context-continuity-ib9_bVYM.js';
 import { SandboxMode } from '@agentproto/command-sandbox';
-import { AdapterHandle, SetupField, AdapterResolver, AdapterLister, HarnessCapabilities, AdapterEntry } from '@agentproto/provider-kit';
+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-D4W661ui.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-D4W661ui.js';
 import { CatalogModelsQuery, CatalogModelsResponse } from './catalog-models.js';
@@ -22,6 +22,9 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SandboxProvider } 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 { ResolvedModel } from '@agentproto/model-catalog';
 import { FrameSink, E2eFrameSink } from '@agentproto/acp/tunnel';
@@ -722,10 +725,18 @@ interface ActivityPolicySlice {
     policyId: string;
     /** Representative session id (fan-in group[0]). */
     sessionId: string;
-    /** The full fan-in group being watched. */
-    sessionIds: readonly string[];
-    /** Group members that have NOT yet finished their turn. */
-    pending: readonly string[];
+    /**
+     * The full fan-in group being watched. OPTIONAL because supervisor state
+     * persisted before fan-in (WP6) predates this field — legacy rows on disk
+     * carry only `sessionId`, and the type must not lie about that.
+     */
+    sessionIds?: readonly string[];
+    /**
+     * Group members that have NOT yet finished their turn. OPTIONAL for the
+     * same reason as `sessionIds`: pre-fan-in persisted supervisor state omits
+     * it.
+     */
+    pending?: readonly string[];
     status: "watching" | "queued" | "gating" | "acting" | "nudging" | "awaiting-ack" | "done" | "blocked" | "cancelled";
     startedAt: string;
     endedAt?: string;
@@ -1684,7 +1695,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" | "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: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";
 /**
  * Fixed severity vocabulary for a judge-gate finding (WP-D). Deliberately
  * small and fixed so `policy_status` output is comparable across different
@@ -2343,6 +2354,31 @@ interface WorkflowApprovalResolvedEvent {
     note?: string;
     ts: string;
 }
+/**
+ * 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.
+ */
+interface WorkflowSuspendedEvent {
+    type: "workflow:suspended";
+    runId: string;
+    stepId: string;
+    on: readonly string[];
+    ts: string;
+}
+/**
+ * Emitted by the workflow runner when a parked `kind: "suspend"` step is
+ * resumed — live (the run continues) or after a daemon restart (the run's
+ * execution could not resume and it is marked failed with a clear reason).
+ */
+interface WorkflowSuspendResumedEvent {
+    type: "workflow:suspend-resumed";
+    runId: string;
+    stepId: string;
+    ts: string;
+}
 /**
  * Emitted when a `kind: "agent"` step's `harness` block declared a field the
  * spawn couldn't honor (today: `harness.tools` — no adapter exposes a
@@ -2357,7 +2393,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 | SessionHarnessWarningEvent;
+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;
 interface SessionEventBus {
     emit(ev: SessionEvent): void;
     /** Subscribe to a specific event type. Returns an unsubscribe fn. */
@@ -2368,6 +2404,45 @@ interface SessionEventBus {
     onAny(handler: (ev: SessionEvent) => void): () => void;
 }
 
+/**
+ * Runtime-side glue for the per-workspace brain: a shared registry of
+ * {@link BrainManager}s (one per workspace bucket) plus the two bridges that
+ * connect the pure `@agentproto/workspace-brain` engine to this daemon's real
+ * conversation stores:
+ *
+ *   - `readSessionForBrain` — a session id → exported transcript, via the same
+ *     ladder as `conversation-read.ts`: the provider-native store first
+ *     (`CONVERSATION_STORES`), then the universal `events.jsonl` capture
+ *     (`exportDaemonEventsSession`). `null` when neither has anything.
+ *   - `resolveWorkspace` — a session id → the workspace bucket it was recorded
+ *     under (via the persisted `conversations.jsonl` index).
+ *
+ * The registry itself is keyed by bucket slug and creates each `BrainManager`
+ * lazily, so a workspace that never produces a session pays nothing until its
+ * first exit does.
+ *
+ * A workspace's knowledge backends are configured per-workspace by a
+ * `knowledge.json` file at `<bucket>/knowledge.json` (see
+ * {@link loadKnowledgeConfigForWorkspace}). No file → the brain's default
+ * single `files` provider (identical to pre-config behavior); an invalid
+ * file → warn + fall back to that default; never throws either way.
+ */
+
+/** The shared registry handed to both the subscriber and the MCP tools. */
+interface WorkspaceBrains {
+    /** Get (creating lazily) the brain manager for a workspace bucket slug. */
+    getBrain(workspace: string): BrainManager;
+    /** Map a session id to the workspace bucket it was recorded under. */
+    resolveWorkspace(sessionId: string): Promise<string | undefined>;
+    /** Resolve an explicit workspace slug (or caller slug) to a safe bucket
+     *  slug — "default" when unregistered/absent (membership rule). */
+    resolveWorkspaceSlug(workspace?: string, callerSlug?: string): string;
+}
+/** Resolve a session id to its exported transcript, native first then daemon
+ *  events — `null` (never throws) when neither store has anything readable. */
+declare function readSessionForBrain(sessionId: string): Promise<ExportedSessionLike | null>;
+declare function createWorkspaceBrains(): WorkspaceBrains;
+
 /**
  * Shared types for pluggable tunnel providers.
  *
@@ -2759,6 +2834,23 @@ interface SandboxProviderHandle extends AdapterHandle {
     readonly setupFields?: readonly SetupField[];
 }
 
+/**
+ * Slug-keyed sandbox provider registry — the sandbox family's counterpart to
+ * `remote-providers/registry.ts`. `local` resolves in-process; everything
+ * else is a dynamic import of `@agentproto/sandbox-<slug>` (e.g.
+ * `@agentproto/sandbox-e2b`), wrapped with this registry's own capability/
+ * setup metadata because those packages export a bare `@agentproto/sandbox`
+ * `SandboxProvider` (just `boot()`) rather than a self-describing
+ * adapter-kit handle the way the tunnel family's third-party packages do.
+ *
+ * `modal` and `daytona` are catalog placeholders — AIP-36 day-1 provider
+ * ids with no published `@agentproto/sandbox-<slug>` package yet, so they
+ * always resolve to `null` (status "supported") until one ships.
+ */
+
+/** Per-slug credentials, as stored by the creds store / setup tool. */
+type SandboxCreds = Record<string, string>;
+
 /**
  * Sandbox family on top of `@agentproto/provider-kit` — mirrors
  * `tunnel-adapters.ts`. This module is the entire bridge between the
@@ -2802,6 +2894,21 @@ interface SandboxAdapterInfo {
 type SandboxProviderResolver = AdapterResolver<SandboxProviderHandle>;
 /** List every sandbox provider with its live status + capabilities. */
 type SandboxProviderLister = AdapterLister<SandboxAdapterInfo>;
+/** Build the sandbox-family creds store (per-slug, 0600). */
+declare function makeSandboxCredsStore(home?: string): CredsStore<SandboxCreds>;
+/**
+ * Resolve a catalog slug to a concrete handle via the provider registry —
+ * `local` in-process, `e2b`/`modal`/`daytona` dynamic-imported. Reads
+ * stored creds first so `e2b` (and any future catalog entry) resolves
+ * configured when possible; unconfigured slugs resolve to a descriptor-only
+ * handle (listing never calls `start()`/`check()`). Throws on an unknown
+ * slug so the kit's resolver wraps it to `null` ("supported but not
+ * installed").
+ */
+declare function makeSandboxResolver(credsStore: CredsStore<SandboxCreds>, opts?: {
+    /** Injectable for tests — defaults to a real dynamic `import()`. */
+    importPackage?: (packageName: string) => Promise<Record<string, unknown>>;
+}): SandboxProviderResolver;
 
 /**
  * Fire-and-forget webhook notifier for session lifecycle events.
@@ -4670,6 +4777,15 @@ interface SessionDescriptor {
      *  completed) turn. Reset when the next turn starts. Tool-call enrichment
      *  events sharing an id count only once. Ephemeral and never persisted. */
     toolCallsThisTurn?: number;
+    /** Absolute path of this session's durable structured transcript
+     *  (`events.jsonl`), resolved from the SAME base dir the transcript
+     *  writer actually writes to (`sessions.eventsDir` config > the
+     *  hardcoded `~/.agentproto/sessions`) — never re-derived by the
+     *  caller. Ephemeral, stamped at read time (list/get) and at spawn;
+     *  never persisted. Lets an external client (`agent_start`'s spawn
+     *  response, Claude desktop sandbox, wait loops) discover WHERE the
+     *  transcript lives without guessing. */
+    eventsPath?: string;
     /** Whether the underlying OS process is still alive. Computed via
      *  `process.kill(pid, 0)` at read time (list()/get()) — cheap,
      *  zero-overhead, standard POSIX check. Absent when `pid` is null
@@ -5537,6 +5653,12 @@ interface SessionSummary {
     sandboxPorts?: Record<number, string>;
     appServe?: SessionAppServeInfo;
 }
+/** Bracketed-paste mode as last observed in a PTY's OUTPUT stream.
+ *  `"unknown"` means neither `\x1b[?2004h` nor `\x1b[?2004l` has been seen
+ *  yet for this session — callers must treat unknown the same as "off"
+ *  (i.e. never wrap) to avoid a regression for sessions/shells that don't
+ *  use bracketed paste at all. */
+type BracketedPasteMode = "on" | "off" | "unknown";
 /**
  * Thrown by the lazy resume path when a resumable session has already failed to
  * resume `MAX_RESUME_ATTEMPTS` times in a row (`canResume` false on a row that
@@ -6187,6 +6309,11 @@ interface SessionsRegistry {
      *  Single-shot variant of attachPty().write — useful for MCP
      *  tools that drive a session through tool calls. */
     writeTerminalInput(id: string, data: string): boolean;
+    /** Last observed bracketed-paste mode for a PTY session, tracked from
+     *  the PTY's OUTPUT stream (see `scanBracketedPaste`). `"unknown"` for
+     *  a missing/non-PTY session or one that hasn't emitted either
+     *  `\x1b[?2004h`/`\x1b[?2004l` sequence yet. */
+    getBracketedPasteMode(id: string): BracketedPasteMode;
     /** Snapshot the recent PTY byte buffer as one Buffer. Newest
      *  bytes at the end; `lastBytes` caps the returned size from the
      *  tail. Returns null when the session is missing or not a PTY. */
@@ -6683,6 +6810,15 @@ interface RecordCommandInput {
     /** Id of the session that invoked this one, when the caller genuinely
      *  knows it — see `SessionDescriptor.callerSessionId`. */
     callerSessionId?: string;
+    /** Parent attribution + depth — same semantics as `SpawnPtyInput` /
+     *  `SpawnAgentInput` (orchestrator WP4): set when the command ran
+     *  through a scoped sub-gateway so `session_tree` shows the command
+     *  session under its invoker. */
+    parentSessionId?: string;
+    /** Recursion depth in the session tree — always recorded (`?? 0` when
+     *  absent) so subtree/depth logic never has to special-case a missing
+     *  value. Same semantics as `SpawnAgentInput.depth`. */
+    depth?: number;
 }
 /** A pull request that a session successfully opened through a code-host
  * driver. `openedAt` is assigned by the registry so callers cannot claim a
@@ -6699,27 +6835,6 @@ interface RecordOpenedPrInput {
     url: string;
 }
 
-/**
- * MCP tools that expose browser service adapters (Camofox, Bureau, …) to
- * agents connected to the daemon. Lets a remote operator start, stop, and
- * inspect browser service sessions through the same MCP connection it uses
- * for fs/exec/agent-cli.
- *
- * Five tools:
- *   browser_adapter_list   discover available browser adapter ids + metadata
- *   start_browser           ensure a browser adapter is up, register as a session
- *   stop_browser            kill a running browser session
- *   list_browsers           browse alive/recent browser sessions
- *   browser_status          descriptor + live health probe for one session
- *
- * Auth: same as every other daemon tool — gated by the gateway's auth source.
- *
- * Injection pattern: `resolveBrowserAdapter` is passed in, not imported.
- * This keeps the runtime package free of a hard dep on @agentproto/adapter-browser.
- * The types below are minimal structural shapes — equivalent to `AgentSessionLike`
- * in sessions.ts.
- */
-
 /**
  * Minimal shape of a BrowserAdapterInstance — structurally compatible with
  * @agentproto/adapter-browser's BrowserAdapterInstance. Kept local so the
@@ -7064,45 +7179,6 @@ interface InboundWatcher {
     shutdown(): void;
 }
 
-/**
- * Runtime-side glue for the per-workspace brain: a shared registry of
- * {@link BrainManager}s (one per workspace bucket) plus the two bridges that
- * connect the pure `@agentproto/workspace-brain` engine to this daemon's real
- * conversation stores:
- *
- *   - `readSessionForBrain` — a session id → exported transcript, via the same
- *     ladder as `conversation-read.ts`: the provider-native store first
- *     (`CONVERSATION_STORES`), then the universal `events.jsonl` capture
- *     (`exportDaemonEventsSession`). `null` when neither has anything.
- *   - `resolveWorkspace` — a session id → the workspace bucket it was recorded
- *     under (via the persisted `conversations.jsonl` index).
- *
- * The registry itself is keyed by bucket slug and creates each `BrainManager`
- * lazily, so a workspace that never produces a session pays nothing until its
- * first exit does.
- *
- * A workspace's knowledge backends are configured per-workspace by a
- * `knowledge.json` file at `<bucket>/knowledge.json` (see
- * {@link loadKnowledgeConfigForWorkspace}). No file → the brain's default
- * single `files` provider (identical to pre-config behavior); an invalid
- * file → warn + fall back to that default; never throws either way.
- */
-
-/** The shared registry handed to both the subscriber and the MCP tools. */
-interface WorkspaceBrains {
-    /** Get (creating lazily) the brain manager for a workspace bucket slug. */
-    getBrain(workspace: string): BrainManager;
-    /** Map a session id to the workspace bucket it was recorded under. */
-    resolveWorkspace(sessionId: string): Promise<string | undefined>;
-    /** Resolve an explicit workspace slug (or caller slug) to a safe bucket
-     *  slug — "default" when unregistered/absent (membership rule). */
-    resolveWorkspaceSlug(workspace?: string, callerSlug?: string): string;
-}
-/** Resolve a session id to its exported transcript, native first then daemon
- *  events — `null` (never throws) when neither store has anything readable. */
-declare function readSessionForBrain(sessionId: string): Promise<ExportedSessionLike | null>;
-declare function createWorkspaceBrains(): WorkspaceBrains;
-
 /**
  * MCP tools that expose the per-workspace brain to agents.
  *
@@ -7131,6 +7207,69 @@ interface RegisterBrainToolsOptions {
 }
 declare function registerBrainTools(server: McpServer, opts: RegisterBrainToolsOptions): void;
 
+declare const webSearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    count: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    country: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    freshness: z.ZodOptional<z.ZodEnum<{
+        pd: "pd";
+        pw: "pw";
+        pm: "pm";
+        py: "py";
+    }>>;
+    safesearch: z.ZodOptional<z.ZodEnum<{
+        off: "off";
+        strict: "strict";
+        moderate: "moderate";
+    }>>;
+}, z.core.$strip>;
+type WebSearchInput = z.infer<typeof webSearchInputSchema>;
+declare const webSearchOutputSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        brave: "brave";
+        serper: "serper";
+    }>;
+    results: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        url: z.ZodString;
+        snippet: z.ZodOptional<z.ZodString>;
+        position: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type WebSearchOutput = z.infer<typeof webSearchOutputSchema>;
+type WebSearchResult = WebSearchOutput["results"][number];
+declare const webSearchTool: _agentproto_tool.ToolHandle<{
+    query: string;
+    count: number;
+    country?: string | undefined;
+    language?: string | undefined;
+    freshness?: "pd" | "pw" | "pm" | "py" | undefined;
+    safesearch?: "off" | "strict" | "moderate" | undefined;
+}, {
+    provider: "brave" | "serper";
+    results: {
+        title: string;
+        url: string;
+        position: number;
+        snippet?: string | undefined;
+    }[];
+}, ToolContext>;
+declare function defineBraveSearchHttpDriver(): DriverHandle;
+declare function defineSerperHttpDriver(): DriverHandle;
+interface RegisterWebSearchToolsOptions {
+    /** Injectable env (tests); default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable fetch (tests / live e2e); default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Register the `web.search` MCP tool (`web_search`) when at least one
+ * provider key is configured. With NEITHER key present, nothing is
+ * registered — no broken tool is advertised, silently.
+ */
+declare function registerWebSearchTools(server: McpServer, opts?: RegisterWebSearchToolsOptions): void;
+
 /**
  * Workshop-brain subscriber — auto-ingest a workspace's conversations when its
  * sessions exit.
@@ -7544,6 +7683,88 @@ interface RegisterSandboxAttachToolOptions {
 /** Register the `sandbox_attach` MCP tool. */
 declare function registerSandboxAttachTool(server: McpServer, opts?: RegisterSandboxAttachToolOptions): void;
 
+/**
+ * The sandbox ledger — `~/.agentproto/sandboxes.json`.
+ *
+ * The daemon KNOWS when it boots, pauses, reconnects to, or stops a sandbox
+ * box (AIP-36 boot-and-drive, `session-spawn.ts`'s `bootSandboxAgentSession`
+ * and the lifecycle teardown inside `SandboxAgentSessionProxy.close()`), but
+ * it writes none of it down: finding a still-live sandboxId meant grepping
+ * session descriptors for a `remote: true` stamp. This module is the
+ * navigation half — one durable record per sandboxId:
+ *
+ *   { sandboxId, provider, label?, state, cwd?, originSessionId?,
+ *     createdAt, updatedAt, expiresAt? }
+ *
+ * State machine: "booted" (fresh boot) → "connected" (reuse/attach) →
+ * "paused" (proxy close() chose the pause teardown) | "stopped" (kill or
+ * expiry). `expiresAt` is stamped at boot when the spec's lifecycle policy
+ * carries a known idle window (`lifecycle.pause_after_idle` →
+ * `SandboxLifecyclePolicy.pauseAfterIdleMs`) — the one expiry the daemon
+ * actually knows about at boot time; a provider-side TTL the daemon never
+ * sees is deliberately NOT guessed at here.
+ *
+ * Writes are ALWAYS best-effort: every helper swallows its own failures and
+ * returns without throwing. A ledger error must never fail a spawn, a
+ * pause, or a teardown — the ledger is an index over reality, never a
+ * participant in it.
+ *
+ * Persistence style matches the daemon's other JSON stores
+ * (`workspace-buckets.ts`, `saveWorkspacesConfig`): serialize → write to a
+ * per-process-unique tmp file → rename over the target. A concurrent reader
+ * never sees half a JSON object, and two in-flight writers never share a
+ * tmp path (the pid-only suffix is not unique within one process — see the
+ * 2026-08-14 registry-wipe write-up in `workspace-buckets.ts`).
+ */
+/** Lifecycle states a ledger row can carry. */
+type SandboxLedgerState = "booted" | "paused" | "connected" | "stopped";
+interface SandboxLedgerEntry {
+    sandboxId: string;
+    provider: string;
+    state: SandboxLedgerState;
+    createdAt: string;
+    updatedAt: string;
+    label?: string;
+    cwd?: string;
+    /** The HOST session id that first booted / last reconnected to the box. */
+    originSessionId?: string;
+    /** ISO instant the box is expected to idle-expire — stamped only when the
+     *  boot knew a window (`lifecycle.pause_after_idle`). */
+    expiresAt?: string;
+}
+/** `~/.agentproto/sandboxes.json`. `AGENTPROTO_SANDBOX_LEDGER` overrides
+ *  the path (tests, and a caller that wants a workspace-scoped ledger). */
+declare const sandboxLedgerPath: () => string;
+/** Rows currently on disk. `[]` for a missing/corrupt file — the same
+ *  "degrade to nothing rather than throw" contract as every other store
+ *  reader in this daemon. Never throws. */
+declare function readSandboxLedger(path?: string): SandboxLedgerEntry[];
+/** Remove a row by sandboxId. Returns whether a row was actually dropped
+ *  (read from the PRE-call disk state). Never throws. */
+declare function removeSandboxLedgerEntry(sandboxId: string, path?: string): boolean;
+type ReuseResolution = {
+    kind: "resolved";
+    sandboxId: string;
+    entry: SandboxLedgerEntry;
+} | {
+    kind: "ambiguous";
+    candidates: SandboxLedgerEntry[];
+} | {
+    kind: "unresolved";
+};
+/**
+ * `reuse: "<label-or-id>"` resolution against the ledger (PLAN-D1 §3).
+ *
+ * A reuse token that exactly matches a row's `label`, or is a PREFIX of
+ * exactly one row's `sandboxId`, resolves to that row's sandboxId. Several
+ * matches → `ambiguous` (the caller must disambiguate — the error it
+ * renders lists the candidates). No match at all → `unresolved`, and the
+ * spawn path passes the token through unchanged so the provider's own
+ * `connect()` failure surfaces exactly as it did before this module
+ * existed.
+ */
+declare function resolveReuseFromLedger(reuse: string, entries: readonly SandboxLedgerEntry[]): ReuseResolution;
+
 /**
  * Idle agent-session reaper (PR-6).
  *
@@ -9221,4 +9442,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, DEFAULT_BUCKET, DEFAULT_ORCHESTRATOR_TOOLS, DEFAULT_WORKTREE_ISOLATION, DeclaredAdapterOption, type DeclaredAdapterPreset, type EagerResumeFailReason, type EagerResumeOutcome, type EagerResumeSkipReason, type EagerResumeSummary, EffortLevel, 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 RemainingQuota, type RemainingQuotaReader, type ResolveNativeLinkInput, ResolvedAuthSpec, ResumeDisabledError, type RouteAwareLaunchConfig, type RouteAwareLaunchConfigInput, RouteSpec, type RuntimeMeta, SESSION_ID_ENV, type SandboxAdapterInfo, type SandboxConnectionDescriptor, 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 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, composeSessionObservers, conversationIndexPath, createActivityProjector, createFileStepCache, createGateway, createInboundEndpointStore, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createPrProvenanceReconciler, createReconnectLogGate, createScopeTokenRegistry, createSupervisorTaskGateRunner, createTaskLedger, createWorkspaceBrainSubscriber, createWorkspaceBrains, daemonRegistryDir, decideWorktreeIsolation, declaredPresetToProviderPreset, 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, migrateLegacySessionsFile, migrationMarkerPath, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, normalizeInbound, normalizeModeId, normalizeWorktreeField, parseAnthropicRateLimitHeaders, parseTaskStatus, parseWindow, parseWorktreeIsolationMode, policyToActivities, policyWatchesSession, prToActivities, projectSessionUsage, readConversationIndex, readDaemonRegistry, readProfileQuota, readRegisteredSlugs, readRuntimeMeta, readSessionForBrain, readUsageSnapshots, reapOrphanedDescendants, recordProfileQuota, registerBrainTools, registerBuiltinRoutes, registerPairingTools, registerSandboxAttachTool, removeHarnessPreset, resolveBucketSlug, resolveNativeLink, resolvePosture, rollupUsage, runCrashDetectPass, runEagerResumePass, runIdleReapPass, runStallWatchdogPass, setDefaultPreset, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, toWorktreeStatusView, turnToActivities, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, updateHarnessPreset, verifyInboundSignature, 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 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, DEFAULT_BUCKET, DEFAULT_ORCHESTRATOR_TOOLS, DEFAULT_WORKTREE_ISOLATION, DeclaredAdapterOption, type DeclaredAdapterPreset, type EagerResumeFailReason, type EagerResumeOutcome, type EagerResumeSkipReason, type EagerResumeSummary, EffortLevel, 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 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, 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, reapOrphanedDescendants, recordProfileQuota, 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, verifyInboundSignature, webSearchTool, workflowToActivities, writeDaemonRegistryEntry };