@agentproto/runtime 2.5.0 → 2.7.0

package/dist/index.d.ts

@@ -6,20 +6,22 @@ import { AcpMcpServer, AcpPermissionResolution } from '@agentproto/acp';
 import { SessionMode } from '@agentproto/acp/client';
 export { SessionMode } from '@agentproto/acp/client';
 import { ChildProcess } from 'node:child_process';
-import { R as RouteSpec, S as SessionConfig, P as Posture, C as ContextProfile, E as EffortLevel, A as AuthMethod, a as CanonicalPosture } from './session-config-DIf6wYYP.js';
-export { D as DeclaredAdapterMode, c as composeMode, d as decomposeMode } from './session-config-DIf6wYYP.js';
+import { R as RouteSpec, S as SessionConfig, P as Posture, C as ContextProfile, E as EffortLevel, A as AuthMethod, a as CanonicalPosture } from './session-config-DbWP9RRj.js';
+export { D as DeclaredAdapterMode, c as composeMode, d as decomposeMode } from './session-config-DbWP9RRj.js';
 import { CostBudget, AuthProfile, CostBudgetScope } from '@agentproto/auth';
 export { CostBudget, CostBudgetScope } from '@agentproto/auth';
-import { R as ResolvedContextContinuityPolicy } from './context-continuity-B9n0t0v-.js';
+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 { R as ResolvedAuthSpec, D as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './spawn-defaults-7uHRnYH1.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-7uHRnYH1.js';
+import { R as ResolvedAuthSpec, D as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './spawn-defaults-DVgmfxWo.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-DVgmfxWo.js';
 import { CatalogModelsQuery, CatalogModelsResponse } from './catalog-models.js';
 export { CatalogAdapterInput, CatalogAdapterModelInput, CatalogPricing, CatalogProduct, CatalogRoute, CatalogRouteSummary, CatalogVendor, buildCatalogModels } from './catalog-models.js';
 import { FooterSession } from './pr-provenance.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SandboxProvider } from '@agentproto/sandbox';
+import { BrainManager, ExportedSessionLike } from '@agentproto/workspace-brain';
+export { BrainManager, BrainStats, IngestReport, IngestResult } from '@agentproto/workspace-brain';
 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';
@@ -1659,7 +1661,7 @@ declare function createTaskLedger(opts: {
  * and session_monitor MCP tool (long-poll multiplexed).
  */
 
-type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:permission-request" | "session:permission-resolved" | "session:exited" | "session:reaped" | "session:stalled" | "session:stall-cleared" | "session:resumed" | "session:spawned" | "session:command-done" | "session:model-changed" | "session:config-changed" | "session:renamed" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed" | "cron:fired" | "cron:succeeded" | "cron:failed" | "activity:changed" | "task:changed";
+type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:awaiting-input-flagged" | "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";
 /**
  * Fixed severity vocabulary for a judge-gate finding (WP-D). Deliberately
  * small and fixed so `policy_status` output is comparable across different
@@ -1741,6 +1743,39 @@ interface SessionAwaitingInputEvent {
     ts: string;
     question?: SessionAwaitingQuestion;
 }
+/**
+ * Emitted by `SessionsRegistry.flagAwaitingInput` (the `session_flag_status`
+ * MCP verb) when something EXTERNAL — a human, another agent, the future
+ * session watchdog — manually corrects a session's `awaitingInput`/
+ * `awaitingQuestion` classification, overriding (or confirming) what the
+ * internal heuristic (`deriveHeuristicQuestion`) or a driver-reported
+ * `agent-prompt` last set. Distinct from `session:awaiting-input` (which only
+ * ever fires when the flag flips TRUE, from the daemon's own turn-end
+ * detection): this fires for BOTH directions of a manual override, always
+ * carries the mandatory `reason` the caller gave (audit trail — this is the
+ * one write path for this field with no automatic sensor behind it), and
+ * `awaitingInput` states the value the override just set rather than being
+ * implied by the event firing at all. Same bus distribution as every other
+ * lifecycle event (`session_events_poll`, the webhook notifier, the routine
+ * engine, `session_monitor`).
+ */
+interface SessionAwaitingInputFlaggedEvent {
+    type: "session:awaiting-input-flagged";
+    sessionId: string;
+    awaitingInput: boolean;
+    /** Required justification the caller passed to `session_flag_status` —
+     *  why this override was made. */
+    reason: string;
+    label?: string;
+    ts: string;
+    /** Present only when `awaitingInput:true` and a `question` was attached —
+     *  mirrors the descriptor's `awaitingQuestion` after the override, same
+     *  shape as every other site that sets it (`source: "structured"`, since a
+     *  manual override is at least as authoritative as a driver-reported
+     *  prompt). Absent when `awaitingInput:false` (the override always clears
+     *  any prior question in that case) or when no `question` was given. */
+    question?: SessionAwaitingQuestion;
+}
 /**
  * Emitted when a permission-hold session parks a `session/request_permission`
  * (see the pending-permissions inbox in sessions.ts). `permissionId` is the
@@ -1847,6 +1882,94 @@ interface SessionStallClearedEvent {
     label?: string;
     ts: string;
 }
+/**
+ * Emitted by the wait long-poll helper (`monitorSessionWait`) the moment a
+ * blocking wait actually SUBSCRIBES to this session — a `/sessions/:id/wait`
+ * long-poll or a `session_monitor` call that has to park. This is the bus
+ * twin of the ephemeral `watchers` descriptor counter (`incWatchers`,
+ * #session-visibility): where the counter lets `session_list` surface "N
+ * supervisors are blocked on this session", the event lets a LIVE consumer
+ * (the transcript panel inside the WATCHED session) react the instant a
+ * watcher appears rather than on its next descriptor poll. Detection +
+ * signal ONLY — nothing here changes the wait's own semantics. `watchers`
+ * is the counter AFTER the attach (read back from the registry, so a
+ * concurrent waiter is already reflected). `watcherSessionId` names the
+ * supervising session when the wait was initiated by one (the scoped
+ * orchestrator's `callerScope.ownerSessionId`); `label` is that session's
+ * label/title, resolved once at attach time (a best-effort snapshot, not
+ * live). Both absent for an anonymous CLI/HTTP waiter. Same bus distribution
+ * as every other lifecycle event (`session_events_poll`, the webhook
+ * notifier, the routine engine, `session_monitor`). Paired with
+ * `session:watcher-detached` when the wait resolves or times out.
+ */
+interface SessionWatcherAttachedEvent {
+    type: "session:watcher-attached";
+    sessionId: string;
+    watchers: number;
+    watcherSessionId?: string;
+    label?: string;
+    ts: string;
+}
+/**
+ * Emitted when a blocking wait on this session releases its watcher — the
+ * wait resolved (a matching lifecycle event landed) or timed out; see
+ * {@link SessionWatcherAttachedEvent}. `watchers` is the counter AFTER the
+ * detach, so a consumer can tell "the last watcher left" (`0`) from "one of
+ * several left". Detection + signal only — a zero count does NOT imply the
+ * session is unsupervised in every sense (a completion policy watches via
+ * its own mechanism, not this counter); it only means no `monitorSessionWait`
+ * long-poll is currently parked on it. Same bus distribution as every other
+ * lifecycle event.
+ */
+interface SessionWatcherDetachedEvent {
+    type: "session:watcher-detached";
+    sessionId: string;
+    watchers: number;
+    watcherSessionId?: string;
+    label?: string;
+    ts: string;
+}
+/**
+ * Emitted at turn-end when the turn that just finished started one or more
+ * BACKGROUND tool calls (a tool-call whose `arguments` object carries
+ * `run_in_background: true` — how Claude Code's Bash announces a
+ * `run_in_background` task; matched generically on the property, not the
+ * tool name) AND the session is NOT `awaitingInput`. The target failure
+ * mode is the turn-END twin of `session:stalled`: the harness's own
+ * task-completion notification does NOT trigger a new turn, so the session
+ * sits `busy:false`, `awaitingInput:false`, background tasks pending — a
+ * silent dead end that looks exactly like a session idle and waiting to be
+ * re-prompted. Detection + signal ONLY: nothing here re-prompts or wakes
+ * the session (no auto-wake — a wake-up path would have to decide what to
+ * say, and that policy belongs to the supervisor, not the daemon). `count`
+ * is how many background tool starts the turn observed. Same bus
+ * distribution as every other lifecycle event (`session_events_poll`, the
+ * webhook notifier, the routine engine, `session_monitor`). Paired with
+ * `session:bg-tasks-cleared` when the flag is later cleared.
+ */
+interface SessionBgTasksParkedEvent {
+    type: "session:bg-tasks-parked";
+    sessionId: string;
+    count: number;
+    label?: string;
+    ts: string;
+}
+/**
+ * Emitted when a session's `pendingBgTasks` flag (see {@link
+ * SessionBgTasksParkedEvent}) is cleared — by the next turn starting (the
+ * session was re-prompted, so it is no longer parked: its new turn will see
+ * whatever the background tasks produced) or by the session exiting (a dead
+ * row carries no live flag). Does NOT imply the background tasks finished
+ * or their output was consumed — only that the "ended its turn with
+ * background work pending and no wake-up path" condition no longer holds.
+ * Same bus distribution as every other lifecycle event.
+ */
+interface SessionBgTasksClearedEvent {
+    type: "session:bg-tasks-cleared";
+    sessionId: string;
+    label?: string;
+    ts: string;
+}
 /**
  * Emitted when a dead agent-cli row is brought back IN PLACE — same session
  * id, same descriptor — by the lazy resume-on-prompt path (`maybeResumeAgent`)
@@ -1975,6 +2098,24 @@ interface SessionRenamedEvent {
     renamedByUser?: boolean;
     ts: string;
 }
+/**
+ * Emitted when an operator pins or unpins a session for list visibility
+ * (`POST /sessions/:id/pin`, the `session_set_pinned` MCP verb). Like
+ * `session:renamed`, this is NOT a `SessionConfig` axis — pinning never
+ * touches the live agent, the idle-reaper, or any notification path, it's
+ * purely a `SessionDescriptor.pinned` display/sort flag — so it rides its
+ * own event rather than `session:config-changed`. `pinned` carries the value
+ * now on the descriptor. Same bus distribution as every other lifecycle event
+ * (`session_events_poll`, the webhook notifier, the routine engine), which is
+ * how a live UI (the VS Code sessions webview) learns to resort its list
+ * without waiting for its next snapshot poll.
+ */
+interface SessionPinnedEvent {
+    type: "session:pinned-changed";
+    sessionId: string;
+    pinned: boolean;
+    ts: string;
+}
 /**
  * Emitted when a session is first registered in the registry (WP-R3) — both
  * the agent-cli spawn path (`spawnAgent`) and the terminal path (`spawnPty`).
@@ -2097,7 +2238,7 @@ interface TaskChangedEvent {
     sessionId?: string;
     ts: string;
 }
-type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | SessionExitedEvent | SessionReapedEvent | SessionStalledEvent | SessionStallClearedEvent | SessionResumedEvent | SessionSpawnedEvent | SessionCommandDoneEvent | SessionModelChangedEvent | SessionConfigChangedEvent | SessionRenamedEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent | ActivityChangedEvent | TaskChangedEvent;
+type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionAwaitingInputFlaggedEvent | 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;
 interface SessionEventBus {
     emit(ev: SessionEvent): void;
     /** Subscribe to a specific event type. Returns an unsubscribe fn. */
@@ -3524,6 +3665,14 @@ type AgentAdapterResolver = (slug: string) => Promise<{
     startSession(opts: {
         cwd: string;
         resumeSessionId?: string;
+        /** Persistent isolated-config location for the adapter (claude-code's
+         *  `CLAUDE_CONFIG_DIR`) — forwarded to the driver's
+         *  `start({ configDir })`. The daemon keys it per session lineage
+         *  (`SessionDescriptor.adapterConfigDir`) so the provider's own
+         *  conversation store survives adapter respawns and `resumeSessionId`
+         *  can restore full context instead of falling back to a digest.
+         *  Adapters that don't isolate a config dir ignore it. */
+        configDir?: string;
         /**
          * Manifest-declared mode id forwarded from `agent_start` (AIP-45
          * `AgentCliHandle.modes` — e.g. claude-code's `plan` /
@@ -3748,7 +3897,7 @@ type AdapterCapabilitiesLister = (opts?: {
 interface AdapterInstallResult {
     slug: string;
     ok: boolean;
-    method: "npm-global" | "agentproto-install" | "already-installed" | "unsupported";
+    method: "npm-global" | "shell-hint" | "agentproto-install" | "already-installed" | "unsupported";
     /** Human-readable one-liner: what ran, and how it ended. */
     message: string;
     /** The shell command that was run, for surfacing in logs / errors.
@@ -3760,6 +3909,12 @@ interface AdapterInstallResult {
      *  post-install re-list failed (the install itself may still have
      *  succeeded — read `ok`). */
     status?: "supported" | "available" | "ready" | "unresolvable";
+    /** True when the install failed ONLY because a manifest setup step
+     *  declares `interactive: true` and this process has no TTY to run it
+     *  in (e.g. openclaw's `onboard --install-daemon` TUI). The remedy is a
+     *  real terminal — `agentproto setup <slug>` — which a UI can offer
+     *  directly as a PTY terminal session. */
+    needsInteractiveSetup?: boolean;
 }
 /**
  * Installs an agent CLI adapter by slug and reports the outcome. Wired by
@@ -4022,6 +4177,8 @@ interface AgentStreamEvent {
      *  @agentproto/acp's `StreamEvent`'s `agent-prompt` kind. Harness-shaped
      *  and untyped; don't assume a stable schema across adapters. */
     rawInput?: unknown;
+    /** "plan" event title — see @agentproto/acp's `StreamEvent`'s `plan` kind. */
+    title?: string;
     /** "plan" event entries — see @agentproto/acp's `StreamEvent`'s `plan` kind. */
     entries?: Array<{
         content: string;
@@ -4089,6 +4246,7 @@ declare const SESSION_ID_ENV = "AGENTPROTO_SESSION_ID";
 declare const WORKSPACE_SLUG_ENV = "AGENTPROTO_WORKSPACE_SLUG";
 type SessionKind = "terminal" | "agent-cli" | "command" | "browser";
 type SessionStatus = "starting" | "running" | "exited" | "killed" | "error";
+type SessionCurrentPhase = "thinking" | `tool-call:${string}` | "awaiting-input" | "awaiting-permission" | "idle" | "completed" | "killed";
 /**
  * The billing-auth resolver's OBSERVABLE echo, recorded on a session
  * descriptor. `mode` + `fingerprint` are always present when recorded (a
@@ -4122,6 +4280,48 @@ interface SessionAccessProfileEcho {
     endpoint: string;
     method: AuthMethod;
 }
+/**
+ * One live waiter behind a session's {@link SessionDescriptor.watchers} count
+ * (#session-visibility). Captured at `monitorSessionWait` attach time and held
+ * only for the life of that wait — never persisted, never updated in place
+ * (a snapshot of the waiter's label at attach time, not a live mirror of it).
+ */
+interface SessionWatcherInfo {
+    /** The waiting session's id, when this wait was initiated by an agent
+     *  session via the orchestrator scope (`callerScope.ownerSessionId`).
+     *  Absent for an anonymous CLI/HTTP waiter — it still counts toward
+     *  `watchers`, it just can't be named. */
+    watcherSessionId?: string;
+    /** Best-effort label/title for `watcherSessionId`, resolved once at attach
+     *  time. A later rename of the watching session is not reflected. */
+    watcherLabel?: string;
+    /** What this wait is blocking on — mirrors `session_monitor`'s `event`
+     *  parameter (`SessionWaitEvent` in orchestration-tools.ts; kept as a plain
+     *  string here so the registry doesn't depend on the tool-layer type). */
+    event: string;
+    /** The wait's configured timeout, ms — absent for the MCP tool's default. */
+    timeoutMs?: number;
+    /** ISO 8601 timestamp this waiter attached. */
+    since: string;
+}
+/** One prompt waiting in `SessionDescriptor.promptQueue` — see that
+ *  field's doc for the FIFO/force ordering contract. */
+interface QueuedPrompt {
+    /** Stable id, assigned at queue time (by the HTTP layer for
+     *  `POST /sessions/:id/prompt`'s `queue` arm so the caller can echo it
+     *  straight back in the response, or minted here for any other
+     *  caller). Used by `removeQueuedPrompt` to cancel this one item
+     *  before it dispatches. */
+    id: string;
+    /** Same shape `runAgentTurn`'s `message` parameter accepts — a raw
+     *  string or an ACP content block/array. */
+    message: unknown;
+    /** ISO 8601 timestamp this item was queued. */
+    queuedAt: string;
+    /** Same as `enqueuePrompt`'s `opts.source` — carried through to the
+     *  turn this item eventually becomes. */
+    source?: string;
+}
 interface SessionDescriptor {
     id: string;
     kind: SessionKind;
@@ -4184,6 +4384,18 @@ interface SessionDescriptor {
      *  `lastOutputAt` goes stale. Updated on incoming session/update
      *  notifications AND on outbound RPC calls. ISO 8601. */
     lastActivityAt?: string;
+    /** Read-time projection of what the session is doing now. Tool-call phases
+     *  carry the adapter-reported tool name (for example
+     *  `tool-call:file_read`). Ephemeral: recomputed by list()/get() and never
+     *  persisted. */
+    currentPhase?: SessionCurrentPhase;
+    /** Whole seconds since `lastActivityAt`, computed at read time. Absent until
+     *  the adapter has reported activity; never persisted. */
+    secondsSinceLastActivity?: number;
+    /** Number of distinct tool calls observed in the current (or most recently
+     *  completed) turn. Reset when the next turn starts. Tool-call enrichment
+     *  events sharing an id count only once. Ephemeral and never persisted. */
+    toolCallsThisTurn?: number;
     /** 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
@@ -4199,6 +4411,15 @@ interface SessionDescriptor {
      *  daemon restart). 0/absent ⇒ nothing is watching. Lets a UI mark a
      *  session "supervised — notify on turn-end". */
     watchers?: number;
+    /** Per-waiter detail behind the {@link watchers} count — who is blocked on
+     *  this session and what they're blocked on. Same lifetime/source as
+     *  `watchers` (stamped at read time from the registry's live waiter list,
+     *  never persisted); empty/absent ⇒ nothing is watching. An anonymous
+     *  CLI/HTTP waiter (no `callerScope`) carries no `watcherSessionId` — it
+     *  still counts, it just can't be named. Lets a UI answer "who is watching
+     *  this, and what are they waiting for" without guessing from the bare
+     *  count. */
+    watcherDetails?: readonly SessionWatcherInfo[];
     /** Count of DESCENDANT sessions (children, grandchildren, …) currently
      *  mid-turn, derived at read time from the `parentSessionId` lineage
      *  (#session-visibility, subtree rollup). Lets a UI show an idle parent that
@@ -4234,6 +4455,38 @@ interface SessionDescriptor {
      *  stalled. Detection + signal only — nothing here kills or restarts the
      *  session. */
     stalledSinceMs?: number;
+    /** Counted background tool starts in the last turn; the session ended its
+     *  turn without a wake-up path — likely parked. Stamped at turn-end when
+     *  the turn observed one or more tool-calls whose `arguments` object
+     *  carries `run_in_background: true` (how Claude Code's Bash announces a
+     *  background task — matched generically on the property, not the tool
+     *  name) AND the session is not `awaitingInput`. The harness's own
+     *  task-completion notification does NOT trigger a new turn, so the
+     *  session sits `busy:false`, `awaitingInput:false`, background tasks
+     *  pending — a silent dead end. Detection + signal ONLY (same doctrine
+     *  as `stalledSinceMs`): nothing here re-prompts or wakes the session.
+     *  Cleared (deleted, never a stale value) on the next turn start and on
+     *  session exit. Emits `session:bg-tasks-parked` /
+     *  `session:bg-tasks-cleared`. */
+    pendingBgTasks?: number;
+    /** ISO 8601 timestamp of the last turn that ended because the ADAPTER
+     *  ITSELF reported a failure — `runAgentTurn` observed a `turn-end` event
+     *  with `reason:"error"` (session-event-bus.ts's `SessionTurnEndEvent`,
+     *  e.g. a refused/errored ACP `stopReason` — see adapters/mastra-agent's
+     *  host) — as opposed to a thrown/rejected adapter stream, which flips
+     *  `status` to `"error"` directly (a genuinely terminal row the existing
+     *  crash/error handling already catches). This is the twin gap for a
+     *  turn that fails IN-BAND while the process stays alive: `status` stays
+     *  `"running"`, `lastError` stays unset (reserved for `markCrashed`), and
+     *  nothing else distinguishes the session from one that simply finished
+     *  a clean turn and is idle. Folded into the same "stalled" activity/UI
+     *  treatment a mid-turn stall gets (see sessionsTree.logic.ts's
+     *  `activityFor`) rather than a new state, on the theory that both mean
+     *  "the last thing this session did needs a look, not a re-prompt on
+     *  faith". Stamped at turn-end when `turnEndReason === "error"`; cleared
+     *  the moment a LATER turn completes without one (same reset shape as
+     *  `resumeAttempts`/`restartAttempts`). Detection + signal only. */
+    lastTurnErroredAt?: string;
     /** DERIVED, read-time only (never persisted — stripped by `snapshotRows`,
      *  stamped by `stampInterrupted` in list()/get()/findByIdOrName). True when
      *  this session died with a turn in flight under a daemon restart —
@@ -4360,6 +4613,17 @@ interface SessionDescriptor {
      *  `session_set_keepalive` (`registry.setKeepAlive`). Absent (not `false`)
      *  for every session that hasn't opted in. */
     keepAlive?: boolean;
+    /** Server-persisted, list-visibility-only favorite flag — set/cleared via
+     *  `session_set_pinned` (`registry.setPinned`) or `POST /sessions/:id/pin`.
+     *  Purely a sort/display concern: pinned sessions sort to the top of the
+     *  session list (CLI table, VS Code webview's dedicated "Pinned" group).
+     *  Deliberately orthogonal to — and must NEVER be confused with —
+     *  `keepAlive` (idle-reaper exemption, operational), the VS Code
+     *  extension's client-side-only "watch" eye (toast notifications, never
+     *  persisted here), or `watchers` (live supervisor wait count). No side
+     *  effects on reaping, notifications, or anything else. Absent (not
+     *  `false`) for every session that hasn't been pinned. */
+    pinned?: boolean;
     /** True when the session was spawned under a real PTY (node-pty)
      *  instead of `child_process.spawn`. PTY sessions carry raw ANSI
      *  bytes (alt-screen, key bindings, colors); attach goes through
@@ -4431,6 +4695,23 @@ interface SessionDescriptor {
      *  `adapterSlug`, recorded under the canonical axis name. Falls back to
      *  `adapterSlug` when not explicitly set. Undefined for pty/command kinds. */
     harness?: string;
+    /**
+     * How this adapter's spawn ROUTE relates to the chosen model (AIP-45
+     * launch-menu drill-down). `"derived-from-model"` means the endpoint falls
+     * out of the model id's own vendor prefix; `"free"`/omitted means the route
+     * is an independent choice. Recorded at spawn time so a live `setModel` can
+     * apply the same wire normalization the spawn path used.
+     */
+    routeSelection?: "free" | "derived-from-model";
+    /**
+     * The adapter manifest's provider (`authDescriptor.provider`) — e.g.
+     * `"anthropic"` for claude-code, `"openai"` for codex. Recorded at spawn
+     * time so a live `setModel` knows when it can safely bare a
+     * `vendor/product` direct ref; ignored for derived-from-model adapters.
+     * Distinct from `auth.provider`, which is the resolved billing wallet and
+     * may name a gateway route.
+     */
+    adapterProvider?: string;
     /**
      * AIP-45 mode the session was spawned with (`AgentCliStartOptions.config.
      * mode` — e.g. claude-code's `plan`/`accept-edits`, a gateway preset mode
@@ -4505,6 +4786,17 @@ interface SessionDescriptor {
      *  via sessions.json so `restart` can pass it as `resumeSessionId`
      *  and reattach to the prior conversation history. */
     adapterSessionId?: string;
+    /** Persistent isolated-config dir handed to the adapter at spawn time
+     *  (`startSession({ configDir })` → claude-code's `CLAUDE_CONFIG_DIR`).
+     *  Keyed by the FIRST session id in a restart lineage
+     *  (`adapterConfigDirFor`) and carried forward verbatim across
+     *  restarts/lazy resumes — the provider's own conversation store lives
+     *  inside it, so reusing the SAME dir is what lets `resumeSessionId`
+     *  restore full context after the adapter process died (before this,
+     *  each respawn minted a fresh temp dir and native resume always
+     *  degraded to the daemon-transcript digest). Absent on legacy rows and
+     *  adapters that don't isolate a config dir. */
+    adapterConfigDir?: 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
@@ -4604,6 +4896,23 @@ interface SessionDescriptor {
      *  message (`runAgentTurn`) — so delivery survives a busy parent without
      *  ever cancelling its in-flight work. Absent when nothing is queued. */
     pendingChildCrashNotices?: string[];
+    /** FIFO of prompts that arrived while this session was mid-turn and
+     *  asked to be QUEUED rather than rejected (`enqueuePrompt`'s
+     *  `opts.queue` arm — see its doc comment). Index 0 is next to
+     *  dispatch. A plain queued item is appended to the back; a
+     *  `force`-queued one is inserted at the front, jumping everything
+     *  already waiting WITHOUT cancelling the live turn (that's what
+     *  `interrupt` is for). Drained one item at a time, in this order, by
+     *  `dispatchQueuedPrompt` at the end of every `runAgentTurn` — never
+     *  by the caller that queued it, which already returned. Always
+     *  replaced with a NEW array reference on every mutation (push, drain,
+     *  removal), never mutated in place — the VS Code webview's
+     *  `sessionDescriptorsEqual` diff is a shallow `!==` per field, so an
+     *  in-place `.shift()` here would silently stop propagating queue
+     *  changes to the transcript panel. `[]` (not absent) once anything
+     *  has ever been queued, matching `pendingChildCrashNotices`'s
+     *  convention above. */
+    promptQueue?: QueuedPrompt[];
     /** Best-effort context-handoff digest (Fix D), stashed on a descriptor
      *  whose resume degraded to a BLANK spawn — the adapter's own
      *  conversation store was missing, or the adapter declared `resumable:
@@ -4742,6 +5051,9 @@ interface SessionSummary {
     killedMidTurn?: boolean;
     lastOutputAt?: string;
     lastActivityAt?: string;
+    currentPhase?: SessionCurrentPhase;
+    secondsSinceLastActivity?: number;
+    toolCallsThisTurn?: number;
     processAlive?: boolean;
     /** Live supervisor waiter count (#session-visibility) — see
      *  `SessionDescriptor.watchers`. Ephemeral, stamped at read time. */
@@ -4755,6 +5067,7 @@ interface SessionSummary {
     activitySummary?: SessionActivitySummary;
     archived?: boolean;
     keepAlive?: boolean;
+    pinned?: boolean;
     pty?: boolean;
     name?: string;
     argv?: readonly string[];
@@ -4777,6 +5090,14 @@ interface SessionSummary {
     busy?: boolean;
     blockedOn?: "subagent" | "command";
     stalledSinceMs?: number;
+    /** Parked-with-background-tasks marker — see
+     *  `SessionDescriptor.pendingBgTasks`. Stamped at turn-end, cleared on the
+     *  next turn start / exit. */
+    pendingBgTasks?: number;
+    /** Adapter-reported turn-error marker — see
+     *  `SessionDescriptor.lastTurnErroredAt`. Stamped at turn-end, cleared on
+     *  the next turn that completes without one. */
+    lastTurnErroredAt?: string;
     origin?: string;
     parentSessionId?: string;
     depth?: number;
@@ -5072,11 +5393,41 @@ interface SessionsRegistry {
      *  `false` reproduces today's mid-turn rejection byte-for-byte. */
     /** `opts.source` on either prompt verb is the turn's provenance
      *  (`agent:<sessionId>` when another session injected it — see
-     *  `SessionObserver.recordPrompt`); recording-only, never behavioral. */
+     *  `SessionObserver.recordPrompt`); recording-only, never behavioral.
+     *
+     *  `opts.queue` is the FIFO arm (additive, opt-in — omitted/false
+     *  reproduces the byte-for-byte busy rejection above, unchanged):
+     *  when the session is mid-turn AND `queue` is true, the prompt is
+     *  appended to `SessionDescriptor.promptQueue` instead of being
+     *  rejected, and this resolves immediately WITHOUT dispatching
+     *  anything — `dispatchQueuedPrompt` fires it once the current (and
+     *  any earlier-queued) turns finish. `opts.force` only matters
+     *  alongside `queue`: it inserts at the FRONT of the queue instead of
+     *  the back, jumping everything already waiting, but — unlike
+     *  `interrupt` — never touches the live turn. `opts.queueId` lets the
+     *  caller pin the queued item's id up front (the HTTP layer does this
+     *  so it can echo the id straight back in its response); omitted, one
+     *  is minted here. On an IDLE session `queue`/`force`/`queueId` are
+     *  no-ops — admission falls straight through to the normal dispatch
+     *  path below, identical to `queue` omitted. `interrupt` is checked
+     *  first: an `{interrupt: true, queue: true}` pair interrupts (never
+     *  queues) exactly like `interrupt` alone. */
     enqueuePrompt(id: string, message: unknown, opts?: {
         interrupt?: boolean;
         source?: string;
+        queue?: boolean;
+        force?: boolean;
+        queueId?: string;
     }): Promise<void>;
+    /** Cancel one not-yet-dispatched item in `SessionDescriptor.promptQueue`
+     *  by id — the composer's per-item "remove" action. Idempotent: an
+     *  unknown session or an id that's already gone (dispatched, already
+     *  removed, or never existed) resolves `{removed: false}` rather than
+     *  throwing, same shape as `interruptSession`'s no-op-is-not-an-error
+     *  contract. */
+    removeQueuedPrompt(id: string, queueId: string): {
+        removed: boolean;
+    };
     /** Eagerly resume ONE dead-but-resumable agent-cli session IN PLACE,
      *  WITHOUT a prompt — the boot-time counterpart to the lazy resume that
      *  `sendPrompt`/`enqueuePrompt` trigger on the first prompt after a restart
@@ -5220,11 +5571,17 @@ interface SessionsRegistry {
      *  ephemeral `watchers` counter surfaced on the descriptor at read time.
      *  Called by `monitorSessionWait` when a `/sessions/:id/wait` long-poll or
      *  `session_monitor` subscription actually blocks. A no-op for an unknown id
-     *  is fine (the wait may outlive the row). */
-    incWatchers(id: string): void;
+     *  is fine (the wait may outlive the row). `detail`, when passed, is held
+     *  (by reference) alongside the count and surfaced as
+     *  `SessionDescriptor.watcherDetails` — pass the SAME object reference to
+     *  the matching {@link decWatchers} call so removal is exact. */
+    incWatchers(id: string, detail?: SessionWatcherInfo): void;
     /** Balance an {@link incWatchers} when the waiter resolves or times out.
-     *  Clamps at 0 and drops the map entry at zero so the counter can't leak. */
-    decWatchers(id: string): void;
+     *  Clamps at 0 and drops the map entry at zero so the counter can't leak.
+     *  Pass the same `detail` reference given to `incWatchers` to remove it from
+     *  `watcherDetails`; omitted/mismatched detail leaves the count balanced but
+     *  the detail list untouched (defensive — should not happen in practice). */
+    decWatchers(id: string, detail?: SessionWatcherInfo): void;
     /** Archive a TERMINAL-status session (exited/killed/error) — sets
      *  `archived: true` and persists. Pure housekeeping: hides the row from
      *  `list()`'s default view, nothing else. Refuses (throws) a still-alive
@@ -5274,6 +5631,45 @@ interface SessionsRegistry {
      *  policy state — never touches the live agent. Throws when the id is
      *  unknown. */
     setKeepAlive(id: string, keepAlive: boolean): SessionDescriptor;
+    /** Set or clear a session's list-visibility pin (the `session_set_pinned`
+     *  MCP verb / `POST /sessions/:id/pin`). `true` flips
+     *  `SessionDescriptor.pinned` on — pure sort/display state for the CLI
+     *  table and the VS Code webview's list, which sort a pinned session to
+     *  the top. `false` clears it. Persists via the same `schedulePersist`
+     *  every descriptor mutation uses and emits `session:pinned-changed` so a
+     *  live UI resorts without waiting for its next snapshot poll. NEVER
+     *  touches `keepAlive`, reaper eligibility, or any notification path —
+     *  pin is quiet, structural state only. Throws when the id is unknown. */
+    setPinned(id: string, pinned: boolean): SessionDescriptor;
+    /**
+     * Manually override `awaitingInput`/`awaitingQuestion` (the
+     * `session_flag_status` MCP verb) — the ONE write path for this pair
+     * besides the internal heuristic (`deriveHeuristicQuestion`) and a
+     * driver-reported `agent-prompt`, both of which only ever run inside a
+     * live turn. Lets a human, another agent, or the session watchdog correct
+     * a missed real question (`awaitingInput:true`, optionally attaching
+     * `question`) or clear a false positive (`awaitingInput:false`).
+     * `awaitingInput:false` ALWAYS clears `awaitingQuestion` too, regardless
+     * of what `question` was passed — a question cannot outlive its
+     * awaiting-input flag. When `question` is given alongside `true`, it's
+     * stored as `{ text: question, source: "structured" }` (an explicit
+     * override is at least as authoritative as a driver-reported prompt).
+     * Guard mirrors the INVERSE of `archiveSession`'s: only a LIVE session
+     * (running/starting) may be flagged — a terminal session has no turn left
+     * to be "awaiting" anything, so correcting it there would be fiction with
+     * nothing downstream (`session_monitor`, the webhook notifier) to observe
+     * it. Persists via `schedulePersist` and emits
+     * `session:awaiting-input-flagged` (carrying the required `reason`) so
+     * the correction is visible via `session_events_poll` same as every other
+     * lifecycle event. Cleared automatically like any other awaiting-input
+     * signal on the session's next prompt/turn start. Throws when the id is
+     * unknown or the session is terminal.
+     */
+    flagAwaitingInput(id: string, patch: {
+        awaitingInput: boolean;
+        question?: string;
+        reason: string;
+    }): SessionDescriptor;
     /** Subscribe to a session's output. Returns an unsubscribe fn.
      *  Initial backfill: synchronously invokes `onLine` once for each
      *  line currently in the ring buffer so attaches show context. */
@@ -5524,6 +5920,14 @@ interface SpawnAgentInput {
     nativeTerminalResume?: boolean;
     /** Canonical harness slug — recorded on the descriptor; defaults to adapterSlug. */
     harness?: string;
+    /** Manifest-declared `routeSelection` (AIP-45) — recorded verbatim onto
+     *  {@link SessionDescriptor.routeSelection} so live `setModel` can apply
+     *  the same wire normalization as spawn. */
+    routeSelection?: "free" | "derived-from-model";
+    /** Manifest-declared provider (`authDescriptor.provider`) — recorded onto
+     *  {@link SessionDescriptor.adapterProvider} so live `setModel` knows when
+     *  to bare a direct `vendor/product` ref; ignored for derived adapters. */
+    adapterProvider?: string;
     /** Optional initial prompt to dispatch immediately. The promise
      *  the registry returns resolves AFTER the spawn — the prompt
      *  runs in the background, projecting events into the ring
@@ -5541,6 +5945,12 @@ interface SpawnAgentInput {
      *  the resume/re-spawn path can re-mount the same toolset (orchestrator
      *  WP1). */
     mcpServers?: AcpMcpServer[];
+    /** Persistent isolated-config dir this spawn passed to
+     *  `startSession({ configDir })` — recorded verbatim onto
+     *  {@link SessionDescriptor.adapterConfigDir} so restart/lazy-resume can
+     *  point the respawned adapter back at the SAME dir (where the provider's
+     *  conversation store lives). See that field's doc. */
+    adapterConfigDir?: string;
     /** 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. */
@@ -6120,6 +6530,212 @@ 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.
+ *
+ * Three tools over the shared {@link WorkspaceBrains} registry:
+ *
+ *   - `workspace_brain_query`  — BM25 recall over a workspace's ingested
+ *                                conversations (dispatch to the provider).
+ *   - `workspace_brain_status` — how many sessions a workspace has ingested.
+ *   - `workspace_brain_ingest` — manually trigger ingestion (a session, or
+ *                                every known-but-uningested session).
+ *
+ * Every tool resolves its target workspace the same way: an explicit
+ * `workspace` argument wins; otherwise the calling session's own workspace is
+ * used (from its descriptor's `workspaceSlug`). Resolution applies the bucket
+ * membership rule, so an unregistered slug degrades to `default` rather than
+ * pointing a brain at an arbitrary path.
+ */
+
+interface RegisterBrainToolsOptions {
+    /** The shared per-workspace brain registry. */
+    brains: WorkspaceBrains;
+    /** Registry used to resolve the calling session's own workspace. */
+    registry: SessionsRegistry;
+    /** The calling agent session id (from `?callerSessionId=` on `/mcp`). */
+    callerSessionId?: string;
+}
+declare function registerBrainTools(server: McpServer, opts: RegisterBrainToolsOptions): void;
+
+/**
+ * Workshop-brain subscriber — auto-ingest a workspace's conversations when its
+ * sessions exit.
+ *
+ * Subscribes to `session:exited` on the {@link SessionEventBus} and, after a
+ * short debounce, fire-and-forgets an ingestion of each freshly-exited session
+ * into its workspace's brain. The debounce batches a flurry of exits (e.g. an
+ * orchestrator tearing down N children at once) into one pass instead of N
+ * index rebuilds.
+ *
+ * Mirrors `webhook-notifier.ts`'s containment discipline: the handler never
+ * throws into the bus's hot path — every error is swallowed and logged, so a
+ * brain hiccup can never take down an exit event.
+ */
+
+interface WorkspaceBrainSubscriberOptions {
+    readonly bus: SessionEventBus;
+    /** The shared brain registry. */
+    readonly brains: WorkspaceBrains;
+    /** Debounce window for batching consecutive exits. Default 5000ms. */
+    debounceMs?: number;
+}
+interface WorkspaceBrainSubscriber {
+    /** Wire the handler onto the bus (idempotent). */
+    start(): void;
+    /** Unsubscribe (idempotent). */
+    stop(): void;
+    /** Flush any pending (not-yet-debounced) exits now. */
+    flush(): void;
+}
+declare function createWorkspaceBrainSubscriber(opts: WorkspaceBrainSubscriberOptions): WorkspaceBrainSubscriber;
+
+/**
+ * `~/.agentproto/harness-presets.json` — the persisted harness→profile binding
+ * (mode 0600). A {@link HarnessPreset} names, per adapter harness, WHICH auth
+ * profile and default model a fresh spawn should bill through, so the operator
+ * no longer re-picks the profile every time (today that link lives only
+ * ephemerally per-session `setSessionAccessProfile` or per-spawn in the
+ * Configuration Lab picker).
+ *
+ * This is a POINTER store, like `auth-profiles.json` and
+ * `llm-endpoint-links.json`, not a secret store: an entry holds a `profileRef`
+ * (an {@link AuthProfile} id) and a `defaultModel` string, never a credential —
+ * so it needs no encryption. It reuses the exact persistence primitives the
+ * sibling stores established (a versioned JSON file under `~/.agentproto/`,
+ * `node:fs/promises`, mode 0600, whole-file write) — see
+ * `user-presets.ts` / `profile-store.ts` / `llm-endpoint-links-store.ts`.
+ *
+ * Invariants enforced on write (validated once, at this boundary, for every
+ * CLI/MCP/editor caller):
+ *   • at most one `isDefault: true` per `harnessSlug` — the spawn path reads
+ *     exactly one default per harness (see `getDefaultHarnessPreset`);
+ *   • `profileRef` must reference an EXISTING, ENABLED auth profile — a dangling
+ *     or disabled profile can never become the silent default a spawn bills;
+ *   • `defaultModel` must be serviceable by that profile's curation allowlist
+ *     (a `mode: "allow"` profile only bills the models it lists).
+ * The profile lookup is injected ({@link HarnessPresetValidationDeps}) so the
+ * store is testable without touching the real auth-profile store; it defaults
+ * to `@agentproto/auth`'s `getAuthProfile`.
+ */
+
+/**
+ * A persisted harness→profile binding: for one adapter harness, which auth
+ * profile + default model a fresh spawn bills through when the caller pins
+ * neither explicitly.
+ */
+interface HarnessPreset {
+    /** Stable, machine-local id — unique across all presets (e.g. `hm-cheap`). */
+    id: string;
+    /** Adapter harness slug this preset binds (e.g. `hermes`). Matched against a
+     *  spawn's `harness ?? adapter`. */
+    harnessSlug: string;
+    /** Human-readable display name (e.g. `Cheap`). */
+    name: string;
+    /** The {@link AuthProfile} id this preset bills through — must exist and be
+     *  enabled at write time. */
+    profileRef: string;
+    /** Model id applied at spawn when the caller named none (e.g. `z-ai/glm-5.2`). */
+    defaultModel: string;
+    /** Whether this is THE default preset for its `harnessSlug`. At most one per
+     *  harness — enforced on write. */
+    isDefault: boolean;
+}
+declare const harnessPresetsFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    presets: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        harnessSlug: z.ZodString;
+        name: z.ZodString;
+        profileRef: z.ZodString;
+        defaultModel: z.ZodString;
+        isDefault: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type HarnessPresetsFile = z.infer<typeof harnessPresetsFileSchema>;
+/** Thrown when a create/update violates a store invariant (unknown/disabled
+ *  profile, a model the profile can't service, …). A validation failure, not
+ *  an I/O failure — callers surface it as a rejected request, not a crash. */
+declare class HarnessPresetValidationError extends Error {
+    constructor(message: string);
+}
+/** Injected profile lookup — lets the store validate `profileRef` without a
+ *  hard dependency on the real auth-profile file (tests stub it). */
+interface HarnessPresetValidationDeps {
+    getProfile: (id: string) => Promise<AuthProfile | undefined>;
+}
+declare function harnessPresetsPath(): string;
+/** Missing or malformed config is treated as empty — a bad preset file must
+ *  never prevent the daemon from spawning. Writes always restore valid JSON. */
+declare function loadHarnessPresets(): Promise<HarnessPresetsFile>;
+/** List all presets, optionally filtered to one harness slug. */
+declare function listHarnessPresets(harnessSlug?: string): Promise<HarnessPreset[]>;
+/** Look up a single preset by id, or undefined if none exists. */
+declare function getHarnessPreset(id: string): Promise<HarnessPreset | undefined>;
+/** The default preset for `harnessSlug`, or undefined when none is marked. The
+ *  spawn path reads this to fill an unpinned `access.profileRef` + model. */
+declare function getDefaultHarnessPreset(harnessSlug: string): Promise<HarnessPreset | undefined>;
+/**
+ * Add or replace a preset by id. Validates the profile binding, then upserts.
+ * When the incoming preset is `isDefault`, every OTHER preset for the same
+ * `harnessSlug` is demoted first, preserving the one-default-per-harness
+ * invariant even across a replace that flips an id's harness or default flag.
+ */
+declare function addHarnessPreset(preset: HarnessPreset, deps?: HarnessPresetValidationDeps): Promise<HarnessPreset>;
+/** Partial update of an existing preset. Re-validates the resulting profile
+ *  binding and re-applies the one-default invariant. Returns the updated
+ *  preset, or undefined when `id` doesn't exist. */
+declare function updateHarnessPreset(id: string, patch: Partial<Omit<HarnessPreset, "id">>, deps?: HarnessPresetValidationDeps): Promise<HarnessPreset | undefined>;
+/** Remove a preset by id. Returns true if it existed. */
+declare function removeHarnessPreset(id: string): Promise<boolean>;
+/**
+ * Mark `presetId` as THE default for its harness, demoting every other preset
+ * that shares its `harnessSlug`. Idempotent. Throws
+ * {@link HarnessPresetValidationError} when `presetId` doesn't exist or when the
+ * caller-supplied `harnessSlug` disagrees with the preset's own — the latter
+ * guards against defaulting a preset under the wrong harness by a stale id.
+ */
+declare function setDefaultPreset(harnessSlug: string, presetId: string): Promise<HarnessPreset>;
+
 /**
  * Built-in custom-route registration (PR-5).
  *
@@ -6153,7 +6769,9 @@ interface InboundWatcher {
  * external, must `await` the returned promise or operator-route overrides
  * will silently not apply.
  */
-declare function registerBuiltinRoutes(): Promise<void>;
+declare function registerBuiltinRoutes(opts?: {
+    llmEndpoint?: boolean;
+}): Promise<void>;
 
 /**
  * Read-only per-provider model enumeration (AIP-45 launch-menu "+" picker,
@@ -7603,6 +8221,16 @@ declare function monitorSessionWait(opts: {
     event?: SessionWaitEvent;
     timeoutMs?: number;
     since?: number;
+    /**
+     * The calling orchestrator's scope, when this wait was initiated by an
+     * agent session (the scoped orchestrator sub-gateway stamps
+     * `ownerSessionId`). Used ONLY to attribute the watcher attach/detach bus
+     * events this wait emits while blocked — an anonymous CLI/HTTP waiter
+     * leaves it absent. Never changes the wait's own semantics.
+     */
+    callerScope?: {
+        ownerSessionId?: string;
+    };
 }): Promise<SessionWaitResult>;
 /**
  * Block until the named policy's status transitions out of the active
@@ -7927,6 +8555,11 @@ interface CreateGatewayOptions {
      * returns) so the injected `serve` can capture the finished gateway.
      */
     pairingRegistry?: PairingRegistry;
+    /** Enable the local LLM Endpoint proxy sidecar (route registration,
+     *  MCP tools, child-process lifecycle). Default false — the endpoint is
+     *  an opt-in feature; when off, the `llm-endpoint` custom route is not
+     *  registered and the `llm_endpoint_*` MCP tools are not exposed. */
+    llmEndpoint?: boolean;
 }
 interface GatewayHandle {
     url: string;
@@ -7985,4 +8618,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 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 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 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, WorkspaceFs, 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, appendConversationRecord, attachSandbox, bucketDir, bucketSessionsFile, bucketTranscriptDir, buildCatalogProviderModels, buildMcpConfigSnippet, buildRouteAwareLaunchConfig, canonicalForModeId, claudeProjectSlug, composeSessionObservers, conversationIndexPath, createActivityProjector, createFileStepCache, createGateway, createInboundEndpointStore, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createPrProvenanceReconciler, createReconnectLogGate, createScopeTokenRegistry, createSupervisorTaskGateRunner, createTaskLedger, daemonRegistryDir, decideWorktreeIsolation, declaredPresetToProviderPreset, deriveSessionUsage, enrichRollupWithProviderQuota, enrichWithRemainingQuota, evaluateCostBudget, filterActivities, findConversationRecord, findNativeMode, formatToolCall, formatToolResult, getMcpCredentialDeps, isAgentCliAuthConfigured, isClosedTaskStatus, isSafeBucketSlug, isTerminalActivityState, listBuckets, listPresets, 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, readUsageSnapshots, reapOrphanedDescendants, recordProfileQuota, registerBuiltinRoutes, registerPairingTools, registerSandboxAttachTool, resolveBucketSlug, resolveNativeLink, resolvePosture, rollupUsage, runCrashDetectPass, runEagerResumePass, runIdleReapPass, runStallWatchdogPass, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, toWorktreeStatusView, turnToActivities, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, 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 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 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 };