@agentproto/runtime 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,10 +1,106 @@
 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 { AcpMcpServer } from '@agentproto/acp';
 import { ChildProcess } from 'node:child_process';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AdapterHandle, AdapterLister } from '@agentproto/adapter-kit';
 import { WorkspaceFs } from './workspace-fs.js';
 export { createWorkspaceFs } from './workspace-fs.js';
 export { ConversationMeta, ConversationStore, ConversationTurn, fileConversationStore } from './conversations.js';
+export { PROVIDER_ENV_VARS, ProviderEntry, ProvidersFile, injectProviderKeysIntoEnv, loadProviders, providerEnvVar, providersPath, removeProviderKey, setProviderKey } from './providers-store.js';
+
+/**
+ * In-process pub/sub bus for session lifecycle events. Separate from
+ * RuntimeEvents (global daemon bus) — session events are scoped to
+ * individual sessions and fire at turn-level granularity.
+ *
+ * Consumers: EventRing (poll_events cursor), WebhookNotifier
+ * (fire-and-forget HTTP), RoutineRunner (state machine fan-in),
+ * and wait_for_any MCP tool (long-poll multiplexed).
+ */
+type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:exited" | "session:command-done" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed";
+interface SessionTurnEndEvent {
+    type: "session:turn-end";
+    sessionId: string;
+    awaitingInput: boolean;
+    label?: string;
+    ts: string;
+}
+interface SessionAwaitingInputEvent {
+    type: "session:awaiting-input";
+    sessionId: string;
+    label?: string;
+    ts: string;
+}
+interface SessionExitedEvent {
+    type: "session:exited";
+    sessionId: string;
+    exitCode?: number;
+    status: "exited" | "killed" | "error";
+    label?: string;
+    ts: string;
+}
+/** Emitted when execute_command finishes. commandId matches the id
+ *  returned by the execute_command MCP tool. */
+interface SessionCommandDoneEvent {
+    type: "session:command-done";
+    sessionId: string;
+    commandId: string;
+    exitCode: number;
+    ts: string;
+}
+/** Emitted by the supervisor when a completion policy's gate passes. */
+interface PolicyPassedEvent {
+    type: "policy:passed";
+    policyId: string;
+    sessionId: string;
+    ts: string;
+}
+/** Emitted by the supervisor when a completion policy's gate fails. */
+interface PolicyFailedEvent {
+    type: "policy:failed";
+    policyId: string;
+    sessionId: string;
+    exitCode?: number;
+    ts: string;
+}
+/**
+ * Emitted by the supervisor (WP5) when a `then:"commit"` policy's gate passes
+ * but `requireHumanAck` is set: the commit is staged-and-ready but NOT yet
+ * executed. Carries the exact paths + message that `ack_policy(approve:true)`
+ * will commit. The policy sits in `awaiting-ack` until acked.
+ */
+interface PolicyCommitReadyEvent {
+    type: "policy:commit-ready";
+    policyId: string;
+    sessionId: string;
+    paths: string[];
+    message: string;
+    ts: string;
+}
+/** Emitted by the supervisor (WP5) when a `then:"commit"` policy has actually
+ *  committed — either directly (requireHumanAck:false) or after an approving
+ *  `ack_policy`. Carries the resulting commit sha. */
+interface PolicyCommittedEvent {
+    type: "policy:committed";
+    policyId: string;
+    sessionId: string;
+    sha: string;
+    paths: string[];
+    message: string;
+    ts: string;
+}
+type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionExitedEvent | SessionCommandDoneEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent;
+interface SessionEventBus {
+    emit(ev: SessionEvent): void;
+    /** Subscribe to a specific event type. Returns an unsubscribe fn. */
+    on<E extends SessionEventType>(type: E, handler: (ev: Extract<SessionEvent, {
+        type: E;
+    }>) => void): () => void;
+    /** Subscribe to all event types. Returns an unsubscribe fn. */
+    onAny(handler: (ev: SessionEvent) => void): () => void;
+}
 
 /**
  * Sessions registry — tracks long-lived child processes spawned by
@@ -78,7 +174,7 @@ interface AgentStreamEvent {
         data?: unknown;
     };
 }
-type SessionKind = "terminal" | "agent-cli" | "command";
+type SessionKind = "terminal" | "agent-cli" | "command" | "browser";
 type SessionStatus = "starting" | "running" | "exited" | "killed" | "error";
 interface SessionDescriptor {
     id: string;
@@ -117,12 +213,29 @@ interface SessionDescriptor {
      *  `/sessions/agent` to spin up a fresh ACP runtime. Undefined for
      *  pty/command kinds. */
     adapterSlug?: string;
+    /** The model the session was requested to run (echoed back at spawn). */
+    model?: string;
+    /** Cumulative estimated USD cost of the session — best-effort, refreshed
+     *  on each turn-end from the adapter's usage reader (e.g. hermes reads its
+     *  state.db). Absent for adapters with no usage source. */
+    costUsd?: number;
+    /** Cumulative input / output token counts (same source + cadence as costUsd). */
+    tokensIn?: number;
+    tokensOut?: number;
     /** ACP-level session id (the adapter's own handle — claude-code's
      *  conversation id, hermes' chat id, …). Set at spawnAgent time
      *  from `agentSession.sessionId`. Survives across daemon restarts
      *  via sessions.json so `restart` can pass it as `resumeSessionId`
      *  and reattach to the prior conversation history. */
     adapterSessionId?: string;
+    /** MCP servers mounted into the agent's session at spawn time
+     *  (orchestrator WP1). Persisted so the resume/re-spawn path can
+     *  re-mount the same host-chosen toolset instead of resuming a
+     *  capability-stripped agent. The current `AcpMcpServer` shape is
+     *  `{ name, transport, ref? }` — a reference, NOT inline credentials
+     *  — so this carries no secrets today. Should the shape ever grow
+     *  headers/tokens, NEVER log this field's contents. */
+    mcpServers?: AcpMcpServer[];
     /** Provider-specific resume hints sniffed from the session's
      *  output. claude-code prints `claude --resume <uuid>` on exit;
      *  we capture that uuid as `claudeResumeId`. On `restart`, when a
@@ -134,6 +247,43 @@ interface SessionDescriptor {
      *  Keys are adapter-specific so future adapters can add their own
      *  ("hermesResumeId", etc.) without changing this type. */
     resumeMetadata?: Record<string, string>;
+    /** Set by the orchestration layer when the agent emits an
+     *  "awaiting-input" turn-end. Cleared on the next turn start.
+     *  Used by `wait_for_any` to fast-return without subscribing. */
+    awaitingInput?: boolean;
+    /** Count of turns that have fully completed (turn-end emitted) on this
+     *  session. Lets `wait_for_any` fast-return for a session that already
+     *  finished its turn before the wait subscribed — a fast turn that ends
+     *  in "completed" (not "awaiting-input") leaves no other persisted
+     *  signal (status stays "running", busy clears). 0 = never ran a turn,
+     *  so a freshly-spawned idle session is NOT mistaken for done. */
+    turnsCompleted?: number;
+    /** True while a turn is actively running (mirror of the internal
+     *  runtime `busy` flag). Lets `wait_for_any` distinguish "idle after a
+     *  finished turn" from "mid-turn" so it doesn't fast-return a stale
+     *  turn-end while the NEXT turn is still generating. */
+    busy?: boolean;
+    /** Session id of the orchestrator that spawned this session, set when
+     *  the spawn arrived via the scoped orchestrator sub-gateway (the
+     *  token carried the spawner's identity). Absent for direct `/mcp`
+     *  spawns (the root operator). Powers the subtree scoping of
+     *  list/kill and the per-parent child quota (orchestrator WP4).
+     *  Persisted so the tree survives a daemon restart. */
+    parentSessionId?: string;
+    /** Recursion depth in the orchestrator tree: a direct (root) spawn is
+     *  depth 0; a session spawned by a depth-d orchestrator is d+1. Used
+     *  by the depth-cap guard. Persisted alongside `parentSessionId`.
+     *  Treated as 0 when absent (legacy rows / direct spawns that predate
+     *  WP4). */
+    depth?: number;
+    /** Adapter id that drives this session (e.g. "camofox", "bureau"). */
+    browserAdapterId?: string;
+    /** Port the browser service listens on. */
+    browserPort?: number;
+    /** Base URL of the browser service (e.g. "http://127.0.0.1:9377"). */
+    browserBaseUrl?: string;
+    /** Execution location — "local" (default) or "cloud". */
+    browserLocation?: "local" | "cloud";
 }
 interface SessionsRegistry {
     spawn(input: SpawnSessionInput): SessionDescriptor;
@@ -156,6 +306,11 @@ interface SessionsRegistry {
      *  `attachPty(id, ...)`. Throws when the registry was constructed
      *  without a `spawnPty` factory (node-pty optional dep missing). */
     spawnPty(input: SpawnPtyInput): SessionDescriptor;
+    /** Register an already-running browser service adapter as a tracked
+     *  session (kind="browser"). Idempotent by identity — each call
+     *  mints a fresh session id. The `stop` callback is invoked by
+     *  `kill()` best-effort. */
+    registerBrowser(input: RegisterBrowserInput): SessionDescriptor;
     /** Send a follow-up turn to a live agent session. Throws when the
      *  session is missing, not an agent-cli kind, or busy. The events
      *  stream into the existing ring buffer + line emitter so /stream
@@ -214,6 +369,30 @@ interface SessionsRegistry {
      *  awaited — the daemon shutdown loop handles process tree teardown. */
     shutdown(): void;
 }
+interface RegisterBrowserInput {
+    /** Adapter id (e.g. "camofox", "bureau", "chromium"). */
+    adapterId: string;
+    /** Port the browser service listens on. */
+    port: number;
+    /** Base URL of the browser service (e.g. "http://127.0.0.1:9377"). */
+    baseUrl: string;
+    /** Execution location — "local" (default) or "cloud". Included in the
+     *  dedup key so a cloud call never returns a pre-existing local session. */
+    location?: "local" | "cloud";
+    /** PID of the service process — undefined when managed by launchd/systemd. */
+    pid?: number;
+    /** True when the service was already healthy before this call (idempotent start). */
+    wasAlreadyRunning: boolean;
+    /** Initial lifecycle status. "running" when the service is confirmed
+     *  healthy; "starting" when a non-blocking cold start returned before the
+     *  service finished converging (health-wait continues in the background and
+     *  `browser_status` / `list_browsers` flip it to running once up).
+     *  Defaults to "running" when omitted. */
+    status?: Extract<SessionStatus, "running" | "starting">;
+    /** Async shutdown callback — called by kill() best-effort. */
+    stop: () => Promise<void>;
+    label?: string;
+}
 interface RegisterSessionInput {
     /** Pre-existing child process to adopt (e.g. from a tunnel spawn). */
     child: ChildProcess;
@@ -242,6 +421,33 @@ interface SpawnAgentInput {
     label?: string;
     /** Pretty command for the descriptor (display only). */
     commandPreview?: string;
+    /** MCP servers mounted at spawn time. Persisted on the descriptor so
+     *  the resume/re-spawn path can re-mount the same toolset (orchestrator
+     *  WP1). */
+    mcpServers?: AcpMcpServer[];
+    /** Spawning orchestrator's session id — set when the spawn arrived
+     *  through the scoped sub-gateway (orchestrator WP4). Recorded on the
+     *  descriptor for subtree scoping + quota accounting. */
+    parentSessionId?: string;
+    /** Recursion depth for the new session (orchestrator WP4). Defaults to
+     *  0 when omitted (direct/root spawn). */
+    depth?: number;
+    /** Requested model id — recorded on the descriptor for display + echo. */
+    model?: string;
+    /** Hard ceiling on cumulative session cost (USD). When set and the
+     *  adapter's usage reader reports a higher cost at a turn-end, the session
+     *  is stopped (best-effort, turn-granular — caps continuation, can't abort
+     *  a turn mid-flight). */
+    maxCostUsd?: number;
+    /** Best-effort usage reader, called on each turn-end to refresh the
+     *  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<{
+        costUsd?: number;
+        tokensIn?: number;
+        tokensOut?: number;
+    } | null>;
 }
 interface SpawnSessionInput {
     kind: SessionKind;
@@ -286,6 +492,833 @@ interface SpawnPtyInput {
     label?: 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:
+ *   list_adapter_browsers   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
+ * runtime package stays free of a hard dependency on the adapter package.
+ */
+interface BrowserInstanceLike {
+    id: string;
+    port: number;
+    baseUrl: string;
+    pid?: number;
+    wasAlreadyRunning: boolean;
+    /** False when a non-blocking cold start returned before the service
+     *  finished converging (background health-wait still running). */
+    healthy: boolean;
+    stop(): Promise<void>;
+}
+/**
+ * Minimal shape of a BrowserAdapterHandle — structurally compatible with
+ * @agentproto/adapter-browser's BrowserAdapterHandle.
+ */
+interface BrowserAdapterLike {
+    id: string;
+    name: string;
+    description: string;
+    defaultPort: number;
+    healthPath: string;
+    /** Where this adapter runs — "local" (default) or "cloud". */
+    location?: "local" | "cloud";
+    ensure(opts: {
+        port?: number;
+        /** forwarded to dependent adapters (e.g. bureau→camofox) */
+        camofoxPort?: number;
+        launchCmd?: string;
+        env?: Record<string, string>;
+        timeoutMs?: number;
+        /** Opt-in non-blocking cold start: wait only this long for a freshly
+         *  spawned service before returning `healthy:false` and converging
+         *  in the background. */
+        initialWaitMs?: number;
+        log?: (s: string) => void;
+        /** Override execution location ("local" or "cloud"). */
+        location?: "local" | "cloud";
+        /** Base URL of the remote service when location="cloud". */
+        baseUrl?: string;
+        /** Override the binary path for a local spawn. */
+        binPath?: string;
+    }): Promise<BrowserInstanceLike>;
+}
+type BrowserAdapterResolver = (id: string) => BrowserAdapterLike | undefined;
+type BrowserAdapterLister = () => {
+    id: string;
+    name: string;
+    description: string;
+    defaultPort: number;
+    /** Where this adapter runs — "local" (default) or "cloud". */
+    location?: "local" | "cloud";
+    /** Install methods — informational metadata from the adapter manifest. */
+    install?: unknown[];
+    /** Config prompts — informational metadata from the adapter manifest. */
+    config?: unknown[];
+}[];
+/**
+ * Family-specific descriptor surfaced in the kit-path `list_adapter_browsers`
+ * response. Fields match the legacy lister shape so the tool output is
+ * unchanged regardless of which path is active.
+ */
+interface BrowserAdapterInfo {
+    id: string;
+    name: string;
+    description: string;
+    defaultPort: number;
+}
+
+/**
+ * Shared types for pluggable tunnel providers.
+ *
+ * Extracted here so both `RemoteController` (single-gateway tunnel) and
+ * `TunnelRegistry` (multi-tunnel general surface) can share the same
+ * provider contract without creating a circular dep.
+ *
+ * The tunnel family is the FIRST consumer of `@agentproto/adapter-kit`:
+ * {@link TunnelProviderHandle} extends the kit's generic `AdapterHandle`
+ * (slug/name/version/description/requiresSetup/check) with the
+ * tunnel-specific `capabilities` + the existing `start`/`stop` lifecycle.
+ */
+
+interface ProviderStartOptions {
+    /** Local target the tunnel forwards to. */
+    target: {
+        host: string;
+        port: number;
+    };
+    /** Workspace path — for log / state files. */
+    workspace: string;
+    /** Called whenever the provider has a status update worth logging. */
+    onLog?: (line: string) => void;
+}
+interface ProviderStartResult {
+    publicUrl: string;
+    pid: number | null;
+}
+/**
+ * A pluggable tunnel provider.
+ *
+ * `start` returns the public URL once the upstream tunnel is ready.
+ * `stop` is idempotent — calling it twice or on an already-dead child
+ * must not throw.
+ */
+interface RemoteProvider {
+    readonly id: string;
+    start(opts: ProviderStartOptions): Promise<ProviderStartResult>;
+    stop(): Promise<void>;
+}
+
+/**
+ * Slug-keyed tunnel provider registry — the single source of truth that both
+ * halves of the tunnel family consult:
+ *
+ *   - the adapter-kit listing path (`list_tunnel_adapters` / `setup_tunnel_provider`)
+ *   - the lifecycle path (`TunnelRegistry`: create / restore / start / stop)
+ *
+ * Before this module those two halves spoke different languages — the
+ * lifecycle engine only knew the short discriminators `"quick"`/`"named"` and
+ * had no ngrok case at all, while the adapter half spoke slugs. They never
+ * reconciled, so ngrok was listable-but-not-creatable. Routing everything
+ * through one registry collapses that: a built-in OR a third-party
+ * `@agentproto/adapter-<slug>` / `@<scope>/agentproto-adapter-<slug>` provider
+ * resolves the same way and works end to end.
+ */
+
+/** Per-slug credentials, as stored by the creds store / setup tool. */
+type TunnelCreds = Record<string, string>;
+
+/**
+ * TunnelRegistry — multi-tunnel public-URL manager.
+ *
+ * Manages a named set of cloudflared (or future provider) tunnels,
+ * each forwarding a local port to a public URL. Independent from
+ * RemoteController which handles the single "expose this gateway"
+ * use-case with bearer-token gating. This registry is for the general
+ * "create a public endpoint for any local port" surface.
+ *
+ * Lifecycle:
+ *   create(input) → spawns provider, waits for URL, stores descriptor
+ *   list()        → TunnelDescriptor[]
+ *   get(id)       → TunnelDescriptor | undefined
+ *   stop(id)      → SIGTERM provider, mark stopped
+ *   shutdown()    → stop all active tunnels (called on daemon exit)
+ *
+ * Persistence: `~/.agentproto/tunnels.json` — descriptors survive
+ * daemon restarts; active entries are marked "stopped" on next boot
+ * since their child processes are gone (same GHOST pattern as
+ * sessions.ts).
+ */
+
+type TunnelStatus = "starting" | "active" | "stopped" | "error";
+/**
+ * Provider identifier — an open set of slugs (built-in `cloudflare-quick` /
+ * `cloudflare-named` / `ngrok`, legacy short names `quick` / `named`, or any
+ * third-party `@scope/agentproto-adapter-<slug>`). Normalized to a canonical
+ * slug only at resolve time, so persisted descriptors keep their original
+ * value and need no migration.
+ */
+type TunnelProvider = string;
+interface TunnelDescriptor {
+    id: string;
+    /** Optional user-friendly slug. Accepts id-or-name in stop/status calls. */
+    name?: string;
+    /** Free-text label surfaced in list / CLI table. */
+    label?: string;
+    provider: TunnelProvider;
+    targetHost: string;
+    targetPort: number;
+    publicUrl: string;
+    status: TunnelStatus;
+    pid: number | null;
+    createdAt: string;
+    stoppedAt?: string;
+    lastError?: string;
+    /**
+     * When true, the tunnel is relaunched on daemon boot (see
+     * `restoreOnBoot`). Only meaningful for `named` tunnels — a relaunched
+     * `quick` tunnel gets a fresh random URL, so autostart for it merely
+     * keeps *a* tunnel up, not a stable URL.
+     */
+    autostart?: boolean;
+    /** Stable public hostname routed to this tunnel. */
+    hostname?: string;
+    /** Cloudflare tunnel id or name (the `run` target). */
+    tunnelId?: string;
+    /** Path to the tunnel credentials JSON (defaults under ~/.cloudflared). */
+    credentialsFile?: string;
+}
+interface CreateTunnelInput {
+    targetPort: number;
+    provider?: TunnelProvider;
+    name?: string;
+    label?: string;
+    targetHost?: string;
+    /** Relaunch this tunnel on daemon boot. See `TunnelDescriptor.autostart`. */
+    autostart?: boolean;
+    /** Stable public hostname (e.g. app.example.com). */
+    hostname?: string;
+    /** Cloudflare tunnel id or name to `run`. */
+    tunnelId?: string;
+    /** Path to the credentials JSON (defaults to ~/.cloudflared/<tunnelId>.json). */
+    credentialsFile?: string;
+}
+interface TunnelRegistryOptions {
+    /** Absolute path for persistence file. Defaults to ~/.agentproto/tunnels.json */
+    persistPath?: string;
+    /** Absolute path to workspace — used as scratch dir for provider config files. */
+    workspace?: string;
+    /** Hook for surfacing provider log lines. */
+    onLog?: (line: string) => void;
+    /**
+     * Read stored credentials for a provider slug. Lets the lifecycle build a
+     * provider that keeps its secrets in the creds store (e.g. ngrok's authtoken,
+     * or any third-party provider) rather than on the descriptor. Injected by the
+     * daemon (index.ts); descriptor-carried config (named's hostname/tunnelId)
+     * still takes precedence.
+     */
+    readCreds?: (slug: string) => Promise<TunnelCreds | null>;
+}
+declare class TunnelRegistry {
+    private readonly tunnels;
+    private readonly persistPath;
+    private readonly workspace;
+    private readonly onLog;
+    private readonly readCreds;
+    private persistTimer;
+    constructor(opts?: TunnelRegistryOptions);
+    create(input: CreateTunnelInput): Promise<TunnelDescriptor>;
+    /**
+     * Drive an entry's provider through start and fold the result back into
+     * its descriptor. On failure the descriptor is marked `error` and the
+     * error re-thrown (callers that want best-effort — e.g. boot restore —
+     * catch it). Shared by `create` and `restoreOnBoot`.
+     */
+    private startEntry;
+    /**
+     * Relaunch every `autostart` tunnel that isn't currently running. Called
+     * once on daemon boot — `loadFromDisk` has already ghosted formerly-live
+     * entries to `stopped` and given autostart ones a real provider. Quick
+     * tunnels are skipped (a relaunch yields a fresh random URL, defeating
+     * the point); named tunnels come back on their stable hostname.
+     *
+     * Best-effort: a provider that fails to start leaves its descriptor in
+     * `error` and the others still come up.
+     */
+    restoreOnBoot(): Promise<void>;
+    list(): TunnelDescriptor[];
+    get(id: string): TunnelDescriptor | undefined;
+    findByIdOrName(idOrName: string): TunnelDescriptor | undefined;
+    stop(idOrName: string): Promise<boolean>;
+    shutdown(): Promise<void>;
+    protected pickProviderForTest(_provider: TunnelProvider, desc: TunnelDescriptor): Promise<RemoteProvider>;
+    /**
+     * Build the creds passed to a provider: stored creds (ngrok authtoken,
+     * third-party secrets) merged with descriptor-carried config (named's
+     * hostname/tunnelId/credentialsFile), descriptor taking precedence.
+     */
+    private credsForDescriptor;
+    private findEntryByIdOrName;
+    private schedulePersist;
+    private persistNow;
+    private loadFromDisk;
+}
+
+/**
+ * Cursor-based ring buffer for session events. Bridges the in-process
+ * SessionEventBus (push) to the poll_events MCP tool (pull).
+ *
+ * Capacity default: 1 000 events. Oldest entry dropped on overflow —
+ * callers that lag beyond the cap see a gap in their cursor but never
+ * a block. `since()` returns `nextCursor = totalEmitted` so a fresh
+ * call with that value always starts just past the current tail.
+ */
+
+interface EventRingSnapshot {
+    events: SessionEvent[];
+    nextCursor: number;
+}
+interface EventRingQueryOpts {
+    sessionIds?: string[];
+    types?: SessionEventType[];
+    /** Default 50. */
+    limit?: number;
+}
+interface EventRing {
+    /**
+     * Return events whose ring-index >= `cursor`. Pass 0 to get all
+     * retained events; pass the previously returned `nextCursor` for an
+     * incremental read. The returned `nextCursor` is always equal to
+     * `totalEmitted` — use it as the next `cursor` argument.
+     *
+     * Negative or below-base cursors are clamped to the oldest retained
+     * event (no error, just a potential replay of a partial window).
+     */
+    since(cursor: number, opts?: EventRingQueryOpts): EventRingSnapshot;
+    /** Wire the ring to a SessionEventBus. Returns an unsubscribe fn. */
+    wire(bus: SessionEventBus): () => void;
+}
+
+/**
+ * Completion-policy supervisor — WP1 + WP2 + WP3 + WP4 + WP5 + WP6 + WP7.
+ *
+ * WP7 (judge-gate): a gate may be a judge AGENT instead of a shell command —
+ * `gate: { judge: { adapter, model?, prompt, timeoutMs? } }`. When the trigger
+ * fires the supervisor spawns a short-lived agent (resolveAgentAdapter →
+ * spawnAgent), prompts it with the rubric (+ a minimal context tail of the
+ * watched session output), waits for its turn-end on the bus, reads the final
+ * reply and parses the LAST `VERDICT: PASS|FAIL` line (case-insensitive). PASS
+ * = gate pass (then-action), FAIL = gate fail (existing nudge/escalate path).
+ * Fail-safe: no resolver / spawn fail / timeout (default 120s) / unparseable
+ * verdict → FAIL (+ reason on state.error). The judge session is ALWAYS killed
+ * when the gate settles. The judge runs while the policy holds its `gating`
+ * slot, so it is accounted for in the WP6 concurrency cap. Persistence: a judge
+ * gate left in `gating` at crash is re-armed to `watching` like any active
+ * policy and simply re-runs the judge — no in-flight judge is persisted.
+ *
+ *
+ * State machine per attached policy:
+ *   watching → gating → acting → done
+ *                    ↘ nudging (retries < maxRetries) → watching  (gate failed, nudge sent)
+ *                    ↘ blocked                                     (gate failed, retries exhausted)
+ *                    ↘ awaiting-ack → done       (then:"commit" + requireHumanAck, ack approve)
+ *                                  ↘ cancelled    (ack reject)
+ *   watching → cancelled  (watched session exited before turn-end)
+ *
+ * Trigger: session:turn-end on the watched session(s).
+ * Gate: optional shell command via the same allowlist + cwd-anchor as
+ *       execute_command. exit 0 = pass.
+ * Action (then:"emit"): emits policy:passed / policy:failed on the bus
+ *       (readable via poll_events).
+ *
+ * WP5 (then:"commit"): on a GREEN gate, prepare a host-side git commit in the
+ * watched session's cwd — `git add -- <explicit paths>` then `git commit -m
+ * <message>` via the same allowlisted runCommand path (argv array, shell:false).
+ * GUARDRAILS: never `git add -A`/glob, never `git push`, never `--force`, never
+ * a branch the policy didn't ask for (commits the cwd's current branch), message
+ * passed as argv (no shell injection), empty paths → error (no commit). A `--`
+ * separator precedes the paths so a path can never be parsed as a git flag.
+ * "nothing to commit" is treated as SUCCESS (idempotent re-commit after a
+ * restart). `requireHumanAck` defaults to TRUE: the gate-green transition goes
+ * to `awaiting-ack` and emits `policy:commit-ready` (paths + message) instead of
+ * committing; the commit runs only on `ack_policy(approve:true)` →
+ * `policy:committed` (+ sha) → done; `approve:false` → cancelled. With
+ * `requireHumanAck:false` the commit runs directly at the green gate.
+ * onFail (WP2): when gate fails, re-prompts the session(s) (sendPrompt) up to
+ *       maxRetries times, then transitions to blocked + emits policy:failed.
+ *
+ * WP3: persists PolicyRunState + input to ~/.agentproto/policies.json (or an
+ * injected persistPath). Debounced async write on every transition; sync flush
+ * at shutdown(). On boot, active policies (watching/gating/nudging/acting) are
+ * re-armed to "watching" and re-subscribed to the bus. Terminal states (done/
+ * blocked/cancelled) are kept for history. Session absent at reload → cancelled.
+ *
+ * WP6 (DAG + concurrency cap):
+ *   - CHAINING: a policy may declare `next` — a recursive AttachPolicyInput.
+ *     When the policy reaches `done` (emit-passed or commit-committed), the
+ *     supervisor automatically attaches `next` as a fresh completion policy on
+ *     the session(s) named in its own spec (chaining policies over EXISTING
+ *     sessions — this WP does NOT spawn new sessions). The child's policyId is
+ *     recorded on the parent as `nextPolicyId`. Chaining is idempotent (a parent
+ *     already carrying a `nextPolicyId` never re-chains, so a re-armed/re-acked
+ *     parent after a restart won't double-attach). `next` persists as part of the
+ *     parent's `input`, so the whole chain survives a restart.
+ *   - CONCURRENCY CAP: a daemon-wide cap (`concurrencyCap`, default 8) on how
+ *     many policies may be in `gating`/`acting` at once. When a trigger fires
+ *     and the cap is already saturated, the policy parks in `queued` (a FIFO
+ *     gate queue) instead of gating. As each active policy settles (done /
+ *     blocked / awaiting-ack / back-to-watching after a nudge), the queue is
+ *     pumped and the oldest queued policy proceeds to gate. Queued policies hold
+ *     NO slot, so a chained DAG can't deadlock behind the cap. The queued state
+ *     persists and is re-armed to `watching` on reload (then re-evaluated).
+ *
+ * WP4 (fan-in): a policy may watch a GROUP of sessions (`sessionIds`). The gate
+ * runs ONCE, only after EVERY member of the group has finished its turn. Members
+ * are tracked in an idempotent `pending` set: a member is removed on its first
+ * `session:turn-end`; a repeated turn-end for an already-removed member is a
+ * no-op (no double-count). When the set empties → gating.
+ *
+ * A member that emits `session:exited` is treated as "this member is done": it
+ * is removed from the pending set exactly like a turn-end (a dead session will
+ * never emit one), so a partially-crashed group can still complete. If every
+ * member exits, the set empties and the gate runs once. The one exception is the
+ * degenerate group of size 1 (the legacy single-`sessionId` form): a lone
+ * watched session that exits has nothing left to gate on, so the policy is
+ * cancelled — preserving the original single-session contract.
+ *
+ * Back-compat: the legacy `sessionId` (single) form is a group of one. `state.
+ * sessionId` is retained as the group's representative (group[0]) and is the id
+ * carried on policy:passed / policy:failed events.
+ */
+
+interface ShellGateSpec {
+    command: string;
+    args?: string[];
+    /** Working directory for the gate command. Defaults to the watched
+     *  session's cwd, anchored to the workspace. */
+    cwd?: string;
+    timeoutMs?: number;
+}
+/**
+ * Judge-agent gate (WP7). Instead of a shell command, the gate spawns a
+ * short-lived LLM agent (via the daemon's `resolveAgentAdapter`), prompts it
+ * with `prompt` (+ a minimal context tail of the watched session output, if
+ * readable), waits for its turn to end, reads the final reply and parses a
+ * verdict line (`VERDICT: PASS` / `VERDICT: FAIL`, last occurrence,
+ * case-insensitive). PASS = gate pass (exit 0 equivalent), FAIL = gate fail
+ * (→ the existing nudge/escalate path). Fail-safe: a judge timeout OR an
+ * unparseable reply is treated as FAIL. The judge session is always killed
+ * when the gate settles (success or failure).
+ */
+interface JudgeGateSpec {
+    judge: {
+        /** Agent CLI adapter slug used to spawn the judge (e.g. "claude-code"). */
+        adapter: string;
+        /** Optional model identifier forwarded to the adapter. */
+        model?: string;
+        /** The rubric / instructions for the judge. The supervisor appends a
+         *  fixed instruction to end the reply with `VERDICT: PASS` or
+         *  `VERDICT: FAIL`. */
+        prompt: string;
+        /** Max wall-clock for the judge turn before it is killed + FAIL.
+         *  Default 120_000ms. */
+        timeoutMs?: number;
+    };
+}
+/** A gate is either a shell command (exit 0 = pass) or a judge agent. */
+type GateSpec = ShellGateSpec | JudgeGateSpec;
+interface OnFailSpec {
+    /**
+     * Message sent to the watched session via sendPrompt when the gate fails.
+     * Use the placeholder {code} to embed the actual exit code.
+     * Default: "Le gate a échoué (exit {code}). Corrige et termine jusqu'à ce qu'il passe."
+     */
+    nudge?: string;
+    /**
+     * Maximum number of consecutive gate failures before transitioning to
+     * blocked. Must be >= 1. Default: 2.
+     */
+    maxRetries?: number;
+}
+interface CommitSpec {
+    /**
+     * Explicit, literal paths to stage — workspace/cwd-relative. NEVER a glob,
+     * NEVER `-A`/`--all`. Staged via `git add -- <paths>` (the `--` guards each
+     * path from being parsed as a flag). An empty array is rejected at attach.
+     */
+    paths: string[];
+    /** Commit message. Passed as a single `-m` argv value — no shell. */
+    message: string;
+    /**
+     * Human-in-the-loop gate before the commit actually runs. Default TRUE:
+     * the green gate transitions to `awaiting-ack` + emits `policy:commit-ready`
+     * and waits for `ack_policy`. Set false to commit directly at the green gate.
+     */
+    requireHumanAck?: boolean;
+}
+interface AttachPolicyInput {
+    /**
+     * Session id whose turn-end triggers the policy (single-session / legacy
+     * form). Equivalent to `sessionIds: [sessionId]`. Provide this OR
+     * `sessionIds`; if both are given, `sessionIds` wins.
+     */
+    sessionId?: string;
+    /**
+     * Fan-in group (WP4): the gate runs once, only after EVERY listed session
+     * has finished its turn (turn-end or exit). Supersedes `sessionId` when
+     * present and non-empty. A single-element array behaves like `sessionId`.
+     */
+    sessionIds?: string[];
+    /**
+     * Optional gate. Absent → always pass immediately. Either a shell gate
+     * (exit 0 = pass) or a judge-agent gate (WP7: `{ judge: {...} }`).
+     */
+    gate?: GateSpec;
+    /**
+     * Action on a GREEN gate. "emit" (WP1) emits policy:passed. "commit" (WP5)
+     * stages explicit paths and commits on the host — see `commit`.
+     */
+    then: "emit" | "commit";
+    /** Required when then === "commit". Ignored otherwise. */
+    commit?: CommitSpec;
+    /**
+     * What to do when the gate fails (WP2). Absent → immediately blocked
+     * (WP1 behaviour). Present → re-prompt the session up to maxRetries
+     * times before blocking; the session must still be running to nudge.
+     */
+    onFail?: OnFailSpec;
+    /**
+     * DAG chaining (WP6). When this policy reaches `done`, the supervisor
+     * automatically attaches `next` as a fresh completion policy. `next` is a
+     * full AttachPolicyInput (recursive — it may declare its own `next`), and it
+     * carries the session(s) it watches in its own spec. Chaining only attaches
+     * policies onto already-running sessions; it never spawns new sessions.
+     */
+    next?: AttachPolicyInput;
+}
+type PolicyRunStatus = "watching" | "queued" | "gating" | "acting" | "nudging" | "awaiting-ack" | "done" | "blocked" | "cancelled";
+interface PolicyRunState {
+    policyId: string;
+    /** Representative session id (the fan-in group's first member, group[0]).
+     *  Carried on policy:passed / policy:failed events. */
+    sessionId: string;
+    /** The full fan-in group being watched. Always present; a length-1 group is
+     *  the legacy single-session form. */
+    sessionIds: string[];
+    /** Sessions in the group that have NOT yet finished their turn. The gate
+     *  fires once this set empties. Idempotent: a member is removed on its first
+     *  turn-end/exit; repeats are no-ops. Reset to the full group on each nudge. */
+    pending: string[];
+    status: PolicyRunStatus;
+    /** Number of nudges sent so far (incremented after each nudge round). */
+    retries: number;
+    startedAt: string;
+    endedAt?: string;
+    lastGate?: {
+        exitCode: number;
+        at: string;
+    };
+    /**
+     * The exact commit prepared at the green gate (WP5). Set when entering
+     * `awaiting-ack` (or just before a direct commit) so that an ack arriving
+     * after a daemon restart commits the same paths/message in the same cwd,
+     * independent of whether the watched session still exists.
+     */
+    commitPlan?: {
+        paths: string[];
+        message: string;
+        cwd: string;
+    };
+    /** The resulting commit sha once `then:"commit"` has committed. */
+    commitSha?: string;
+    /**
+     * DAG chaining (WP6): the policyId of the child policy attached when this
+     * policy reached `done`. Set exactly once (idempotent chaining guard).
+     */
+    nextPolicyId?: string;
+    error?: string;
+}
+interface CompletionPolicySupervisor {
+    /**
+     * Attach a completion policy to an already-running session.
+     * Returns immediately with the initial (watching) state.
+     * The state machine runs in the background.
+     */
+    attach(input: AttachPolicyInput): PolicyRunState;
+    getStatus(policyId: string): PolicyRunState | undefined;
+    cancel(policyId: string): void;
+    /**
+     * Human acknowledgement for a `then:"commit"` policy parked in
+     * `awaiting-ack` (WP5). `approve:true` runs the prepared commit (→ done,
+     * emits policy:committed); `approve:false` cancels it (no commit). No-op on
+     * any other state. Returns the (possibly updated) state.
+     */
+    ack(policyId: string, approve: boolean): Promise<PolicyRunState | undefined>;
+    list(): PolicyRunState[];
+    /**
+     * Sync flush of the policy snapshot to disk. Call from the daemon
+     * stop() path — mirrors sessions.shutdown().
+     */
+    shutdown(): void;
+}
+
+/**
+ * Fire-and-forget webhook notifier for session lifecycle events.
+ *
+ * Each session can register its own `notifyUrl` (via `start_agent_session`).
+ * A global URL can be set via `AGENTPROTO_NOTIFY_URL` env var or
+ * `~/.agentproto/notify.json` (env wins). Both are POSTed when an event
+ * fires — the union of per-session + global URLs, deduplicated.
+ *
+ * Retry policy: one retry after 2 s on network error. No retry on 4xx/5xx.
+ * Timeout: 10 s per attempt. All errors are swallowed — the notifier never
+ * throws into the session's hot path.
+ */
+
+interface WebhookNotifier {
+    /** Register a per-session URL (called from start_agent_session). */
+    register(sessionId: string, url: string): void;
+    unregister(sessionId: string): void;
+    /** Handler to wire into SessionEventBus.onAny. Fire-and-forget. */
+    onSessionEvent(ev: SessionEvent): void;
+}
+
+/**
+ * Orchestrator sub-gateway (ADR §4.2 / WP2) — the security primitive
+ * that lets a spawned agent become a *scoped* orchestrator without
+ * handing it the daemon's full toolset.
+ *
+ * The plain `/mcp` endpoint registers EVERY tool (execute_command,
+ * fs_*, remote_*, import_mcp, terminals, driver CRUD) and bypasses auth
+ * on loopback — pointing a child at it would be a privilege handout.
+ * This module builds a second, scoped MCP server that registers ONLY a
+ * curated orchestration allowlist, gated by an unguessable per-child
+ * scope-token. The HTTP layer mounts it at `/mcp/orchestrator`
+ * (`http-server.ts`); WP3 will auto-mint a token and inject the URL at
+ * spawn time. WP2 only builds the primitive.
+ *
+ * Three pieces:
+ *   - DEFAULT_ORCHESTRATOR_TOOLS — the curated allowlist.
+ *   - createScopeTokenRegistry() — mint / verify / revoke scope-tokens.
+ *   - createOrchestratorMcpServerFactory() — build a scoped server for
+ *     a verified scope.
+ */
+
+/**
+ * The curated set of tools a scoped child orchestrator may call.
+ *
+ * INCLUDED — the orchestration primitives:
+ *   start_agent_session, prompt_agent_session, get_agent_session_output,
+ *   wait_for_any, poll_events  (spawn + drive + fan-in)
+ *   list_sessions, list_agent_sessions, kill_agent_session  (observe +
+ *     halt). NB: list/kill are NOT yet scoped to the child's own
+ *     subtree — that subtree filter is WP4 (parentSessionId/depth). For
+ *     WP2 they are exposed daemon-wide; documented debt.
+ *
+ * EXCLUDED — the danger surface (each a separate trust boundary):
+ *   execute_command, terminal/PTY tools (raw shell), fs tools
+ *   (read/write/delete file, create_directory, …), remote_* (publish
+ *   the daemon to the internet), import_mcp / mcp_imported_* /
+ *   list_discovered_mcps / remove_imported_mcp (widen the daemon's own
+ *   MCP surface), and driver CRUD (create_/delete_/update_driver — these
+ *   never register here because the scoped server is built with no
+ *   doctype specs).
+ */
+declare const DEFAULT_ORCHESTRATOR_TOOLS: readonly string[];
+interface OrchestratorScope {
+    /** The opaque scope-token handed to (and presented by) the child. */
+    token: string;
+    /** The effective tool allowlist for this scope (⊆ the default and,
+     *  for a recursively-spawned child, ⊆ its parent's allowlist). */
+    tools: ReadonlySet<string>;
+    /**
+     * Session id of the orchestrator that OWNS this token — i.e. the
+     * child session that presents it back on `/mcp/orchestrator`. The
+     * token is minted *before* the child session exists (the injector
+     * needs the URL to compose the spawn), so this is bound late, after
+     * `spawnAgent` returns the id, via `bindOwner`. Until bound, spawns
+     * through this scope are attributed to no parent and its subtree is
+     * empty (safe degradation). (ADR §4.5 / WP4) */
+    ownerSessionId?: string;
+    /** Recursion depth of the owning orchestrator session. A spawn made
+     *  *through* this scope produces a child at `depth + 1`. Root scopes
+     *  (minted for a direct `/mcp` spawn) are depth 0. */
+    depth: number;
+    /** Max recursion depth reachable through this scope. A spawn whose
+     *  child depth (`depth + 1`) would exceed this is rejected. Clamped
+     *  to `HARD_MAX_DEPTH`. */
+    maxDepth: number;
+    /** Max concurrently-alive children the owning orchestrator may spawn
+     *  before further spawns are rejected. */
+    maxChildren: number;
+}
+/**
+ * Narrow a caller-requested tool list to ⊆ a ceiling subset.
+ *
+ * The `ceiling` is the maximum a caller may end up with — the global
+ * `DEFAULT_ORCHESTRATOR_TOOLS` for a root scope, or the *parent's*
+ * effective tools for a recursively-spawned child (non-re-grant: a
+ * child can never widen beyond what its parent holds — ADR §4.5 #5).
+ * The `{ tools: [...] }` form can only REMOVE from the ceiling, never
+ * add: any name outside it is dropped. Omitting `requested` yields the
+ * full ceiling. Omitting `ceiling` defaults to the global default.
+ */
+declare function narrowOrchestratorTools(requested?: readonly string[], ceiling?: ReadonlySet<string>): Set<string>;
+interface MintScopeOptions {
+    /** Caller-requested allowlist — narrowed ⊆ `ceiling` (or the default
+     *  when no ceiling is given). */
+    tools?: readonly string[];
+    /** Upper bound on the minted tools (the parent's effective tools for
+     *  a recursive child). Omit for a root scope (defaults to the global
+     *  default subset). */
+    ceiling?: ReadonlySet<string>;
+    /** Depth of the owning orchestrator (default 0). */
+    depth?: number;
+    /** Max depth reachable through this scope (default DEFAULT_MAX_DEPTH,
+     *  clamped to HARD_MAX_DEPTH). */
+    maxDepth?: number;
+    /** Per-orchestrator alive-child quota (default DEFAULT_MAX_CHILDREN). */
+    maxChildren?: number;
+}
+interface ScopeTokenRegistry {
+    /** Mint a fresh scope-token. See `MintScopeOptions`. */
+    mint(opts?: MintScopeOptions): OrchestratorScope;
+    /** Resolve a presented token to its scope, or null when unknown. */
+    verify(token: string | null | undefined): OrchestratorScope | null;
+    /** Late-bind the owning child session id onto a minted scope (the
+     *  token is minted before the child exists). No-op when the token is
+     *  unknown. Mutates the live scope object so `verify` reflects it. */
+    bindOwner(token: string, sessionId: string): void;
+    /** Drop a token (e.g. when the child session ends). */
+    revoke(token: string): void;
+}
+/**
+ * In-memory registry of live scope-tokens. Tokens are random 256-bit
+ * hex (unguessable, never persisted) — see ADR §5.3. Single-user-host
+ * trust assumption mirrors the loopback auth bypass on `/mcp`.
+ */
+declare function createScopeTokenRegistry(): ScopeTokenRegistry;
+interface OrchestratorGatewayDeps {
+    workspace: string;
+    name?: string;
+    version?: string;
+    registry: SessionsRegistry;
+    sessionEvents: SessionEventBus;
+    eventRing: EventRing;
+    supervisor?: CompletionPolicySupervisor;
+    resolveAgentAdapter?: AgentAdapterResolver;
+    listAgentAdapters?: AgentAdapterLister;
+    /** Orchestrator injector (WP3/WP4). When wired, a child orchestrator
+     *  driving the scoped server can itself spawn sub-orchestrators
+     *  (`orchestrator: true` on its `start_agent_session`) — the new
+     *  token inherits depth+1 and is bounded by the caller's tools
+     *  (non-re-grant). Omitted → recursion injection is unavailable on
+     *  the scoped surface (a child can still spawn plain sub-agents). */
+    orchestratorInjector?: OrchestratorInjector;
+    /** Optional webhook notifier — same singleton as the root /mcp server.
+     *  When provided, per-session notifyUrl values from start_agent_session
+     *  are registered on spawn and unregistered on exit, so child
+     *  orchestrators spawning through this scoped gateway also fire webhooks. */
+    webhookNotifier?: WebhookNotifier;
+}
+type OrchestratorMcpServerFactory = (scope: OrchestratorScope) => Promise<McpServer>;
+/**
+ * Build a factory that produces a scoped MCP server for a verified
+ * scope. The server is created with NO doctype specs and NO workspace
+ * (so no CRUD verbs, no `self_inspect`, no driver tools leak in), then
+ * the orchestration passes run against a `withToolSubset` wrapper so
+ * only `scope.tools` survive. Critically, `mcpProxy` and the PTY
+ * factory are never wired here — import + terminal tools stay unwired
+ * AND are excluded from the subset (defense in depth).
+ */
+declare function createOrchestratorMcpServerFactory(deps: OrchestratorGatewayDeps): OrchestratorMcpServerFactory;
+/**
+ * The auto-injection assembly (ADR §4.4 / WP3) — turns the "make this
+ * child an orchestrator" intent into the concrete `mcpServers` entry
+ * the ACP `session/new` call mounts, plus the token lifecycle.
+ *
+ * One call (`inject`) does three things:
+ *   1. mint a scope-token (narrowed ⊆ default when `tools` is given);
+ *   2. build the `mcpServers` entry pointing the child at the daemon's
+ *      own scoped sub-gateway (`/mcp/orchestrator?scope=<token>`);
+ *   3. hand back `bindLifecycle(sessionId)` so the caller can revoke
+ *      the token the moment that child session exits — no token leaks
+ *      past the life of the session it was minted for.
+ *
+ * Assembled in `createGateway` (not the CLI resolver) because it needs
+ * the gateway's scope-token registry, the session-event bus, and the
+ * HTTP listener's port — all of which live there.
+ */
+interface OrchestratorInjection {
+    /** The `mcpServers` entry to merge into the child's `session/new`. */
+    entry: AcpMcpServer;
+    /** The minted scope — `token` gates the endpoint, `tools` is the
+     *  effective (narrowed) allowlist. */
+    scope: OrchestratorScope;
+    /**
+     * Revoke the scope-token once `sessionId` exits. Subscribes to the
+     * session-event bus for that one session's `session:exited` and
+     * self-unsubscribes on fire. Returns an unsubscribe in case the
+     * caller wants to drop the binding early (rarely needed).
+     */
+    bindLifecycle(sessionId: string): () => void;
+}
+interface OrchestratorInjectorDeps {
+    scopeTokens: ScopeTokenRegistry;
+    sessionEvents: SessionEventBus;
+    /** Port the daemon's HTTP listener (and thus `/mcp/orchestrator`)
+     *  binds. The child reaches it over loopback. */
+    port: number;
+    /** Loopback host for the injected `ref`. Always loopback — the child
+     *  is co-located on the host. Default `127.0.0.1`. */
+    host?: string;
+    /** `name` advertised on the injected `mcpServers` entry. The child
+     *  sees its orchestration tools namespaced under this. Default
+     *  `agentproto`. */
+    entryName?: string;
+}
+type OrchestratorInjector = (opts?: {
+    tools?: readonly string[];
+    /** The calling orchestrator's scope, when this spawn arrives via the
+     *  scoped sub-gateway (recursive spawn). The minted child token then
+     *  inherits `depth = caller.depth + 1`, its tools are bounded by the
+     *  caller's tools (non-re-grant — ADR §4.5 #5), and its depth/child
+     *  limits never exceed the caller's. Omit for a root spawn (direct
+     *  `/mcp`) → depth 0, full default subset, default limits. */
+    caller?: OrchestratorScope;
+    /** Override the max depth reachable through the minted scope (clamped
+     *  to the caller's, then to HARD_MAX_DEPTH). Root-only knob. */
+    maxDepth?: number;
+    /** Override the per-orchestrator child quota for the minted scope
+     *  (clamped to the caller's). Root-only knob. */
+    maxChildren?: number;
+}) => OrchestratorInjection;
+/**
+ * Build the orchestrator injector. Closed over the gateway's
+ * scope-token registry + session-event bus + HTTP port. Returns a
+ * function that the `start_agent_session` handler calls when its
+ * `orchestrator` field is set.
+ */
+declare function createOrchestratorInjector(deps: OrchestratorInjectorDeps): OrchestratorInjector;
+
 /**
  * Tiny node:http server that fronts the runtime gateway.
  *
@@ -328,13 +1361,31 @@ type AgentAdapterResolver = (slug: string) => Promise<{
     startSession(opts: {
         cwd: string;
         resumeSessionId?: string;
-        /** Model identifier forwarded from `start_agent_session`. Adapters
-         *  that support model selection (e.g. via a `--model` CLI flag) may
-         *  honour this; others silently ignore it. */
+        /** Model identifier forwarded from `start_agent_session`. For ACP
+         *  adapters this is applied via session/set_config_option after
+         *  newSession (the ACP wrapper does not forward CLI args to claude).
+         *  Adapters that don't support model selection ignore it. */
         model?: string;
+        /** Effort level forwarded from `start_agent_session`. Effort is
+         *  model-dependent — same label ≠ same budget across models; defaults
+         *  differ by model. Omit to keep the model's own default. Applied
+         *  via session/set_config_option on ACP adapters; others ignore it. */
+        effort?: string;
+        /** MCP servers to mount into the spawned agent's session at spawn
+         *  time. Forwarded verbatim to the driver's `start({ mcpServers })`
+         *  → the ACP arm's `session/new.mcpServers`, giving the child agent
+         *  a host-chosen scoped toolset (e.g. the daemon's own orchestration
+         *  gateway). Adapters that don't model MCP mounting ignore it. */
+        mcpServers?: AcpMcpServer[];
     }): 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>;
 } | null>;
 /**
  * Compact adapter metadata for the discovery endpoints. Independent
@@ -357,6 +1408,128 @@ interface AuthOptions {
     token?: string;
 }
 
+/**
+ * InboundWatcher — polls agentpush `poll_inbound` on a timer and
+ * spawns one agent per contact_ref that has unread inbound messages.
+ *
+ * Flow per tick:
+ *   mcp_imported_call(alias, "poll_inbound", {source, since:cursor})
+ *   → group events by contact_ref
+ *   → spawn one agent per contact with prompt from promptTemplate
+ *   → advance + persist cursor to ~/.agentproto/agentpush-cursors.json
+ *
+ * Cursor key = "${alias}:${source}" — stable across daemon restarts so
+ * cursor resume actually works (a random watcherId would break it).
+ *
+ * Prompt template variables: {{source}}, {{contact_ref}},
+ *   {{messages_json}}, {{count}}.
+ *
+ * The mcpServersForChild array is forwarded to the spawned agent's
+ * startSession + spawnAgent so the child can call dispatch_request
+ * directly on the mounted agentpush MCP server.
+ *
+ * State is in-memory; cursors persist to disk (debounced async write
+ * + sync flush at shutdown), matching the supervisor.ts pattern.
+ */
+
+interface WatcherStartInput {
+    /** Imported MCP alias (e.g. "agentpush"). */
+    alias: string;
+    /** Contact ref / channel to watch — forwarded as `source` to poll_inbound. */
+    source: string;
+    /** Agent adapter slug (e.g. "claude-code"). */
+    adapter: string;
+    /**
+     * Prompt template with placeholders:
+     *   {{source}}        — the watched source
+     *   {{contact_ref}}   — the sender's contact_ref
+     *   {{messages_json}} — JSON array of the new events
+     *   {{count}}         — number of new messages
+     */
+    promptTemplate: string;
+    /** Poll interval in ms. Default 5 000. */
+    pollIntervalMs?: number;
+    /** Working directory for spawned agents. Default process.cwd(). */
+    cwd?: string;
+    /** Optional label suffix on spawned sessions. */
+    label?: string;
+    /**
+     * MCP servers to mount in the child agent at spawn time.
+     * Pass agentpush here so the child can call dispatch_request.
+     */
+    mcpServersForChild?: Array<{
+        name: string;
+        transport: "stdio" | "http" | "sse";
+        ref?: string;
+    }>;
+}
+interface WatcherDescriptor {
+    watcherId: string;
+    alias: string;
+    source: string;
+    adapter: string;
+    pollIntervalMs: number;
+    status: "running" | "stopped";
+    /** Next `since` value for poll_inbound (exclusive lower bound). */
+    cursor: number;
+    lastPollAt?: string;
+    lastFireAt?: string;
+    /** Total agent sessions spawned since the watcher started. */
+    spawned: number;
+}
+interface InboundWatcher {
+    start(input: WatcherStartInput): WatcherDescriptor;
+    /** Returns false when watcherId is unknown. */
+    stop(watcherId: string): boolean;
+    list(): WatcherDescriptor[];
+    /** Stops all watchers and flushes cursor state to disk synchronously. */
+    shutdown(): void;
+}
+
+/**
+ * Browser family on top of `@agentproto/adapter-kit` — Phase 3 (lightest
+ * adoption: no creds, no wizard, no catalog file).
+ *
+ * Provides the kit-compatible types (`BrowserAdapterHandle`) and the
+ * `makeBrowserAdapterLister` factory that wraps the existing injected
+ * `listBrowserAdapters` / `resolveBrowserAdapter` functions in a standard
+ * `AdapterLister<BrowserAdapterInfo>`.
+ *
+ * The resulting lister is passed as the `lister` option to
+ * `registerBrowserTools`, which uses it to produce the same
+ * `{ id, name, description, defaultPort }[]` JSON the legacy path emits
+ * (output shape is unchanged — only the internal flow changes).
+ *
+ * Kit invariants honoured:
+ *   - `check()` is NEVER called by the lister (OQ-5).
+ *   - `BrowserAdapterInfo` carries no cred values (Appendix B).
+ *   - `requiresSetup = false` → status is always "ready" without a ledger.
+ */
+
+/**
+ * Kit-compatible handle for a single in-process browser adapter.
+ * `requiresSetup` is always `false` — browser adapters need no creds or
+ * setup wizard, so the kit classifies them as "ready" on first resolution.
+ */
+interface BrowserAdapterHandle extends AdapterHandle {
+    readonly requiresSetup: false;
+    readonly defaultPort: number;
+}
+/**
+ * Build a kit-compatible `AdapterLister<BrowserAdapterInfo>` from the
+ * existing injected browser adapter functions. The returned lister uses an
+ * empty catalog and `discoverExtras` to surface the injected adapters, then
+ * maps each resolved handle's fields into a `BrowserAdapterInfo` descriptor.
+ *
+ * The caller should pass the result as the `lister` option to
+ * `registerBrowserTools`, which extracts `AdapterEntry.info` to preserve the
+ * existing tool response shape.
+ */
+declare function makeBrowserAdapterLister(opts: {
+    listBrowserAdapters: BrowserAdapterLister;
+    resolveBrowserAdapter?: BrowserAdapterResolver;
+}): AdapterLister<BrowserAdapterInfo>;
+
 /**
  * `.agentproto/` config dir — runtime-managed state at the root of
  * every workspace. Mirrors the `.git/` model: user-content stays at
@@ -369,6 +1542,15 @@ interface AuthOptions {
  *     for `cat .agentproto/runtime.json` diagnostics + future tooling
  *     that wants to discover a running gateway from disk.
  *
+ * The same snapshot is ALSO mirrored to the central, workspace-
+ * independent daemon registry at `~/.agentproto/daemons/<port>.json`
+ * (see daemonRegistryDir / writeDaemonRegistryEntry below). The
+ * per-workspace file only helps `cat`-style local diagnostics and
+ * discovery for REGISTERED workspaces; a daemon launched from an
+ * arbitrary cwd (tunnel mode, a repo checkout) writes its workspace
+ * file somewhere discovery never walks. The central entry is what
+ * makes `agentproto chat` / `sessions` find such a daemon.
+ *
  * What does NOT go here:
  *   - HEARTBEAT.md — user-edited content
  *   - conversations/ — user-readable chat history
@@ -406,13 +1588,44 @@ interface RuntimeMeta {
      */
     token: string;
 }
+/** `~/.agentproto/daemons/` — the central, workspace-independent daemon
+ *  registry. Each live daemon owns one `<port>.json` here. */
+declare function daemonRegistryDir(): string;
+/**
+ * Write `<registry>/<port>.json` (mode 0600 — holds the bearer token).
+ * Best-effort; failure here never gates the gateway. Mirrors the
+ * per-workspace runtime.json so the same `RuntimeMeta` shape is readable
+ * from either location.
+ */
+declare function writeDaemonRegistryEntry(meta: RuntimeMeta): Promise<void>;
+/** Remove a daemon's central registry entry. Best-effort; missing is a
+ *  no-op. Called from graceful shutdown alongside unlinkRuntimeMeta. */
+declare function unlinkDaemonRegistryEntry(port: number): Promise<void>;
+/**
+ * Read every entry in the central daemon registry, newest-first by
+ * `startedAt`. No liveness filtering here — callers decide (discovery
+ * skips dead PIDs; the sweep deletes them). Malformed / unreadable
+ * entries are skipped silently.
+ */
+declare function readDaemonRegistry(): Promise<Array<{
+    meta: Partial<RuntimeMeta> & Record<string, unknown>;
+    path: string;
+    mtime: Date;
+}>>;
+/**
+ * Delete central registry entries whose PID is dead (kill -9, crash,
+ * reboot). Returns the paths cleaned. Called at `serve` boot — the same
+ * footgun the per-workspace sweep guards against, applied to the central
+ * registry. Skips `currentPort` (the booting daemon's own entry).
+ */
+declare function sweepStaleDaemonRegistry(currentPort: number): Promise<string[]>;
 /**
  * Delete `<workspace>/.agentproto/runtime.json`. Best-effort — called
  * from the daemon's graceful shutdown path so a CLI looking for the
  * live daemon doesn't pick up a stale token after this process exits.
  * Missing file is a no-op (the daemon may never have written one).
  */
-declare function unlinkRuntimeMeta(workspace: string): Promise<void>;
+declare function unlinkRuntimeMeta(workspace: string, port?: number): Promise<void>;
 /**
  * Read a runtime.json from `<workspace>/.agentproto/`. Returns the
  * parsed object (no validation) plus the on-disk mtime, or null when
@@ -493,6 +1706,12 @@ interface CreateGatewayOptions {
      *  `GET /adapters` HTTP route + `list_adapters` MCP tool so UIs
      *  can discover what's installed on the host. */
     listAgentAdapters?: AgentAdapterLister;
+    /** Optional browser adapter resolver — when provided, enables the
+     *  `start_browser` MCP tool (launches Camofox / Bureau / Chromium). */
+    resolveBrowserAdapter?: BrowserAdapterResolver;
+    /** Optional browser adapter lister — when provided, enables the
+     *  `list_adapter_browsers` MCP tool. */
+    listBrowserAdapters?: BrowserAdapterLister;
     /** Optional PTY factory (node-pty wrapper, typically from the cli
      *  layer's `loadNodePtyFactory()`). When provided, enables
      *  `POST /sessions/terminal`, the `start_terminal_session` MCP
@@ -522,11 +1741,23 @@ interface GatewayHandle {
      *  inside the same process can register their child processes for
      *  visibility through /sessions and the CLI TUI. */
     sessions: SessionsRegistry;
+    /** Tunnel registry — manages public cloudflared tunnels for any
+     *  local port. Exposed so embedding hosts can open tunnels
+     *  programmatically without going through the HTTP/MCP surface. */
+    tunnels: TunnelRegistry;
     /** 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
      *  tools without re-reading the runtime.json file. */
     token: string;
+    /** Mint a scope-token for the scoped orchestrator sub-gateway
+     *  (`/mcp/orchestrator`). The returned `token` gates that endpoint
+     *  and `tools` is the effective allowlist (⊆ the default orchestrator
+     *  subset). WP3 will call this at spawn time and inject the URL into
+     *  the child's `mcpServers`; for WP2 it's the internal primitive. */
+    mintOrchestratorScope(opts?: {
+        tools?: readonly string[];
+    }): OrchestratorScope;
     stop(): Promise<void>;
 }
 /**
@@ -543,4 +1774,4 @@ interface GatewayHandle {
  */
 declare function createGateway(opts: CreateGatewayOptions): Promise<GatewayHandle>;
 
-export { type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, BuildHeartbeatAgent, type CreateGatewayOptions, type GatewayHandle, type RuntimeMeta, type SessionDescriptor, type SessionKind, type SessionStatus, type SessionsRegistry, type SpawnAgentInput, type SpawnSessionInput, WorkspaceFs, createGateway, readRuntimeMeta, sweepStaleRuntimeMetas, unlinkRuntimeMeta };
+export { type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, type CreateGatewayOptions, DEFAULT_ORCHESTRATOR_TOOLS, type GatewayHandle, type InboundWatcher, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, type RegisterBrowserInput, type RegisterSessionInput, type RuntimeMeta, type ScopeTokenRegistry, type SessionDescriptor, type SessionKind, type SessionStatus, type SessionsRegistry, type SpawnAgentInput, type SpawnSessionInput, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type WatcherDescriptor, type WatcherStartInput, WorkspaceFs, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createScopeTokenRegistry, daemonRegistryDir, makeBrowserAdapterLister, narrowOrchestratorTools, readDaemonRegistry, readRuntimeMeta, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };