@agentproto/runtime 2.6.0 → 2.7.0

package/dist/index.d.ts

@@ -6,15 +6,15 @@ 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-CYJoeHeO.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-CYJoeHeO.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';
@@ -1661,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: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" | "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
@@ -1743,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
@@ -1862,11 +1895,12 @@ interface SessionStallClearedEvent {
  * 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`); 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.
+ * 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";
@@ -2064,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`).
@@ -2186,7 +2238,7 @@ interface TaskChangedEvent {
     sessionId?: string;
     ts: string;
 }
-type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | SessionExitedEvent | SessionReapedEvent | SessionStalledEvent | SessionStallClearedEvent | SessionWatcherAttachedEvent | SessionWatcherDetachedEvent | SessionBgTasksParkedEvent | SessionBgTasksClearedEvent | 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. */
@@ -3613,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` /
@@ -3849,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
@@ -4214,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;
@@ -4303,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
@@ -4352,6 +4469,24 @@ interface SessionDescriptor {
      *  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 —
@@ -4478,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
@@ -4640,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
@@ -4739,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:
@@ -4893,6 +5067,7 @@ interface SessionSummary {
     activitySummary?: SessionActivitySummary;
     archived?: boolean;
     keepAlive?: boolean;
+    pinned?: boolean;
     pty?: boolean;
     name?: string;
     argv?: readonly string[];
@@ -4919,6 +5094,10 @@ interface SessionSummary {
      *  `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;
@@ -5214,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
@@ -5362,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
@@ -5416,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. */
@@ -5691,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. */