Merge remote-tracking branch 'origin/master' into worktree/remove-expose-internals

packages/README.md

@@ -32,7 +32,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
-| [`session-query/`](session-query/README.md) | Session retrieval: logical corpus, bounded reads, lineage, and event relationships | Product — stable surface |
+| [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
 | [`session-title/`](session-title/README.md) | Log-backed session titles: fallback service, shared LLM policy, and opt-in providers | Product — stable surface |
 | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |

packages/client/connection/src/client/fixture.ts

@@ -2,8 +2,8 @@
 // RpcRequest<P> and returns RpcResponse<T> (echoing the rpcId); streams yield RpcRequest<frame>
 // (the fixture IS the fake server, so it mints frame rpcIds); root respond takes ClientResponse
 // and returns RpcReceipt. fx-alpha carries a hand-built history script (60 turns, pageable);
-// prompt triggers a chunked streaming replay; cancel stops the replay; one resident pending
-// approval (placeholder-card material, subscribed-baseline-replay semantics: stable rpcId reuse).
+// prompt triggers a chunked streaming replay; cancel stops the replay; resident pending
+// approval/question requests exercise replay and composer takeover with stable rpcIds.
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
@@ -281,6 +281,41 @@ export function createFixtureApi(): ApiProxy {
   const mint = (): ReturnType<typeof RpcId> => RpcId(`fx-rpc-${nextRpc++}`)
   /** Resident pending approval (stable rpcId: every mux open replays the same id, matching host replay semantics). */
   const pendingApprovalRpcId = mint()
+  const pendingQuestionRpcId = mint()
+  let questionPending = true
+  const fixtureQuestions: Extract<MuxFrame, { type: 'question/requested' }>['questions'] = [
+    {
+      id: 'harness-profile',
+      header: '偏好',
+      question: '你现在更想招哪类 Agent/Harness 候选人？',
+      options: [
+        { label: '工程落地型 (Recommended)', description: '更看重能直接做 runtime、tool executor、sandbox、trace 和线上问题排查。' },
+        { label: '研究潜力型', description: '更看重 Agent 理解、训练评测思路和长期成长空间。' },
+        { label: '均衡型', description: '同时要求工程能力和 Agent 认知，但可能筛选门槛更高。' },
+      ],
+    },
+    {
+      id: 'work-mode',
+      header: '方式',
+      question: '你希望候选人优先展示哪种工作方式？',
+      options: [
+        { label: '先做小型原型 (Recommended)', description: '用可运行结果尽快验证关键假设。' },
+        { label: '先写完整设计', description: '先收敛边界、协议和风险，再开始实现。' },
+      ],
+    },
+    {
+      id: 'signals',
+      header: '信号',
+      question: '哪些面试信号最重要？',
+      detail: '按当前招聘目标选择；跳过则视为不设偏好。',
+      multiSelect: true,
+      options: [
+        { label: '系统设计' },
+        { label: '代码质量' },
+        { label: 'Agent 产品判断' },
+      ],
+    },
+  ]
 
   const muxConns = new Set<StreamConn<MuxFrame>>()
   const hostConns = new Set<StreamConn<HostFrame>>()
@@ -467,7 +502,7 @@ export function createFixtureApi(): ApiProxy {
         muxConns.add(conn)
         const breakNow = (): void => { conn.breakNow() }
         streamBreakers.add(breakNow)
-        // Open baseline: subscribed for attached (running) sessions + pending approval replay (stable rpcId).
+        // Open baseline: subscribed sessions + pending interactions replayed with stable rpcIds.
         for (const s of sessions) {
           if (!s.running) continue
           conn.push({ rpcId: mint(), payload: { type: 'session/subscribed', sessionId: s.sessionId, lastSeq: (logs.get(s.sessionId)?.length ?? 0) - 1 } })
@@ -480,6 +515,14 @@ export function createFixtureApi(): ApiProxy {
             toolName: 'dangerous_tool', reason: 'fixture 常驻占位审批（可见不可答）',
           },
         })
+        if (questionPending) {
+          conn.push({
+            rpcId: pendingQuestionRpcId,
+            payload: {
+              type: 'question/requested', sessionId: sid('fx-alpha'), questions: fixtureQuestions,
+            },
+          })
+        }
         try {
           yield* conn.drain(signal)
         } finally {
@@ -509,9 +552,16 @@ export function createFixtureApi(): ApiProxy {
       },
     },
     respond(message: ClientResponse): Promise<RpcReceipt> {
-      // The v1 UI never answers (PendingCard is visible but not answerable); implemented for type completeness, always not-pending.
-      void message
-      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+      if (!questionPending || message.rpcId !== pendingQuestionRpcId) {
+        return Promise.resolve({ accepted: false, reason: 'not-pending' })
+      }
+      questionPending = false
+      emitMux({
+        type: 'question/resolved', sessionId: sid('fx-alpha'),
+        questionRpcId: pendingQuestionRpcId,
+        outcome: message.result.ok ? 'answered' : 'cancelled',
+      })
+      return Promise.resolve({ accepted: true })
     },
   }
 }

packages/client/connection/tests/fixture.spec.ts

@@ -148,14 +148,14 @@ describe('createFixtureApi', () => {
     expect(types.at(-1)).toBe('turn/end') // steer did not restart the turn
   })
 
-  it('mux open replays the baseline: subscribed for running sessions + the resident approval with a stable rpcId', async () => {
+  it('mux open replays subscribed sessions and resident interactions with stable rpcIds', async () => {
     const api = createFixtureApi()
     const openOnce = async (): Promise<RpcRequest<MuxFrame>[]> => {
       const abort = new AbortController()
       const envelopes: RpcRequest<MuxFrame>[] = []
       for await (const envelope of api.events.mux(req({}), abort.signal)) {
         envelopes.push(envelope)
-        if (envelopes.length >= 2) abort.abort()
+        if (envelopes.length >= 3) abort.abort()
       }
       return envelopes
     }
@@ -165,6 +165,8 @@ describe('createFixtureApi', () => {
     expect((first[0]?.payload as { lastSeq: number }).lastSeq).toBeGreaterThan(0)
     expect(first[1]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
     expect(second[1]?.rpcId).toBe(first[1]?.rpcId) // stable rpcId across replays (host replay semantics)
+    expect(first[2]?.payload).toMatchObject({ type: 'question/requested', sessionId: 'fx-alpha' })
+    expect(second[2]?.rpcId).toBe(first[2]?.rpcId)
   })
 
   it('steer with no replay in flight falls through to a fresh queued turn; non-text blocks stringify empty', async () => {
@@ -217,9 +219,38 @@ describe('createFixtureApi', () => {
     }
   })
 
-  it('respond is a typed stub: always not-pending', async () => {
+  it('respond resolves the resident question once and rejects duplicate or unrelated ids', async () => {
     const api = createFixtureApi()
     expect(await api.respond({ type: 'client-response', rpcId: RpcId('x'), result: { ok: true, value: {} } })).toEqual({ accepted: false, reason: 'not-pending' })
+    const abort = new AbortController()
+    let question: RpcRequest<MuxFrame> | undefined
+    for await (const envelope of api.events.mux(req({}), abort.signal)) {
+      if (envelope.payload.type !== 'question/requested') continue
+      question = envelope
+      abort.abort()
+    }
+    if (question === undefined) throw new Error('fixture question missing')
+    const response = { type: 'client-response' as const, rpcId: question.rpcId, result: { ok: true as const, value: {} } }
+    expect(await api.respond(response)).toEqual({ accepted: true })
+    expect(await api.respond(response)).toEqual({ accepted: false, reason: 'not-pending' })
+
+    const replayAbort = new AbortController()
+    const replayed = await collect(api.events.mux(req({}), replayAbort.signal), replayAbort, frames => frames.length === 2)
+    expect(replayed.every(frame => frame.type !== 'question/requested')).toBe(true)
+
+    const cancelledApi = createFixtureApi()
+    const cancelAbort = new AbortController()
+    let cancelQuestion: RpcRequest<MuxFrame> | undefined
+    for await (const envelope of cancelledApi.events.mux(req({}), cancelAbort.signal)) {
+      if (envelope.payload.type !== 'question/requested') continue
+      cancelQuestion = envelope
+      cancelAbort.abort()
+    }
+    if (cancelQuestion === undefined) throw new Error('fixture cancellation question missing')
+    expect(await cancelledApi.respond({
+      type: 'client-response', rpcId: cancelQuestion.rpcId,
+      result: { ok: false, error: { code: 'cancelled', message: 'skip', details: {} } },
+    })).toEqual({ accepted: true })
   })
 
   it('describe answers the fixture identity', async () => {

packages/client/ui-conversation/README.md

@@ -26,4 +26,4 @@ None; this package neither assembles nor sends a provider request.
 - **Details panel is the minimal form** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred.
 - **Assistant footer extensions (IconActions row, per-message paging) are reserved slots** — drawn in the design, not implemented.
 - **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export.
-- **Approval/question cards are display-only placeholders** — web-side answering (composer takeover panel) is the P-II approvals project.
+- **Approval cards are display-only placeholders** — question requests answer through the composer chain (ui-question), while web-side approval answering is the P-II approvals project.

packages/client/ui-conversation/src/client/index.ts

@@ -18,8 +18,8 @@ export type {
 } from './contract/views.ts'
 export type { ToolCallBlock } from './contract/tool-call-model.ts'
 export type {
-  ChatStore, ChatViewInjected, ChatViewSlotProps, ConversationInjected, ConversationSlotProps,
-  ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
+  ChatStore, ChatViewInjected, ChatViewSlotProps, ComposerChainProps, ConversationInjected,
+  ConversationSlotProps, ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
   EmptyStateInjected, EmptyStateSlotProps, ToolRowOwnerProps, ToolRowProps,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.

packages/client/ui-question/README.md

@@ -0,0 +1,20 @@
+# @deepseek-ai/dsh-client-ui-question
+
+Web `ask_user_question` feature plugin. Its host half mounts `dsh-tool-ask-user` only when the Web feature is selected; its browser half registers the `question` entry in the conversation-owned `conversation.composer` keyed slot.
+
+The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`.
+
+Selection state is local to a component keyed by the request rpcId. A replay with the same id preserves a still-mounted draft, while `question/resolved` from the host removes the composer. The host remains authoritative: successful HTTP delivery does not remove pending state locally.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-ask-user`; that package owns the model-visible tool schema and structured result.
+
+#### KV Cache effect
+
+No direct invalidation; `dsh-tool-ask-user` owns the model-visible tool call and result.
+
+## Known Limitations and Deferred Work
+
+- **Unsubmitted drafts are not durable** — reconnect resync or a full page reload restores the host-owned pending request with the same rpcId, but a composer unmount resets local option and custom-text drafts.
+- **One request owns the composer at a time** — later pending requests remain in the session snapshot and become visible after the earlier request resolves.

packages/client/ui-question/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-question",
+  "description": "Web ask_user_question feature: host tool mount plus composer-takeover question UI",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-ui-conversation"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
+    "clsx": "^2.0.0",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

packages/client/ui-question/src/client/QuestionComposer.module.css

@@ -0,0 +1,348 @@
+.frame {
+  display: flex;
+  justify-content: center;
+  padding: 6px 24px 10px;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  max-width: 720px;
+  /* Composer seat sits in a fixed-height conversation column (overflow
+     hidden): cap the card against the viewport and scroll the option list
+     so header and footer actions stay reachable on long batches. */
+  max-height: min(60vh, 520px);
+  padding: 14px 16px 12px;
+  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border-radius: 18px;
+  background: var(--dsw-specific-input-major);
+  box-shadow: var(--dsw-shadow-lv1-blur);
+  color: var(--dsw-alias-label-primary);
+}
+
+.card,
+.card * {
+  box-sizing: border-box;
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  flex-shrink: 0;
+  margin-bottom: 8px;
+}
+
+.headingBlock {
+  min-width: 0;
+  padding: 1px 2px;
+}
+
+.eyebrow {
+  margin-bottom: 2px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+.title {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin: 0;
+  font-size: 16px;
+  line-height: 22px;
+  font-weight: 600;
+}
+
+.multiSelectHint {
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 400;
+  white-space: nowrap;
+}
+
+.detail {
+  margin: 2px 0 0;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 400;
+}
+
+.headerActions,
+.footerActions {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex-shrink: 0;
+}
+
+.progress {
+  padding: 0 6px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 24px;
+  white-space: nowrap;
+}
+
+.iconButton {
+  display: grid;
+  place-items: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+}
+
+.iconButton:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-primary);
+}
+
+.iconButton:disabled {
+  color: var(--dsw-alias-label-dimmed);
+  cursor: default;
+}
+
+.options {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  /* The scrollable region of the capped card (ChatView list pattern). */
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.option {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-height: 42px;
+  padding: 5px 8px;
+  border: 1px solid transparent;
+  border-radius: 12px;
+  background: transparent;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+  transition: background-color 120ms ease, border-color 120ms ease;
+}
+
+.option:hover:not(:disabled),
+.optionSelected {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.optionSelected {
+  border-color: var(--dsw-alias-border-l2);
+}
+
+.option:disabled,
+.customTrigger:disabled {
+  cursor: default;
+}
+
+.number {
+  display: grid;
+  place-items: center;
+  flex: 0 0 28px;
+  width: 28px;
+  height: 28px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 999px;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.optionCopy {
+  min-width: 0;
+  flex: 1;
+}
+
+.optionLine {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 2px 6px;
+}
+
+.optionLabel {
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 600;
+}
+
+.badge {
+  padding: 0 6px;
+  border-radius: 999px;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-secondary);
+  font-size: 11px;
+  line-height: 18px;
+}
+
+.description {
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 400;
+}
+
+.choiceIcon {
+  display: grid;
+  place-items: center;
+  width: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.custom {
+  border: 1px solid transparent;
+  border-radius: 12px;
+}
+
+.customOpen {
+  border-color: var(--dsw-alias-border-l2);
+  background: var(--dsw-alias-bg-module-platform);
+}
+
+.customOptionless {
+  border: none;
+  background: transparent;
+}
+
+.customTrigger {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-height: 42px;
+  padding: 5px 8px;
+  border: none;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 14px;
+  line-height: 20px;
+  text-align: left;
+  cursor: pointer;
+}
+
+.customTrigger:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+}
+
+.customInput {
+  display: block;
+  width: calc(100% - 20px);
+  min-height: 54px;
+  max-height: 140px;
+  margin: 0 10px 10px;
+  padding: 7px 10px;
+  resize: vertical;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 10px;
+  outline: none;
+  background: var(--dsw-specific-input-major);
+  color: var(--dsw-alias-label-primary);
+  caret-color: var(--dsw-alias-state-business-primary);
+  font: inherit;
+  font-size: 13px;
+  line-height: 20px;
+}
+
+.customInput:focus {
+  border-color: var(--dsw-alias-state-business-primary);
+}
+
+.customInput::placeholder {
+  color: var(--dsw-alias-label-caption);
+}
+
+.customOptionless .customInput {
+  width: 100%;
+  min-height: 58px;
+  margin: 0;
+  background: var(--dsw-alias-bg-module-platform);
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-shrink: 0;
+  margin-top: 8px;
+  padding: 0 2px;
+}
+
+.feedback {
+  min-height: 16px;
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+@media (max-width: 720px) {
+  .frame {
+    padding: 6px 10px 10px;
+  }
+
+  .card {
+    padding: 12px 10px 10px;
+    border-radius: 16px;
+  }
+
+  .header {
+    display: block;
+  }
+
+  .headerActions {
+    justify-content: flex-end;
+    margin-top: 8px;
+  }
+
+  .headingBlock {
+    padding: 0 2px;
+  }
+
+  .title {
+    font-size: 15px;
+    line-height: 21px;
+  }
+
+  .option,
+  .customTrigger {
+    align-items: flex-start;
+    gap: 8px;
+    padding: 6px;
+  }
+
+  .choiceIcon {
+    margin-top: 3px;
+  }
+
+  .footer {
+    align-items: flex-end;
+  }
+
+  .footerActions {
+    flex-shrink: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .option {
+    transition: none;
+  }
+}

packages/client/ui-question/src/client/QuestionComposer.tsx

@@ -0,0 +1,297 @@
+import { useMemo, useState, type KeyboardEvent } from 'react'
+import clsx from 'clsx'
+import {
+  Button, IconCheckOutline16, IconChevronLeftOutline14, IconChevronRightOutline14,
+  IconCloseOutline16, IconEditOutline16,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import { PendingQuestion, type QuestionAnswer, type QuestionComposerProps } from './contract/slots.ts'
+import css from './QuestionComposer.module.css'
+
+interface DraftAnswer {
+  selected: string[]
+  custom: string
+  customOpen: boolean
+  skipped: boolean
+}
+
+/**
+ * Split the conventional recommendation suffix without changing the answer value.
+ * @param label - Original option label returned if selected.
+ * @returns Display label plus recommendation state.
+ */
+export function parseRecommendedLabel(label: string): { label: string; recommended: boolean } {
+  const suffix = /\s*(?:\((?:recommended|推荐)\)|（(?:recommended|推荐)）)\s*$/i
+  return suffix.test(label)
+    ? { label: label.replace(suffix, ''), recommended: true }
+    : { label, recommended: false }
+}
+
+/**
+ * Remove a conventional multi-select suffix so the hint can be styled separately.
+ * @param title - Question title supplied by the interaction request.
+ * @returns Question title without a trailing multi-select marker.
+ */
+export function parseQuestionTitle(title: string): string {
+  return title.replace(/\s*[（(]可多选[）)]\s*$/, '')
+}
+
+/** Return whether a textarea key event belongs to an active IME composition. */
+function isComposing(event: KeyboardEvent<HTMLTextAreaElement>): boolean {
+  return event.nativeEvent.isComposing || event.nativeEvent.keyCode === 229
+}
+
+/**
+ * Composer takeover boundary; the carrier key keys local drafts, so a
+ * same-request replay (same key, new carrier object) preserves them.
+ * @param props - the selector-matched pending question carrier plus the framework standard kit.
+ * @returns The question flow for this request.
+ */
+export function QuestionComposer(props: QuestionComposerProps) {
+  // Domain-face mint rides the carrier's stable identity (never minted in a
+  // select/render dispatch — per-dispatch minting would churn memo identity).
+  const question = useMemo(() => new PendingQuestion(props.matched), [props.matched])
+  return <QuestionFlow key={question.key} pending={question} />
+}
+
+function QuestionFlow({ pending }: { pending: PendingQuestion }) {
+  const questions = pending.questions
+  const [index, setIndex] = useState(0)
+  const [drafts, setDrafts] = useState<DraftAnswer[]>(() => questions.map(question => ({
+    selected: [], custom: '', customOpen: (question.options?.length ?? 0) === 0, skipped: false,
+  })))
+  const [busy, setBusy] = useState<'answer' | 'cancel' | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const question = questions[index]!
+  const draft = drafts[index]!
+  const hasOptions = (question.options?.length ?? 0) > 0
+
+  const cancelFlow = (): void => {
+    setBusy('cancel')
+    setError(null)
+    void pending.cancel().catch((cause: unknown) => {
+      setBusy(null)
+      setError(cause instanceof Error ? cause.message : String(cause))
+    })
+  }
+
+  const updateDraft = (update: (current: DraftAnswer) => DraftAnswer): void => {
+    setDrafts(current => current.map((item, itemIndex) => itemIndex === index ? update(item) : item))
+    setError(null)
+  }
+
+  const choose = (label: string): void => {
+    updateDraft((current) => {
+      const selected = question.multiSelect === true
+        ? current.selected.includes(label)
+          ? current.selected.filter(item => item !== label)
+          : [...current.selected, label]
+        : [label]
+      return { selected, custom: '', customOpen: false, skipped: false }
+    })
+    if (question.multiSelect !== true && index < questions.length - 1) {
+      setIndex(current => current + 1)
+    }
+  }
+
+  const openCustom = (): void => {
+    updateDraft(current => ({ ...current, selected: [], customOpen: true, skipped: false }))
+  }
+
+  const answered = (item: DraftAnswer): boolean =>
+    item.selected.length > 0 || item.custom.trim() !== ''
+
+  const completed = (item: DraftAnswer): boolean => answered(item) || item.skipped
+
+  const submitDrafts = (values: DraftAnswer[]): void => {
+    const missing = values.findIndex(item => !completed(item))
+    if (missing >= 0) {
+      setIndex(missing)
+      setError('请先完成这道问题。')
+      return
+    }
+    const answer: QuestionAnswer = {
+      answers: questions.map((item, itemIndex) => {
+        const value = values[itemIndex] as DraftAnswer
+        if (value.skipped) return { id: item.id, selected: [] }
+        const custom = value.custom.trim()
+        return {
+          id: item.id,
+          selected: custom === '' ? value.selected : [],
+          ...(custom === '' ? {} : { custom }),
+        }
+      }),
+    }
+    setBusy('answer')
+    setError(null)
+    void pending.answer(answer).catch((cause: unknown) => {
+      setBusy(null)
+      setError(cause instanceof Error ? cause.message : String(cause))
+    })
+  }
+
+  const continueFlow = (): void => {
+    if (!answered(draft)) {
+      setError('请选择一个选项或填写自定义答案。')
+      return
+    }
+    if (index < questions.length - 1) {
+      setIndex(current => current + 1)
+      setError(null)
+      return
+    }
+    submitDrafts(drafts)
+  }
+
+  const skipQuestion = (): void => {
+    const nextDrafts = drafts.map((item, itemIndex) => itemIndex === index
+      ? {
+          selected: [], custom: '',
+          customOpen: (question.options?.length ?? 0) === 0,
+          skipped: true,
+        }
+      : item)
+    setDrafts(nextDrafts)
+    setError(null)
+    if (index < questions.length - 1) {
+      setIndex(current => current + 1)
+      return
+    }
+    submitDrafts(nextDrafts)
+  }
+
+  return (
+    <div className={css.frame} data-question-key={pending.key}>
+      <section className={css.card} aria-labelledby={`question-${pending.key}-${String(index)}`}>
+        <header className={css.header}>
+          <div className={css.headingBlock}>
+            {question.header !== undefined && <div className={css.eyebrow}>{question.header}</div>}
+            <h2 className={css.title} id={`question-${pending.key}-${String(index)}`}>
+              <span>{question.multiSelect === true
+                ? parseQuestionTitle(question.question)
+                : question.question}</span>
+              {question.multiSelect === true && <span className={css.multiSelectHint}>可多选</span>}
+            </h2>
+            {question.detail !== undefined && <p className={css.detail}>{question.detail}</p>}
+          </div>
+          <div className={css.headerActions}>
+            <span className={css.progress}>{index + 1} / {questions.length}</span>
+            <button
+              type="button" className={css.iconButton} aria-label="上一题"
+              disabled={index === 0 || busy !== null}
+              onClick={() => { setIndex(index - 1); setError(null) }}
+            >
+              <IconChevronLeftOutline14 />
+            </button>
+            <button
+              type="button" className={css.iconButton} aria-label="下一题"
+              disabled={index === questions.length - 1 || busy !== null}
+              onClick={() => { setIndex(index + 1); setError(null) }}
+            >
+              <IconChevronRightOutline14 />
+            </button>
+            <button
+              type="button" className={css.iconButton} aria-label="放弃整组问题"
+              title="放弃整组问题"
+              disabled={busy !== null} onClick={cancelFlow}
+            >
+              <IconCloseOutline16 />
+            </button>
+          </div>
+        </header>
+
+        <div className={css.options} role={question.multiSelect === true ? 'group' : 'radiogroup'}>
+          {(question.options ?? []).map((option, optionIndex) => {
+            const selected = draft.selected.includes(option.label)
+            const display = parseRecommendedLabel(option.label)
+            return (
+              <button
+                type="button" key={`${option.label}-${String(optionIndex)}`}
+                className={clsx(css.option, selected && css.optionSelected)}
+                role={question.multiSelect === true ? 'checkbox' : 'radio'}
+                aria-checked={selected}
+                aria-label={display.label}
+                disabled={busy !== null}
+                onClick={() => { choose(option.label) }}
+                onKeyDown={(event) => {
+                  if (event.key !== 'Enter' || !drafts.every(completed)) return
+                  event.preventDefault()
+                  submitDrafts(drafts)
+                }}
+              >
+                <span className={css.number}>{optionIndex + 1}</span>
+                <span className={css.optionCopy}>
+                  <span className={css.optionLine}>
+                    <span className={css.optionLabel}>{display.label}</span>
+                    {display.recommended && <span className={css.badge}>推荐</span>}
+                    {option.description !== undefined && (
+                      <span className={css.description}>{option.description}</span>
+                    )}
+                  </span>
+                </span>
+                <span className={css.choiceIcon}>
+                  {selected ? <IconCheckOutline16 /> : <IconChevronRightOutline14 />}
+                </span>
+              </button>
+            )
+          })}
+
+          <div className={clsx(
+            css.custom,
+            draft.customOpen && css.customOpen,
+            !hasOptions && css.customOptionless,
+          )}>
+            {hasOptions && (
+              <button
+                type="button" className={css.customTrigger}
+                disabled={busy !== null} onClick={openCustom}
+                aria-expanded={draft.customOpen}
+              >
+                <span className={css.number}><IconEditOutline16 /></span>
+                <span>其他，请填写自定义答案</span>
+              </button>
+            )}
+            {draft.customOpen && (
+              <textarea
+                autoFocus
+                className={css.customInput}
+                value={draft.custom}
+                disabled={busy !== null}
+                rows={2}
+                placeholder="输入你的答案"
+                onChange={(event) => {
+                  const value = event.target.value
+                  updateDraft(current => ({
+                    ...current, selected: [], custom: value, customOpen: true, skipped: false,
+                  }))
+                }}
+                onKeyDown={(event) => {
+                  if (event.key === 'Enter' && !event.shiftKey && !isComposing(event)) {
+                    event.preventDefault()
+                    continueFlow()
+                  }
+                }}
+              />
+            )}
+          </div>
+        </div>
+
+        <footer className={css.footer}>
+          <div className={css.feedback} role="status">{error}</div>
+          <div className={css.footerActions}>
+            <Button variant="ghost" size="sm" disabled={busy !== null} onClick={skipQuestion}>
+              跳过本题
+            </Button>
+            <Button
+              variant="primary" size="sm"
+              disabled={busy !== null || !answered(draft)} onClick={continueFlow}
+            >
+              {busy === 'answer'
+                ? '正在提交…'
+                : index === questions.length - 1 ? '提交' : '下一题'}
+            </Button>
+          </div>
+        </footer>
+      </section>
+    </div>
+  )
+}

packages/client/ui-question/src/client/contract/slots.ts

@@ -0,0 +1,77 @@
+/**
+ * Question-composer slot contract: the registrant-side props composition for
+ * the conversation-owned `conversation.composer` slot, plus the question
+ * domain face over the runtime's carrier object. The carrier (PendingWait)
+ * owns envelope transport only; the question protocol — answer value shape,
+ * cancelled error encoding, receipt checks — lives HERE, with the package
+ * that consumes it.
+ */
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+// Also pulls ui-conversation's SlotMap merge (the 'conversation.composer'
+// entry) into every program that sees this contract, so PropsRuntime resolves.
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
+import type { QuestionResponsePayload } from '@deepseek-ai/dsh-client-connection/client'
+
+/** The pending question carrier the owner dispatches into the composer slot. */
+export type QuestionWait = PendingWait<'question'>
+
+/** One structured answer batch covering every question of the request. */
+export type QuestionAnswer = QuestionResponsePayload['answer']
+
+/**
+ * Question domain face over the carrier: render identity and questions
+ * transparently forwarded; answer/cancel own the wire encoding (the ok value
+ * shape and the cancelled error) and turn a rejected carrier receipt into a
+ * thrown error. Components mint one per carrier via useMemo (never inside a
+ * select — a per-dispatch mint would churn identity and break memoization).
+ */
+export class PendingQuestion {
+  /**
+   * @param wait - the runtime carrier for one pending question request.
+   */
+  constructor(private readonly wait: QuestionWait) {}
+
+  /** Opaque render identity (React key / draft remount axis), forwarded from the carrier. */
+  get key(): string {
+    return this.wait.key
+  }
+
+  /** The request's question list, forwarded from the carrier payload. */
+  get questions(): QuestionWait['payload']['questions'] {
+    return this.wait.payload.questions
+  }
+
+  /**
+   * Deliver the whole answer batch; a rejected carrier receipt throws.
+   * @param answer - complete structured answer batch.
+   */
+  async answer(answer: QuestionAnswer): Promise<void> {
+    const receipt = await this.wait.respond({
+      ok: true, value: { sessionId: this.wait.sessionId, answer },
+    })
+    if (!receipt.accepted) {
+      throw new Error(`question response rejected: ${receipt.reason}`)
+    }
+  }
+
+  /** Reject the whole wait (the host resolves the tool call as cancelled); a rejected receipt throws. */
+  async cancel(): Promise<void> {
+    const receipt = await this.wait.respond({
+      ok: false,
+      error: { code: 'cancelled', message: 'the user closed this question request', details: {} },
+    })
+    if (!receipt.accepted) {
+      throw new Error(`question cancellation rejected: ${receipt.reason}`)
+    }
+  }
+}
+
+/**
+ * Full component props: the framework runtime share (chain currency +
+ * session/global standard kit) plus the chain `matched` share — the entry's
+ * selector result, already narrowed to the question carrier. No injected
+ * share: the carrier plus the domain face above carry the whole behavior
+ * surface.
+ */
+export type QuestionComposerProps = PropsRuntime<'conversation.composer'> & { matched: QuestionWait }

packages/client/ui-question/src/client/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Web question plugin, browser half: QuestionComposer registered as a
+ * selector-routed entry of the conversation-declared composer chain. Pure
+ * consumer — the selector narrows the owner's currency to the question
+ * carrier (matched prop), and the whole behavior surface rides the carrier
+ * (domain encoding in contract/slots.ts PendingQuestion); no inject face, no
+ * service dependency beyond slots. Export discipline: packages/client/AGENTS.md.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ComposerChainProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { QuestionWait } from './contract/slots.ts'
+import { QuestionComposer } from './QuestionComposer.tsx'
+
+export { PendingQuestion } from './contract/slots.ts'
+export type { QuestionAnswer, QuestionComposerProps, QuestionWait } from './contract/slots.ts'
+
+/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+export const inject = ['slots']
+
+/** Chain routing: claim the composer while a question wait is pending (pure — owner props only). */
+function selectQuestion({ interactions }: ComposerChainProps): QuestionWait | null {
+  return interactions.find((i): i is QuestionWait => i.kind === 'question') ?? null
+}
+
+/**
+ * Client plugin body: register the question composer into the composer chain.
+ * Zero business face — data and verbs both live on the matched carrier.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  const slots = ctx.slots
+  ctx.effect(
+    () => slots.register({ name: 'conversation.composer', select: selectQuestion }, QuestionComposer),
+    'ui-question: composer chain registration',
+  )
+}

packages/client/ui-question/src/css-modules.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: Readonly<Record<string, string>>
+  export default classes
+}

packages/client/ui-question/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Web question plugin, node half: enabling this UI feature also exposes the
+ * model-facing ask_user_question tool on the host composition.
+ */
+import type { Context } from 'cordis'
+import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
+
+/** Host services required by the model-facing tool. */
+export const inject = ['tools', 'userInteraction']
+
+/**
+ * Mount ask_user_question for hosts that selected the Web question plugin.
+ * @param ctx - Host plugin context carrying tools and userInteraction.
+ */
+export function apply(ctx: Context): void {
+  toolAskUser.apply(ctx)
+}

packages/client/ui-question/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-question`.
+ * @module @deepseek-ai/dsh-client-ui-question/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-question'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-question-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: tool and slot registrations are effects
+ * owned and observed by their respective registries; the host pending table is
+ * exercised through the public wire protocol.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns The installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/client/ui-question/tests/browser-plugin.spec.ts

@@ -0,0 +1,64 @@
+/**
+ * apply wiring on a real cordis Context + SlotsService: QuestionComposer
+ * registered as the `question` entry of the conversation-declared composer
+ * slot with ZERO business face (data and verbs ride the dispatched carrier),
+ * load-order fail-loud, and fiber-teardown unregistration. Component and
+ * domain-face behavior is covered props-direct in question-composer.spec.tsx;
+ * no renderer machinery here.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { QuestionComposer } from '../src/client/QuestionComposer.tsx'
+import { apply, inject } from '../src/client/index.ts'
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const slots = ctx.get('slots') as SlotsService
+  // Stand-in for ui-conversation's conversation entry: the composer slot only
+  // exists while a live entry declares it in children (declaration account:
+  // design §2.2).
+  slots.register(
+    { name: 'root', children: { 'conversation.composer': { kind: 'chain', scope: 'session' } } } as never,
+    () => null,
+  )
+  return { ctx, slots }
+}
+
+describe('apply', () => {
+  it('declares the services it binds', () => {
+    expect(inject).toEqual(['slots'])
+  })
+
+  it('fails loud when no live entry has declared the composer slot', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SlotsService).await()
+    await expect(ctx.plugin({ inject: [...inject], apply }))
+      .rejects.toThrow(/slot "conversation.composer" is not declared/)
+  })
+
+  it('registers the question entry: routing selector, no inject face', async () => {
+    const { ctx, slots } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    const entry = slots.entries('conversation.composer')[0]!
+    expect(entry.component).toBe(QuestionComposer)
+    // The whole behavior surface rides the matched carrier: no business face.
+    expect(entry.inject).toBeUndefined()
+    // The selector narrows the chain currency: question wait in → that wait; none → null.
+    const select = entry.select as (owner: { interactions: readonly { kind: string }[] }) => unknown
+    const question = { kind: 'question' }
+    expect(select({ interactions: [{ kind: 'approval' }, question] })).toBe(question)
+    expect(select({ interactions: [{ kind: 'approval' }] })).toBeNull()
+    expect(select({ interactions: [] })).toBeNull()
+  })
+
+  it('teardown unregisters the slot entry', async () => {
+    const { ctx, slots } = await bench()
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(slots.entries('conversation.composer')).toHaveLength(1)
+    await fiber.dispose()
+    expect(slots.entries('conversation.composer')).toHaveLength(0)
+  })
+})

packages/client/ui-question/tests/node-plugin.spec.ts

@@ -0,0 +1,28 @@
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import { apply, inject } from '../src/index.ts'
+
+let ctx: Context | undefined
+
+afterEach(async () => {
+  await ctx?.fiber.dispose()
+  ctx = undefined
+})
+
+describe('ui-question node plugin', () => {
+  it('exposes ask_user_question only for the selected Web feature lifecycle', async () => {
+    ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(UserInteractionService)
+    const feature = ctx.plugin({ inject: [...inject], apply })
+    await feature.await()
+    expect(ctx.tools.get('ask_user_question')).toBeDefined()
+
+    await feature.dispose()
+    expect(ctx.tools.get('ask_user_question')).toBeUndefined()
+  })
+})

packages/client/ui-question/tests/question-composer.spec.tsx

@@ -0,0 +1,265 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import type { ConversationSnapshot, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
+import type { RpcReceipt } from '@deepseek-ai/dsh-client-connection/client'
+import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+import { PendingQuestion } from '../src/client/contract/slots.ts'
+import {
+  QuestionComposer, parseQuestionTitle, parseRecommendedLabel,
+} from '../src/client/QuestionComposer.tsx'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+/** Framework standard-kit stubs: the composer consumes none of them, the
+ *  composed props type mandates their delivery (framework hooks are plain
+ *  stubs per the client testing discipline). */
+const kit = {
+  sessionId: SID,
+  useSession: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook<ConversationSnapshot>,
+  useSessions: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook<SessionListState>,
+}
+
+const QUESTIONS = [
+  {
+    id: 'profile', header: '偏好', question: '选择候选人类型',
+    detail: '按当前空缺岗位的优先级选择。',
+    options: [
+      { label: '工程落地型 (Recommended)', description: '优先工程交付。' },
+      { label: '研究潜力型', description: '优先研究能力。' },
+    ],
+  },
+  {
+    id: 'detail', question: '补充你的要求',
+  },
+  {
+    id: 'signals', question: '选择重要信号（可多选）', multiSelect: true,
+    options: [{ label: '系统设计' }, { label: '代码质量' }, { label: '产品判断' }],
+  },
+]
+
+/** Carrier fixture: a real PendingWait over a scripted respond carrier. */
+function wait(rpcId = 'question-1', respond = vi.fn(() => Promise.resolve<RpcReceipt>({ accepted: true }))) {
+  const carrier = new PendingWait(
+    'question', RpcId(rpcId), SID, { questions: QUESTIONS } as PendingWait<'question'>['payload'], respond)
+  return { carrier, respond }
+}
+
+/** The client-response envelope respond must have received for an answer batch. */
+function answeredEnvelope(rpcId: string, answers: object[]) {
+  return {
+    type: 'client-response', rpcId: RpcId(rpcId),
+    result: { ok: true, value: { sessionId: SID, answer: { answers } } },
+  }
+}
+
+describe('QuestionComposer', () => {
+  it('collects single, custom, and multi-select answers before one batch submit', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    expect(screen.getByText('1 / 3')).toBeTruthy()
+    expect(screen.getByText('推荐')).toBeTruthy()
+    expect(screen.getByText('工程落地型')).toBeTruthy()
+    expect(screen.getByText('按当前空缺岗位的优先级选择。')).toBeTruthy()
+    fireEvent.keyDown(screen.getByRole('radio', { name: /工程落地型/ }), { key: 'Enter' })
+    expect(respond).not.toHaveBeenCalled()
+    fireEvent.click(screen.getByRole('radio', { name: /工程落地型/ }))
+
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    // detail is per-question: the second question carries none.
+    expect(screen.queryByText('按当前空缺岗位的优先级选择。')).toBeNull()
+    expect(screen.queryByRole('button', { name: '填写答案' })).toBeNull()
+    const custom = screen.getByPlaceholderText('输入你的答案')
+    fireEvent.change(custom, { target: { value: '要能独立排查线上问题' } })
+    fireEvent.keyDown(custom, { key: 'Enter' })
+
+    expect(screen.getByText('3 / 3')).toBeTruthy()
+    expect(screen.getByText('选择重要信号')).toBeTruthy()
+    expect(screen.getByText('可多选')).toBeTruthy()
+    expect(screen.queryByText('（可多选）')).toBeNull()
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: '代码质量' }))
+    fireEvent.keyDown(screen.getByRole('checkbox', { name: '代码质量' }), { key: 'Enter' })
+
+    // The domain face encoded the whole batch into one carrier envelope.
+    expect(respond).toHaveBeenCalledWith(answeredEnvelope('question-1', [
+      { id: 'profile', selected: ['工程落地型 (Recommended)'] },
+      { id: 'detail', selected: [], custom: '要能独立排查线上问题' },
+      { id: 'signals', selected: ['系统设计', '代码质量'] },
+    ]))
+    expect((screen.getByRole('button', { name: '正在提交…' }) as HTMLButtonElement).disabled).toBe(true)
+  })
+
+  it('skips individual questions without discarding earlier answers', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    expect((screen.getByText('下一题').closest('button') as HTMLButtonElement).disabled).toBe(true)
+    fireEvent.click(screen.getByRole('radio', { name: '研究潜力型' }))
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '跳过本题' }))
+    expect(screen.getByText('3 / 3')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '跳过本题' }))
+
+    expect(respond).toHaveBeenCalledWith(answeredEnvelope('question-1', [
+      { id: 'profile', selected: ['研究潜力型'] },
+      { id: 'detail', selected: [] },
+      { id: 'signals', selected: [] },
+    ]))
+  })
+
+  it('keeps IME Enter inside the custom input until composition finishes', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('radio', { name: '研究潜力型' }))
+    const custom = screen.getByPlaceholderText('输入你的答案')
+    fireEvent.change(custom, { target: { value: '中文输入' } })
+
+    fireEvent.keyDown(custom, { key: 'Enter', isComposing: true })
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    expect(respond).not.toHaveBeenCalled()
+
+    fireEvent.keyDown(custom, { key: 'Enter', keyCode: 229 })
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    expect(respond).not.toHaveBeenCalled()
+
+    fireEvent.keyDown(custom, { key: 'Enter' })
+    expect(screen.getByText('3 / 3')).toBeTruthy()
+  })
+
+  it('opens custom input, reports missing skipped answers, and supports header navigation', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('button', { name: '其他，请填写自定义答案' }))
+    expect(screen.getByPlaceholderText('输入你的答案')).toBeTruthy()
+    fireEvent.click(screen.getByRole('radio', { name: '工程落地型' }))
+    const emptyCustom = screen.getByPlaceholderText('输入你的答案')
+    fireEvent.keyDown(emptyCustom, { key: 'Enter', shiftKey: true })
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    fireEvent.keyDown(emptyCustom, { key: 'Enter' })
+    expect(screen.getByText('请选择一个选项或填写自定义答案。')).toBeTruthy()
+
+    fireEvent.click(screen.getByLabelText('下一题'))
+    fireEvent.click(screen.getByRole('checkbox', { name: '产品判断' }))
+    fireEvent.click(screen.getByRole('button', { name: '提交' }))
+    expect(screen.getByText('请先完成这道问题。')).toBeTruthy()
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    fireEvent.click(screen.getByLabelText('上一题'))
+    expect(screen.getByText('1 / 3')).toBeTruthy()
+    expect(respond).not.toHaveBeenCalled()
+  })
+
+  it('surfaces cancellation failures: rejected receipt text and raw transport reasons', async () => {
+    const respond = vi.fn()
+      .mockResolvedValueOnce({ accepted: false, reason: 'bad-response' })
+      .mockRejectedValueOnce(new Error('第二次取消失败'))
+    const { carrier } = wait('question-1', respond)
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    // Receipt rejection surfaces through the domain face's thrown message.
+    fireEvent.click(screen.getByRole('button', { name: '放弃整组问题' }))
+    expect(await screen.findByText('question cancellation rejected: bad-response')).toBeTruthy()
+    expect((screen.getByRole('button', { name: '跳过本题' }) as HTMLButtonElement).disabled).toBe(false)
+
+    fireEvent.click(screen.getByRole('button', { name: '放弃整组问题' }))
+    expect(await screen.findByText('第二次取消失败')).toBeTruthy()
+  })
+
+  it('surfaces transport rejection and resets local drafts for a different request', async () => {
+    const respond = vi.fn()
+      .mockRejectedValueOnce(new Error('网络中断'))
+      .mockRejectedValueOnce('字符串错误')
+    const first = wait('first', respond)
+    const view = render(<QuestionComposer matched={first.carrier} interactions={[first.carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('radio', { name: /研究潜力型/ }))
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    const second = wait('second', respond)
+    view.rerender(<QuestionComposer matched={second.carrier} interactions={[second.carrier]} {...kit} />)
+    expect(screen.getByRole('radio', { name: /研究潜力型/ }).getAttribute('aria-checked')).toBe('false')
+
+    fireEvent.click(screen.getByRole('radio', { name: /工程落地型/ }))
+    const custom = screen.getByPlaceholderText('输入你的答案')
+    fireEvent.change(custom, { target: { value: 'x' } })
+    fireEvent.keyDown(custom, { key: 'Enter' })
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('button', { name: '提交' }))
+    expect(await screen.findByText('网络中断')).toBeTruthy()
+    expect((screen.getByRole('button', { name: '提交' }) as HTMLButtonElement).disabled).toBe(false)
+
+    fireEvent.click(screen.getByRole('button', { name: '提交' }))
+    expect(await screen.findByText('字符串错误')).toBeTruthy()
+  })
+
+  it('same-key carrier replacement (baseline replay) keeps drafts', () => {
+    const first = wait('same-id')
+    const view = render(<QuestionComposer matched={first.carrier} interactions={[first.carrier]} {...kit} />)
+    fireEvent.click(screen.getByRole('radio', { name: /研究潜力型/ }))
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    // Replay mints a NEW carrier for the same request; same key = no remount.
+    const replayed = wait('same-id')
+    view.rerender(<QuestionComposer matched={replayed.carrier} interactions={[replayed.carrier]} {...kit} />)
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+  })
+})
+
+describe('PendingQuestion domain face', () => {
+  it('encodes the answer batch into the ok envelope and throws on a rejected receipt', async () => {
+    const respond = vi.fn()
+      .mockResolvedValueOnce({ accepted: true })
+      .mockResolvedValueOnce({ accepted: false, reason: 'not-pending' })
+    const question = new PendingQuestion(wait('rq', respond).carrier)
+    const batch = { answers: [{ id: 'mode', selected: ['Fast'] }] }
+    await expect(question.answer(batch)).resolves.toBeUndefined()
+    expect(respond).toHaveBeenCalledWith(answeredEnvelope('rq', batch.answers))
+    await expect(question.answer(batch)).rejects.toThrow(/question response rejected: not-pending/)
+  })
+
+  it('encodes cancellation as the cancelled error envelope and throws on a rejected receipt', async () => {
+    const respond = vi.fn()
+      .mockResolvedValueOnce({ accepted: true })
+      .mockResolvedValueOnce({ accepted: false, reason: 'bad-response' })
+    const question = new PendingQuestion(wait('rc', respond).carrier)
+    await expect(question.cancel()).resolves.toBeUndefined()
+    expect(respond).toHaveBeenCalledWith({
+      type: 'client-response', rpcId: RpcId('rc'),
+      result: {
+        ok: false,
+        error: { code: 'cancelled', message: 'the user closed this question request', details: {} },
+      },
+    })
+    await expect(question.cancel()).rejects.toThrow(/question cancellation rejected: bad-response/)
+  })
+
+  it('forwards key and questions from the carrier', () => {
+    const question = new PendingQuestion(wait('rk').carrier)
+    expect(question.key).toBe('q:rk')
+    expect(question.questions).toBe(wait('rk').carrier.payload.questions)
+  })
+})
+
+describe('parseRecommendedLabel', () => {
+  it('recognizes English and Chinese suffixes without changing ordinary labels', () => {
+    expect(parseRecommendedLabel('Fast (Recommended)')).toEqual({ label: 'Fast', recommended: true })
+    expect(parseRecommendedLabel('稳妥（推荐）')).toEqual({ label: '稳妥', recommended: true })
+    expect(parseRecommendedLabel('稳妥 (推荐)')).toEqual({ label: '稳妥', recommended: true })
+    expect(parseRecommendedLabel('Plain')).toEqual({ label: 'Plain', recommended: false })
+  })
+})
+
+describe('parseQuestionTitle', () => {
+  it('removes Chinese and ASCII multi-select suffixes', () => {
+    expect(parseQuestionTitle('选择信号（可多选）')).toBe('选择信号')
+    expect(parseQuestionTitle('选择信号 (可多选)')).toBe('选择信号')
+    expect(parseQuestionTitle('选择信号')).toBe('选择信号')
+  })
+})

packages/client/ui-question/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../connection"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../ui/tool-ask-user"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-question/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-question', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/context/session-reference/tests/session-reference.spec.ts

@@ -15,10 +15,24 @@ import SessionReferenceService, {
 } from '@deepseek-ai/dsh-session-reference'
 import { stringifyTagSafeJson } from '../src/serialization.ts'
 
+class TestSessionQueryService extends SessionQueryService {
+  override searchSessions(
+    ..._args: Parameters<SessionQueryService['searchSessions']>
+  ): ReturnType<SessionQueryService['searchSessions']> {
+    return Promise.resolve({ items: [] })
+  }
+
+  override searchEvents(
+    ..._args: Parameters<SessionQueryService['searchEvents']>
+  ): ReturnType<SessionQueryService['searchEvents']> {
+    return Promise.resolve({ items: [] })
+  }
+}
+
 async function harness(config: Config = {}): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SessionQueryService)
+  await ctx.plugin(TestSessionQueryService)
   await ctx.plugin(SessionReferenceService, config)
   return ctx
 }
@@ -524,19 +538,19 @@ describe('session reference discovery and preparation', () => {
   it('rejects direct invalid configuration before service publication', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
-    await ctx.plugin(SessionQueryService)
+    await ctx.plugin(TestSessionQueryService)
     expect(() => new SessionReferenceService(ctx, { maxReferences: 0 }))
       .toThrow(expectCode('SESSION_REFERENCE_INVALID_CONFIG'))
 
     const oversizedCtx = new Context()
     await oversizedCtx.plugin(SessionStore)
-    await oversizedCtx.plugin(SessionQueryService)
+    await oversizedCtx.plugin(TestSessionQueryService)
     expect(() => new SessionReferenceService(oversizedCtx, { maxReferences: 4 }))
       .toThrow(expectCode('SESSION_REFERENCE_INVALID_CONFIG'))
 
     const defaultCtx = new Context()
     await defaultCtx.plugin(SessionStore)
-    await defaultCtx.plugin(SessionQueryService)
+    await defaultCtx.plugin(TestSessionQueryService)
     expect(() => new SessionReferenceService(defaultCtx)).not.toThrow()
   })
 })

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -402,6 +402,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>',
         jsDoc: '/**\n * Create and publish one owner-scoped session after backend setup succeeds.\n * @param owner - exact registered Agent that owns access and cleanup.\n * @param request - backend type plus optional owner-local name and cwd.\n * @param signal - cancellation of unpublished setup.\n * @returns published identity, metadata, status, and MOTD.\n */',
       },
+      {
+        signature: 'hasOwnerActivity(owner: Agent): boolean',
+        jsDoc: '/**\n * Test whether an exact owner has a published session or unpublished spawn.\n * @param owner - exact live owner to inspect.\n * @returns true across the entire spawn-to-close interval, with no publication gap.\n */',
+      },
       {
         signature: 'startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation',
         jsDoc: '/**\n * Start one exclusive interactive send.\n * @param owner - exact session owner.\n * @param id - target PTY identity.\n * @param request - explicit text, submit behavior, and cancellation.\n * @returns live operation handle for foreground await or task registration.\n */',
@@ -464,20 +468,40 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
         jsDoc: '/**\n * Load a header and balanced contiguous log. A complete interrupted final\n * turn is preserved and durably closed with missing tool errors plus any open\n * step and turn boundaries; only a torn final record is discarded. Unknown\n * versions and corruption in the committed prefix reject.\n * @param id - the persisted session to reload.\n * @returns the header and a log ending on a balanced `turn/end`.\n */',
       },
+      {
+        signature: 'abstract inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
+        jsDoc: '/**\n * Inspect a header and its valid contiguous stored prefix without repairing\n * a torn tail, closing an interrupted turn, or publishing coordinator state.\n * This read is serialized with writes for the same id and returns detached\n * values, so observers cannot mutate backend-owned state.\n * @param id - the persisted session to inspect.\n * @returns the header and valid stored event prefix exactly as observed.\n */',
+      },
       {
         signature: 'abstract list(): Promise<SessionHeader[]>',
         jsDoc: '/**\n * Lightweight listing from metadata, without a full-log parse.\n * @returns one header per materialized session.\n */',
       },
+      {
+        signature: 'abstract listSnapshots(): Promise<SessionPersistenceSnapshot[]>',
+        jsDoc: '/**\n * List materialized sessions with cheap per-log change tokens.\n *\n * Repeated observations of an unchanged log return the same revision. A\n * successful mutating {@link load} repair changes the next listed revision.\n * Revisions also distinguish independently backed stores so backend-local\n * counters cannot compare equal across different persistence sources.\n * @returns one header and opaque revision per materialized session without loading full logs.\n */',
+      },
     ],
   },
   {
     key: 'sessionQuery',
-    summary: 'Live-preferred logical-corpus exact-read and relationship-tracing service.',
+    summary: 'Unified live-preferred session query service.',
     methods: [
+      {
+        signature: 'abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>',
+        jsDoc: '/**\n * Search the live-preferred logical corpus and group by session.\n * @param request - query text, metadata filters, page size, and cursor.\n * @param exec - optional cancellation control.\n * @returns session hits ranked by their strongest matching event.\n */',
+      },
+      {
+        signature: 'abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionEventSearchHit>>',
+        jsDoc: '/**\n * Search events within one live-preferred logical session.\n * @param request - target session, query text, filters, page size, and cursor.\n * @param exec - optional cancellation control.\n * @returns matching event hits in deterministic relevance order.\n */',
+      },
       {
         signature: 'listSessions(): Promise<SessionRecord[]>',
         jsDoc: '/**\n * List the complete logical corpus using live-preferred records.\n * @returns deterministic newest-first cloned session records.\n */',
       },
+      {
+        signature: 'async filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]>',
+        jsDoc: '/**\n * Filter the complete logical corpus with provider-independent predicates.\n * @param filters - ANDed session metadata and availability clauses.\n * @returns matching cloned records in deterministic newest-first order.\n */',
+      },
       {
         signature: 'async readTitle(sessionId: SessionId): Promise<SessionTitleSnapshot | undefined>',
         jsDoc: '/**\n * Fold the latest log-backed title from one live-preferred logical session.\n * @param sessionId - live or persisted session id to read.\n * @returns latest title snapshot, or `undefined` when the log has no title event.\n */',
@@ -486,6 +510,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>',
         jsDoc: '/**\n * List lightweight raw-log event records for one logical session.\n * @param sessionId - live-preferred session id to read.\n * @returns event records in ascending seq order.\n */',
       },
+      {
+        signature: 'async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>',
+        jsDoc: '/**\n * Scan first-party semantic event documents with provider-independent filters.\n * @param sessionId - live-preferred session id to scan.\n * @param filters - ANDed metadata and literal-text predicates.\n * @returns matching semantic documents in ascending seq order.\n */',
+      },
       {
         signature: 'async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>',
         jsDoc: '/**\n * Read one session\'s complete current model surface from one corpus observation.\n * @param sessionId - live-preferred session id to read.\n * @returns cloned header, current surface, and raw-log capture boundary.\n * @throws when source resolution fails or the session surface is invalid.\n */',
@@ -730,7 +758,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'register(definition: ToolDefinition): () => void',
-        jsDoc: '/**\n * Register globally or in the calling agent scope. Scoped tools shadow\n * globals; duplicates within one layer and the reserved `run_code` name fail.\n * @param definition - the tool schema, execution, and optional presentation functions.\n * @returns the exact disposer that unregisters the tool.\n */',
+        jsDoc: '/**\n * Register globally or in the calling agent scope. Scoped tools shadow\n * globals; duplicates within one layer and the reserved `run_code` name fail.\n * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n * @returns the exact disposer that unregisters the tool.\n */',
       },
       {
         signature: 'restrict(filter: ToolRestriction): () => void',
@@ -754,7 +782,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>',
-        jsDoc: '/**\n * Execute through pre-policy, guards, around-dispatch, post-policy, and final\n * notification. Tool and listener failures resolve as materialized error\n * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is\n * the same lossless, frozen snapshot final observers receive. Cancellation\n * arriving after entry and before final result materialization skips a\n * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n * successful started outcome with `ABORTED`; already-started work is still\n * drained and may retain a tool-owned structured error.\n * @param exec - the typed same-process call input. The registry assigns its\n *   correlation token before policy begins.\n * @returns the materialized final result.\n */',
+        jsDoc: '/**\n * Execute through pre-policy, guards, around-dispatch, post-policy,\n * definition-owned content finalization, and final notification. Tool and\n * listener failures resolve as materialized error results; an invisible tool\n * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n * snapshot final observers receive. Cancellation\n * arriving after entry and before final result materialization skips a\n * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n * successful started outcome with `ABORTED`; already-started work is still\n * drained and may retain a tool-owned structured error.\n * @param exec - the typed same-process call input. The registry assigns its\n *   correlation token before policy begins.\n * @returns the materialized final result.\n */',
       },
     ],
   },
@@ -1697,6 +1725,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SendOptions',
     declaration: 'export interface SendOptions {\n    source?: MessageSource;\n    contexts?: HookContext[];\n}',
   },
+  {
+    name: 'SessionAvailability',
+    declaration: 'export type SessionAvailability = \'live\' | \'persisted\';',
+  },
   {
     name: 'SessionEvent',
     declaration: 'export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n    [K in SessionEventType]: {\n        type: K;\n        seq: number;\n        time: number;\n        data: SessionEventMap[K];\n    } & (K extends SurfaceEventType ? {\n        sourceEventSeqs?: number[];\n        surfaceOp?: SurfaceOp;\n    } : object);\n}[T];',
@@ -1705,6 +1737,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionEventMap',
     declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': PromptMessageData;\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        meta?: JsonValue;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        provenance: AssistantProvenance;\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: JsonValue;\n    };\n    \'steering/message\': PromptMessageData & {\n        turn: number;\n    };\n    \'todo/write\': {\n        todos: TodoItem[];\n    };\n    \'request/header\': {\n        header: EpochHeader;\n        reason: R /* …truncated — full shape in source */',
   },
+  {
+    name: 'SessionEventMetadataFilter',
+    declaration: 'export type SessionEventMetadataFilter = Exclude<SessionEventResultFilter, {\n    kind: \'text\';\n}>;',
+  },
   {
     name: 'SessionEventReadRequest',
     declaration: 'export interface SessionEventReadRequest {\n    sessionId: SessionId;\n    seq: number;\n    before?: number;\n    after?: number;\n}',
@@ -1713,6 +1749,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionEventRecord',
     declaration: 'export interface SessionEventRecord {\n    sessionId: SessionId;\n    seq: number;\n    type: SessionEventType;\n    time: number;\n    surface: SessionEventSurface;\n}',
   },
+  {
+    name: 'SessionEventResultFilter',
+    declaration: 'export type SessionEventResultFilter = ({\n    kind: \'seq\';\n} & SessionResultRange) | ({\n    kind: \'time\';\n} & SessionResultRange) | {\n    kind: \'type\';\n    values: readonly SessionEventType[];\n} | {\n    kind: \'surface\';\n    values: readonly SessionEventSurface[];\n} | {\n    kind: \'text\';\n    text: string;\n};',
+  },
+  {
+    name: 'SessionEventSearchDocument',
+    declaration: 'export interface SessionEventSearchDocument extends SessionEventRecord {\n    text: string;\n}',
+  },
+  {
+    name: 'SessionEventSearchHit',
+    declaration: 'export interface SessionEventSearchHit extends SessionEventRecord {\n    snippet: string;\n}',
+  },
+  {
+    name: 'SessionEventSearchRequest',
+    declaration: 'export interface SessionEventSearchRequest {\n    sessionId: SessionId;\n    query: string;\n    filters?: readonly SessionEventMetadataFilter[];\n    limit?: number;\n    cursor?: SessionSearchCursor;\n}',
+  },
   {
     name: 'SessionEventSurface',
     declaration: 'export type SessionEventSurface = \'current\' | \'shadowed\' | \'log-only\';',
@@ -1757,6 +1809,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionLocation',
     declaration: 'export interface SessionLocation {\n    readonly kind: string;\n    readonly path: string;\n}',
   },
+  {
+    name: 'SessionPersistenceRevision',
+    declaration: 'export type SessionPersistenceRevision = Branded<\'SessionPersistenceRevision\'>;',
+  },
+  {
+    name: 'SessionPersistenceSnapshot',
+    declaration: 'export interface SessionPersistenceSnapshot {\n    header: SessionHeader;\n    revision: SessionPersistenceRevision;\n}',
+  },
   {
     name: 'SessionRecord',
     declaration: 'export interface SessionRecord {\n    header: SessionHeader;\n    live: boolean;\n    persisted: boolean;\n}',
@@ -1769,6 +1829,34 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionReferenceInput',
     declaration: 'export interface SessionReferenceInput {\n    sessionId: SessionId;\n    label?: string;\n}',
   },
+  {
+    name: 'SessionResultFilter',
+    declaration: 'export type SessionResultFilter = {\n    kind: \'id\';\n    values: readonly SessionId[];\n} | {\n    kind: \'cwd\';\n    values: readonly (string | null)[];\n} | ({\n    kind: \'created-at\';\n} & SessionResultRange) | {\n    kind: \'parent\';\n    values: readonly (SessionId | null)[];\n} | {\n    kind: \'availability\';\n    values: readonly SessionAvailability[];\n};',
+  },
+  {
+    name: 'SessionResultRange',
+    declaration: 'export interface SessionResultRange {\n    from?: number;\n    to?: number;\n}',
+  },
+  {
+    name: 'SessionSearchCursor',
+    declaration: 'export type SessionSearchCursor = Branded<\'SessionSearchCursor\'>;',
+  },
+  {
+    name: 'SessionSearchExecContext',
+    declaration: 'export interface SessionSearchExecContext {\n    signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'SessionSearchHit',
+    declaration: 'export interface SessionSearchHit extends SessionRecord {\n    bestMatch: SessionEventSearchHit;\n}',
+  },
+  {
+    name: 'SessionSearchPage',
+    declaration: 'export interface SessionSearchPage<T> {\n    items: readonly T[];\n    nextCursor?: SessionSearchCursor;\n}',
+  },
+  {
+    name: 'SessionSearchRequest',
+    declaration: 'export interface SessionSearchRequest {\n    query: string;\n    sessionFilters?: readonly SessionResultFilter[];\n    eventFilters?: readonly SessionEventMetadataFilter[];\n    limit?: number;\n    cursor?: SessionSearchCursor;\n}',
+  },
   {
     name: 'SessionSurfaceSnapshot',
     declaration: 'export interface SessionSurfaceSnapshot {\n    session: SessionHeader;\n    capturedThroughSeq: number | null;\n    events: SurfaceEvent[];\n}',
@@ -1935,11 +2023,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TaskSnapshot',
-    declaration: 'export interface TaskSnapshot {\n    id: TaskId;\n    kind: TaskKind;\n    label: string;\n    ownerSession?: SessionId;\n    status: TaskStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
+    declaration: 'export interface TaskSnapshot {\n    id: TaskId;\n    kind: TaskKind;\n    label: string;\n    outputLimitBytes?: number;\n    ownerSession?: SessionId;\n    status: TaskStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
   },
   {
     name: 'TaskStart',
-    declaration: 'export interface TaskStart {\n    kind: TaskKind;\n    label: string;\n    owner?: Agent;\n    run(): TaskHooks;\n}',
+    declaration: 'export interface TaskStart {\n    kind: TaskKind;\n    label: string;\n    outputLimitBytes?: number;\n    owner?: Agent;\n    run(): TaskHooks;\n}',
   },
   {
     name: 'TaskStatus',
@@ -1987,7 +2075,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolDefinition',
-    declaration: 'export interface ToolDefinition extends ToolSchema {\n    readonly output: ToolOutputDefinition;\n    execute(args: unknown, exec: ToolRunContext): Promise<unknown>;\n    timeoutMs?: number;\n    isConcurrencySafe?(args: unknown): boolean;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
+    declaration: 'export interface ToolDefinition extends ToolSchema {\n    readonly output: ToolOutputDefinition;\n    execute(args: unknown, exec: ToolRunContext): Promise<unknown>;\n    finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;\n    timeoutMs?: number;\n    isConcurrencySafe?(args: unknown): boolean;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
   },
   {
     name: 'ToolErrorInfo',

packages/cordis/tool-cordis/tests/inspect.spec.ts

@@ -78,7 +78,7 @@ describe('cordis_inspect', () => {
     expect(report).toContain('- tools — Tool registry and execution pipeline.')
     expect(report).toContain('/**')
     expect(report).toContain('Register globally or in the calling agent scope.')
-    expect(report).toContain('@param definition - the tool schema')
+    expect(report).toContain('@param definition - tool schema, execution, and optional finalization/presentation callbacks')
     expect(report).toContain('@returns the exact disposer')
     expect(report).toContain('register(definition: ToolDefinition)')
     expect(report).toContain('type shapes (referenced by the signatures above')

packages/core/agent-loop/README.md

@@ -67,7 +67,7 @@ Within a step, exclusive calls form barriers; parallel-safe calls use a bounded
 ### What belongs to plugins
 
 Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:
-- Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → `tools/result` pipeline; exact signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
+- Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → definition-owned `finalizeContent` → `tools/result` pipeline; exact event signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
 - Compaction: pressure on `agent/post-step`; canonical context overflow on `agent/request-error`
 - Transient model recovery: `dsh-llm-retry` on `agent/request-error`, with finite code-specific budgets and non-surface `llm/retry` status events
 - Sandbox, permission, plan mode: `tools/pre-execute` for extensible deny/ask, `tools.guard()` for monotonic owner policy, `tools/post-execute` for result decisions, and `tools/result` for final observation

packages/core/tools/README.md

@@ -1,6 +1,6 @@
 # dsh-tools
 
-Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the extensible allow/deny gate) → monotonic registered guards → `tools/execute` (an around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the result, attach context) → the observe-only `tools/result` notification. The registry also owns HOW its tools are presented to the model — its `mode` config selects native function calling, [Code Mode](#code-mode), or both.
+Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the extensible allow/deny gate) → monotonic registered guards → `tools/execute` (an around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the result, attach context) → the definition-owned `finalizeContent` boundary → the observe-only `tools/result` notification. The registry also owns HOW its tools are presented to the model — its `mode` config selects native function calling, [Code Mode](#code-mode), or both.
 
 ## Service: `ToolRegistry` (ctx key: `tools`)
 
@@ -15,7 +15,7 @@ tools:
 
 ### Public API
 
-- `ctx.tools.register(definition: ToolDefinition): () => void` Register a trusted typed same-process definition with a mandatory canonical `output` declaration. The layer is the calling context's scope: a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, shadowing a same-named global tool there. Duplicate names within one layer throw; non-native modes also reject the reserved `run_code` transport name. Missing/unsupported output declarations and a non-positive/non-finite `timeoutMs` fail at registration. Disposed with the calling fiber.
+- `ctx.tools.register(definition: ToolDefinition): () => void` Register a trusted typed same-process definition with a mandatory canonical `output` declaration. The layer is the calling context's scope: a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, shadowing a same-named global tool there. Duplicate names within one layer throw; non-native modes also reject the reserved `run_code` transport name. Missing or unsupported output declarations and a non-positive or non-finite `timeoutMs` fail at registration. The optional synchronous `finalizeContent` callback is snapshotted when a call starts and may replace only final model-facing content after every pipeline outcome is normalized, including an error discovered while materializing another result field. Disposed with the calling fiber.
 - `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to global tools and throws from a plain context. The filter is snapshotted at registration; multiple masks intersect and scope-local tools merge afterwards. Deny masks admit later unnamed globals, while allow masks exclude later names. Unknown, local, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent) — presenters pass the calling agent so the card matches what executed.
 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)).
@@ -33,11 +33,11 @@ Cancellation is cooperative and quiescent. Every typed invocation supplies a cal
 
 ### Live events
 
-The live registry pipeline has three transformable waterfalls followed by the observe-only `tools/result` boundary; registry changes are deliberately unfiltered shared-state notifications. Exact signatures, dispatch modes, scope filtering, and failure-containment contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md), while the complete ordering is visualized in the generated [tool execution pipeline](../../../docs/tool-execution-pipeline.md). `tools/result` is live; the similarly named `tool/result` is the durable session event the agent loop appends afterwards.
+The live registry pipeline has three transformable waterfalls, then the definition-owned content finalizer, then the observe-only `tools/result` boundary; registry changes are deliberately unfiltered shared-state notifications. Exact signatures, dispatch modes, scope filtering, and failure-containment contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md), while the complete ordering is visualized in the generated [tool execution pipeline](../../../docs/tool-execution-pipeline.md). `tools/result` is live; the similarly named `tool/result` is the durable session event the agent loop appends afterwards.
 
 ### Key types
 
-- `ToolDefinition` — `ToolSchema` + mandatory `output { schema, render, presentationMeta? }` + `execute(args, exec)`, optional presentation callbacks, cooperative `timeoutMs`, and optional per-call `isConcurrencySafe(args)` classification. A body returns only the canonical JSON value declared by the output schema and cooperatively stops through `exec.signal`.
+- `ToolDefinition` — `ToolSchema` + mandatory `output { schema, render, presentationMeta? }` + `execute(args, exec)`, optional final-content and presentation callbacks, cooperative `timeoutMs`, and optional per-call `isConcurrencySafe(args)` classification. A body returns only the canonical JSON value declared by the output schema and cooperatively stops through `exec.signal`. `finalizeContent(exec, result)` runs exactly once for every normalized result, including failures that bypass post-policy, and can replace only `content`; it must be synchronous and total.
 - `ToolExecutionInput` — the caller-supplied call description: `{ callId, name, arguments, signal, agent?, parent? }`; `signal` is required and readonly, callers may pass an enclosing execution's opaque token as `parent`, and callers never choose the new execution's own token.
 - `ToolExecutionToken` — a fresh branded `Symbol` assigned by the registry. It supports equality correlation only and never crosses a model, log, or worker boundary.
 - `ToolExecution` — the readonly pipeline view: immutable `{ token, callId, name, arguments, signal, agent?, parent? }`; the registry separately retains and re-fuses the original caller signal. `ToolDispatchExecution` is the `tools/execute`-only view whose required signal is mutable, so a wrapper may replace and restore it but cannot delete it. A nested call's `parent` is a `ToolExecutionToken`, not an execution object.
@@ -53,7 +53,7 @@ The live registry pipeline has three transformable waterfalls followed by the ob
 - Tool plugins call `ctx.tools.register()` — schemas flow into the assembly automatically.
 - `tools/pre-execute` is the reorderable allow/deny/ask gate; `ctx.tools.guard()` adds monotonic owner policy after it.
 - `tools/execute` wraps normalized canonical dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal; a wrapper-authored success is normalized through the resolved tool's output declaration. Canonical-result provenance belongs to one immutable dispatch token, so a cached result from another call or tool is revalidated under the active declaration.
-- `tools/post-execute` may replace presentation content, replace the canonical value, block with feedback, or attach ordered contexts; `tools/result` observes the immutable final outcome. Content replacement is not a confidentiality boundary: block or replace the value when programmatic consumers must not receive it.
+- `tools/post-execute` may replace presentation content, replace the canonical value, block with feedback, or attach ordered contexts. A definition's optional `finalizeContent` then owns its last content-only invariant across normal results and outer pipeline failures; `tools/result` observes the immutable final outcome. Content replacement is not a confidentiality boundary: block or replace the value when programmatic consumers must not receive it.
 - Exact signatures and ordering live in the generated [event catalog](../../../docs/cordis-catalog/events.md) and [pipeline](../../../docs/tool-execution-pipeline.md).
 - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas.
 

packages/core/tools/src/index.ts

@@ -169,6 +169,18 @@ export interface ToolDefinition extends ToolSchema {
    * @returns the canonical value declared by `output.schema`.
    */
   execute(args: unknown, exec: ToolRunContext): Promise<unknown>
+  /**
+   * Synchronous last-mile transform for model-facing content. The registry
+   * snapshots this callback when execution starts and invokes it exactly once
+   * for every normalized outcome, including pipeline failures that bypass
+   * `tools/post-execute`, immediately before lossless materialization.
+   * Returning `undefined` preserves the content; every other result field
+   * remains registry-owned. The callback must be total and must not throw.
+   * @param exec - immutable execution identity and arguments.
+   * @param result - complete normalized outcome before materialization.
+   * @returns replacement content, or `undefined` to preserve it.
+   */
+  finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
   /**
    * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
    * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it
@@ -330,9 +342,9 @@ export interface ToolRegistryScheduler {
   prepare(exec: ToolExecutionInput): Promise<ScheduledToolPreparation>
   /** Run only the around-dispatch/body stage. */
   dispatch(exec: ToolRunContext): Promise<ScheduledToolDispatch>
-  /** Run ordered post-execute finalization, then materialize and notify the final outcome. */
+  /** Run post-execute and definition-owned content finalization, then materialize and notify. */
   finalize(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult>
-  /** Materialize and notify a final outcome that must bypass post-execute. */
+  /** Run definition-owned content finalization, then materialize and notify without post-execute. */
   finish(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult
 }
 
@@ -638,6 +650,8 @@ export class ToolRegistry extends Service {
   private deferredContexts = new WeakMap<ToolRunContext, HookContext[]>()
   /** Original caller cancellation, kept outside the wrapper-mutable execution object. */
   private cancellationStates = new WeakMap<ToolRunContext, ToolCancellationState>()
+  /** Definition-owned final content transform snapshotted before policy begins. */
+  private contentFinalizers = new WeakMap<ToolRunContext, ToolDefinition['finalizeContent']>()
   private readonly layers = new ScopedLayers(
     scope => new ToolLayer(scope),
     () => { this.ctx.emit('tools/change') },
@@ -715,7 +729,7 @@ export class ToolRegistry extends Service {
   /**
    * Register globally or in the calling agent scope. Scoped tools shadow
    * globals; duplicates within one layer and the reserved `run_code` name fail.
-   * @param definition - the tool schema, execution, and optional presentation functions.
+   * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
    * @returns the exact disposer that unregisters the tool.
    */
   register(definition: ToolDefinition): () => void {
@@ -910,10 +924,11 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Execute through pre-policy, guards, around-dispatch, post-policy, and final
-   * notification. Tool and listener failures resolve as materialized error
-   * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is
-   * the same lossless, frozen snapshot final observers receive. Cancellation
+   * Execute through pre-policy, guards, around-dispatch, post-policy,
+   * definition-owned content finalization, and final notification. Tool and
+   * listener failures resolve as materialized error results; an invisible tool
+   * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
+   * snapshot final observers receive. Cancellation
    * arriving after entry and before final result materialization skips a
    * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
    * successful started outcome with `ABORTED`; already-started work is still
@@ -952,6 +967,8 @@ export class ToolRegistry extends Service {
     const agent = exec.agent
     const parent = exec.parent
     const signal = exec.signal
+    const definition = this.get(name, agent)
+    const finalizeContent = definition?.finalizeContent?.bind(definition)
     const base = {
       token,
       callId,
@@ -970,6 +987,7 @@ export class ToolRegistry extends Service {
       }
       const execution: MutableToolRunContext = { ...base, arguments: deepFreeze(detached) }
       this.deferredContexts.set(execution, deferredContexts)
+      this.contentFinalizers.set(execution, finalizeContent)
       this.cancellationStates.set(execution, {
         callerSignal: signal,
         bodyInvoked: false,
@@ -977,6 +995,7 @@ export class ToolRegistry extends Service {
       return { kind: 'ready', exec: execution }
     } catch (error: unknown) {
       const execution: MutableToolRunContext = { ...base, arguments: undefined }
+      this.contentFinalizers.set(execution, finalizeContent)
       return { kind: 'final-result', exec: execution, result: toolErrorResult(error) }
     }
   }
@@ -1130,7 +1149,8 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Run ordered post-execute, then materialize and notify the final outcome.
+   * Run ordered post-execute, then apply definition-owned content finalization,
+   * materialize, and notify the final outcome.
    * @param exec - the prepared execution.
    * @param result - dispatch/pre result that still needs post-execute.
    * @returns the materialized final result.
@@ -1151,16 +1171,23 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Materialize and notify a final result that must bypass post-execute.
+   * Materialize the candidate, apply definition-owned content finalization,
+   * then materialize and notify the authoritative result.
    * @param exec - the prepared execution.
    * @param result - final result.
    * @returns the materialized final result.
    * @internal
    */
   private finishScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult {
+    let materializedResult: ToolExecutionResult
+    try {
+      materializedResult = this.materializeFinalResult(result)
+    } catch (error: unknown) {
+      materializedResult = this.materializeFinalResult(toolErrorResult(error))
+    }
     let finalResult: ToolExecutionResult
     try {
-      finalResult = this.materializeFinalResult(result)
+      finalResult = this.materializeFinalResult(this.applyFinalContent(exec, materializedResult))
     } catch (error: unknown) {
       finalResult = this.materializeFinalResult(toolErrorResult(error))
     }
@@ -1168,6 +1195,14 @@ export class ToolRegistry extends Service {
     return finalResult
   }
 
+  /** Apply the snapshotted tool-owned content transform without exposing other result fields. */
+  private applyFinalContent(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult {
+    const finalizeContent = this.contentFinalizers.get(exec)
+    if (finalizeContent === undefined) return result
+    const content = finalizeContent(exec, result)
+    return content === undefined ? result : { ...result, content }
+  }
+
   /** Notify observers without exposing a mutation or error channel into the outcome. */
   private notifyResult(exec: ToolExecution, result: ToolExecutionResult): void {
     // Freeze the registry's live object before observers receive its readonly

packages/core/tools/src/schema.ts

@@ -3,7 +3,7 @@
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import type { ToolDefinition, ToolRunContext, ToolResult } from './index.ts'
+import type { ToolDefinition, ToolExecution, ToolExecutionResult, ToolRunContext, ToolResult } from './index.ts'
 import { assertSupportedJsonSchema, isJsonSchemaRecord, isPlainJsonArray, JsonSchemaError, validateJsonSchemaValue } from './json-schema.ts'
 import type { JsonSchemaNode, JsonSchemaScalar, ObjectJsonSchema } from './json-schema.ts'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
@@ -511,6 +511,15 @@ export interface DefineToolOptions<S extends ParameterSchemaSpec, O extends Valu
    * @returns The canonical value declared by `output.schema`.
    */
   execute(args: InferArgs<S>, exec: ToolRunContext): Promise<InferValue<NoInfer<O>>>
+  /**
+   * Optional last-mile content transform for every normalized outcome. Unlike
+   * `execute`, arguments remain `unknown` because invalid-input failures also
+   * reach this callback. See {@link ToolDefinition.finalizeContent}.
+   * @param exec - immutable execution identity and arguments.
+   * @param result - complete normalized outcome before materialization.
+   * @returns replacement content, or `undefined` to preserve it.
+   */
+  finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
   /**
    * Pure pending-state presenter.
    * @param args - typed validated arguments.
@@ -530,7 +539,7 @@ export interface DefineToolOptions<S extends ParameterSchemaSpec, O extends Valu
  * Define a first-party tool with inferred arguments and strict execution
  * validation. Replay-only presenters validate softly and fall back to generic
  * rendering for obsolete logged arguments.
- * @param options - typed definition and optional presenters.
+ * @param options - typed definition and optional finalizer and presenters.
  * @returns A registry-ready definition.
  */
 export function defineTool<const S extends ParameterSchemaSpec, const O extends ValueSchemaSpec>(
@@ -540,6 +549,8 @@ export function defineTool<const S extends ParameterSchemaSpec, const O extends
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const userExecute = options.execute
   // eslint-disable-next-line @typescript-eslint/unbound-method
+  const userFinalizeContent = options.finalizeContent
+  // eslint-disable-next-line @typescript-eslint/unbound-method
   const userRender = options.output.render
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const userPresentationMeta = options.output.presentationMeta
@@ -577,6 +588,13 @@ export function defineTool<const S extends ParameterSchemaSpec, const O extends
       return userExecute(args as InferArgs<S>, exec) as Promise<JsonValue>
     },
   }
+  if (userFinalizeContent) {
+    tool.finalizeContent = (exec, result) => userFinalizeContent(exec, result)
+  }
+  // Presentation is display-only and may run on REPLAY of arbitrary logged args
+  // (possibly from an older schema), so it must never throw: validate softly and
+  // fall back to `undefined` (a generic UI presentation) on any mismatch, rather
+  // than the hard `ToolArgsError` the execute path raises.
   if (userPresentCall) {
     tool.presentCall = (args: unknown): ToolCallView | undefined => {
       if (validate(args).length > 0) return undefined

packages/core/tools/tests/tools.spec.ts

@@ -51,22 +51,22 @@ describe('ToolRegistry', () => {
     expect(assembly.tools.map(t => t.name)).toEqual(['echo'])
   })
 
-  it('schemas() drops the UI presentation callbacks — they must never reach the model', async () => {
+  it('schemas() drops host callbacks — they must never reach the model', async () => {
     const ctx = await setup()
-    // A tool that declares presentCall/presentResult (functions). schemas() feeds
-    // the system-prompt assembly → the model request, so those callbacks (and
-    // `execute`) must be stripped: a function in the JSON tool schema would
-    // corrupt the request. schemas() is an explicit allowlist, so it can't leak.
+    // Tool definitions contain output, finalization, execution, and presentation
+    // callbacks. schemas() is an explicit allowlist so none can reach the model.
     ctx.tools.register(defineContentToolFixture({
       name: 'present',
       description: 'has presenters',
       parameters: { x: { type: 'string', required: true } },
       async execute() { return [] },
+      finalizeContent: (_exec, result) => result.content,
       presentCall: args => ({ card: 'generic', title: args.x }),
       presentResult: (args, result) => ({ card: 'generic', title: args.x, content: result.content }),
     }))
     const schema = ctx.tools.schemas()[0] as unknown as Record<string, unknown>
     expect(Object.keys(schema).sort()).toEqual(['description', 'name', 'parameters'])
+    expect(schema.finalizeContent).toBeUndefined()
     expect(schema.presentCall).toBeUndefined()
     expect(schema.presentResult).toBeUndefined()
     expect(schema.execute).toBeUndefined()
@@ -155,6 +155,72 @@ describe('ToolRegistry', () => {
     expect(observedError).toBe(true)
   })
 
+  it('finalizes errors discovered while snapshotting non-content result fields', async () => {
+    const ctx = await setup()
+    let finalizeCalls = 0
+    ctx.tools.register({
+      ...echoTool,
+      name: 'throwing-meta',
+      output: {
+        ...echoTool.output,
+        presentationMeta() {
+          const meta = {}
+          Object.defineProperty(meta, 'value', {
+            enumerable: true,
+            get() { throw new Error('snapshot failed: '.repeat(100)) },
+          })
+          return meta
+        },
+      },
+      finalizeContent(_exec, result) {
+        finalizeCalls += 1
+        const block = result.content[0]
+        if (block?.type !== 'text') return undefined
+        return [{ type: 'text', text: block.text.slice(0, 32) }]
+      },
+      async execute() {
+        return 'body'
+      },
+    })
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('throwing-meta'), name: 'throwing-meta', arguments: {},
+    })
+
+    expect(result.isError).toBe(true)
+    const block = result.content[0]
+    expect(block?.type).toBe('text')
+    expect(block?.type === 'text' ? block.text : '').toMatch(/^Error: tool "throwing-meta"/)
+    expect(block?.type === 'text' ? block.text : '').toHaveLength(32)
+    expect(finalizeCalls).toBe(1)
+  })
+
+  it('normalizes a throwing final content callback without invoking it again', async () => {
+    const ctx = await setup()
+    let finalizeCalls = 0
+    ctx.tools.register({
+      ...echoTool,
+      name: 'throwing-finalizer',
+      finalizeContent() {
+        finalizeCalls += 1
+        throw new Error('finalizer violated its total contract')
+      },
+    })
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('throwing-finalizer'), name: 'throwing-finalizer', arguments: {},
+    })
+
+    expect(result).toEqual({
+      content: [{ type: 'text', text: 'Error: finalizer violated its total contract' }],
+      isError: true,
+      error: { message: 'finalizer violated its total contract' },
+    })
+    expect(finalizeCalls).toBe(1)
+  })
+
   it('requires every raw registration to declare its canonical output', async () => {
     const ctx = await setup()
     const missingOutput = {
@@ -747,6 +813,36 @@ describe('ToolRegistry', () => {
     expect(result.content[0]).toMatchObject({ text: 'output rejected: try again' })
   })
 
+  it('runs the snapshotted final content transform after outer pipeline normalization', async () => {
+    const ctx = await setup()
+    const dispose = ctx.tools.register(defineContentToolFixture({
+      name: 'bounded',
+      description: 'bounded result',
+      parameters: {},
+      async execute() { return [{ type: 'text', text: 'body' }] },
+      finalizeContent(exec, result) {
+        expect(exec.name).toBe('bounded')
+        expect(result.isError).toBe(true)
+        return [{ type: 'text', text: 'bounded failure' }]
+      },
+    }))
+    ctx.on('tools/pre-execute', async () => {
+      dispose()
+      throw new HarnessError('policy failed', 'POLICY_FAILED')
+    })
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('bounded'), name: 'bounded', arguments: {} })
+
+    expect(result).toEqual({
+      content: [{ type: 'text', text: 'bounded failure' }],
+      isError: true,
+      error: {
+        message: 'policy failed',
+        info: { name: 'HarnessError', code: 'POLICY_FAILED' },
+      },
+    })
+  })
+
   it('a block decision can ALSO attach additionalContexts', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)

packages/examples/acp-demo/README.md

@@ -15,7 +15,7 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it
 | `@deepseek-ai/dsh-command-goal` | the discoverable direct `/goal` producer; the app enables the spine's persisted-goal stack with it |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by clients that can complete ACP elicitation requests |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) |
-| `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | exact current-surface reads and bounded `dsh-session:` snapshots |
+| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | combined exact/FTS session queries and bounded `dsh-session:` snapshots |
 | `@deepseek-ai/dsh-session-checkpoint-policy` | semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
 | `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers when a leaf explicitly exposes a user-question tool |
 | ~~`@deepseek-ai/dsh-tool-ask-user`~~ | **omitted by default** — ACP elicitation support is still client-dependent, so leaves must opt in deliberately |
@@ -43,7 +43,7 @@ The app owns this cluster through one ordered Cordis effect. Teardown drains the
 | `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
 | `goals` | owner defaults | persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
 | `llmRetry` | owner defaults | bounded transient model-request retry policy routed through `dsh-agent-spine-demo` |
-| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
+| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory and the parent of the derived `session-query.db` index |
 | `packChunks` | `false` | write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`) |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
 | `sessionReferences` | service defaults | cross-session candidate and snapshot limits routed to `dsh-session-reference` |

packages/examples/acp-demo/package.json

@@ -46,6 +46,7 @@
     "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
     "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
     "@deepseek-ai/dsh-session-reference": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-user-interaction": "^0.0.1",
@@ -66,6 +67,7 @@
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",

packages/examples/acp-demo/src/index.ts

@@ -12,6 +12,7 @@
  */
 
 import type { Context } from 'cordis'
+import { join } from 'node:path'
 import z from 'schemastery'
 import * as acp from '@deepseek-ai/dsh-acp'
 import CommandService from '@deepseek-ai/dsh-commands'
@@ -25,7 +26,7 @@ import SessionPersistenceJsonl, {
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQueryService from '@deepseek-ai/dsh-session-query'
+import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
 
 export const name = 'acp-demo'
@@ -57,7 +58,7 @@ export interface Config {
   dshHome?: string
   /** Fallback session-title limits forwarded through agent-spine-demo. */
   sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
   persistenceRoot?: string
   /** Write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`). Defaults to `false`. */
   packChunks?: boolean
@@ -110,14 +111,16 @@ export const Config: z<Config> = z.object({
 /**
  * Compose the spine with the ACP front door. The agent-spine-demo bundle pre-creates
  * NO agents (its `agents` list defaults to `[]`) and carries the deployment
- * `persona`; the JSONL backend persists under `persistenceRoot`; the ACP
- * bridge owns stdout for JSON-RPC and creates one agent per `session/new`
- * from the provider/model pair. The composite effect unloads in reverse order,
- * keeping checkpoint and persistence listeners attached until ACP agents have
- * flushed their closing events. No logger, no `hmr` — stdout stays pure.
+ * `persona`; the JSONL backend and derived query index persist under
+ * `persistenceRoot`; the ACP bridge owns stdout for JSON-RPC and creates one
+ * agent per `session/new` from the provider/model pair. The composite effect
+ * unloads in reverse order, keeping checkpoint and persistence listeners
+ * attached until ACP agents have flushed their closing events. No logger, no
+ * `hmr` — stdout stays pure.
  */
 export function apply(ctx: Context, config: Config): void {
   const goals = config.goals ?? {}
+  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
   ctx.effect(function* () {
     yield ctx.plugin(CommandService).dispose
     if (goals !== false) yield ctx.plugin(commandGoal).dispose
@@ -127,13 +130,13 @@ export function apply(ctx: Context, config: Config): void {
     // persistence passthroughs rather than sharing a facade with stdio-demo.
     /* jscpd:ignore-start */
     yield ctx.plugin(SessionPersistenceJsonl, {
-      root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
+      root: persistenceRoot,
       ...config.packChunks !== undefined ? { packChunks: config.packChunks } : {},
       ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
     }).dispose
     /* jscpd:ignore-end */
     yield ctx.plugin(sessionCheckpointPolicy).dispose
-    yield ctx.plugin(SessionQueryService).dispose
+    yield ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') }).dispose
     yield ctx.plugin(SessionReferenceService, config.sessionReferences ?? {}).dispose
     yield ctx.plugin(acp, { provider: config.provider, model: config.model }).dispose
   }, 'acp-demo.composition')

packages/examples/acp-demo/tests/built-bin.e2e.ts

@@ -36,7 +36,8 @@ const dshPackages = [
   'bash/bash-local', 'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
   'session-persistence/session-persistence',
   'session-persistence/session-checkpoint-policy', 'session-persistence/session-persistence-jsonl',
-  'session-query/session-query', 'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
+  'session-query/session-query', 'session-query/session-query-sqlite',
+  'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
   'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',

packages/examples/acp-demo/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../session-query/session-query"
     },
+    {
+      "path": "../../session-query/session-query-sqlite"
+    },
     {
       "path": "../../context/session-reference"
     },

packages/examples/tui-demo/README.md

@@ -13,7 +13,7 @@ Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and
 | `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-session-checkpoint-policy` | Semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
-| `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | Exact current-surface reads and bounded `@session` snapshots consumed by the TUI |
+| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | Combined exact/FTS session queries and bounded `@session` snapshots consumed by the TUI |
 | `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service |
 | `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays |
 | `@deepseek-ai/dsh-tool-ask-user` | Model-facing `ask_user_question` tool |
@@ -37,7 +37,7 @@ Swappable LLM, bash, filesystem, and other capability providers remain in the le
 | `toolTasks` | owner defaults | Background-task control-tool config, or `false` |
 | `goals` | owner defaults | Persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
 | `workspaceContext` | required | Workspace-instruction config, or `false` |
-| `persistenceRoot` | `./.sessions` | JSONL persistence root |
+| `persistenceRoot` | `./.sessions` | JSONL persistence root and parent of the derived `session-query.db` index |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
 | `sessionReferences` | service defaults | Cross-session candidate and snapshot limits routed to `dsh-session-reference` |
 | `welcome` | `ready.` | TUI subtitle |

packages/examples/tui-demo/package.json

@@ -48,6 +48,7 @@
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
     "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
     "@deepseek-ai/dsh-session-reference": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
     "@deepseek-ai/dsh-tui": "^0.0.1",
@@ -72,6 +73,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
     "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",

packages/examples/tui-demo/src/index.ts

@@ -10,6 +10,7 @@
 
 import type { Context } from 'cordis'
 import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
 import z from 'schemastery'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
@@ -23,7 +24,7 @@ import SessionPersistenceJsonl, {
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQueryService from '@deepseek-ai/dsh-session-query'
+import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
 import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as uiTui from '@deepseek-ai/dsh-tui'
@@ -52,7 +53,7 @@ export interface Config {
   dshHome?: string
   /** Fallback session-title limits forwarded through agent-spine-demo. */
   sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
   persistenceRoot?: string
   /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
   persistenceCompression?: JsonlCompression
@@ -119,14 +120,15 @@ export function composeTuiApp(ctx: Context, config: Config): void {
   const resumeSessionId = config.resumeSessionId === '' ? undefined : config.resumeSessionId
   const sessionId = SessionId(resumeSessionId ?? `main-session-${randomUUID()}`)
   const goals = config.goals ?? {}
+  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
   ctx.plugin(CommandService)
   if (goals !== false) ctx.plugin(commandGoal)
   ctx.plugin(SessionPersistenceJsonl, {
-    root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
+    root: persistenceRoot,
     ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
   })
   ctx.plugin(sessionCheckpointPolicy)
-  ctx.plugin(SessionQueryService)
+  ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') })
   ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
   ctx.plugin(UserInteractionService)
   ctx.plugin(uiTui, {

packages/examples/tui-demo/tests/tui-agent.spec.ts

@@ -51,7 +51,7 @@ describe('dsh-tui-demo app', () => {
       'command-goal',
       'SessionPersistenceJsonl',
       'session-checkpoint-policy',
-      'SessionQueryService',
+      'SessionQuerySqlite',
       'SessionReferenceService',
       'UserInteractionService',
       'ui-tui',
@@ -60,6 +60,7 @@ describe('dsh-tui-demo app', () => {
     ])
     expect(calls[0]?.config).toBeUndefined()
     expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
+    expect(calls[4]?.config).toEqual({ path: '/tmp/tui-sessions/session-query.db' })
     expect(calls[5]?.config).toEqual({
       maxReferences: 2,
       candidateLimit: 7,

packages/examples/tui-demo/tsconfig.json

@@ -29,6 +29,9 @@
     {
       "path": "../../session-query/session-query"
     },
+    {
+      "path": "../../session-query/session-query-sqlite"
+    },
     {
       "path": "../../context/session-reference"
     },

packages/host/apiproxy/src/api/events.schema.ts

@@ -17,6 +17,7 @@ export const askUserQuestionItemSchema = z.object({
   id: z.string(),
   question: z.string(),
   header: z.string().optional(),
+  detail: z.string().optional(),
   options: z.array(z.object({ label: z.string(), description: z.string().optional() })).optional(),
   multiSelect: z.boolean().optional(),
 }) satisfies z.ZodType<Wire<AskUserQuestionItem>>
@@ -27,7 +28,10 @@ export const muxFrameSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('session/subscribed'), sessionId: sessionIdSchema, lastSeq: z.number().int() }),
   z.object({ type: z.literal('approval/requested'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, toolName: z.string(), callId: z.string().optional(), reason: z.string().optional() }),
   z.object({ type: z.literal('approval/resolved'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]) }),
-  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema) }),
+  // Non-empty by wire contract: the user-interaction service rejects empty
+  // batches at ask() (EMPTY_QUESTIONS), so an empty frame is host breakage
+  // and must fail loud here, not reach the composer.
+  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema).min(1) }),
   z.object({ type: z.literal('question/resolved'), sessionId: sessionIdSchema, questionRpcId: rpcIdSchema, outcome: z.union([z.literal('answered'), z.literal('cancelled')]) }),
   z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
 ]) as unknown as z.ZodType<MuxFrame>

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -33,6 +33,7 @@ export const rpcIdSchema = z.string() as unknown as z.ZodType<RpcId>
 /** Error body: discriminated by code, per-branch details aligned to RpcErrorDetailsMap; details is required. */
 export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code', [
   z.object({ code: z.literal('bad-request'), message: z.string(), details: z.object({ issues: z.array(z.custom<ZodIssue>()) }) }),
+  z.object({ code: z.literal('cancelled'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
   z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),

packages/host/apiproxy/src/api/rpc.ts

@@ -30,6 +30,7 @@ export function RpcId(id: string): RpcId {
 /** Error code → details type map (a second table isomorphic to RpcMethodMap). New code = one row here + one branch in the error schema. */
 export interface RpcErrorDetailsMap {
   'bad-request': { issues: ZodIssue[] }
+  'cancelled': {}
   'session-not-found': { sessionId: SessionId }
   'agent-busy': { reason: string }
   'internal': {}

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -29,6 +29,7 @@ describe('RpcId', () => {
 describe('rpcErrorSchema', () => {
   it('accepts every code branch with its required details', () => {
     expect(rpcErrorSchema.parse({ code: 'bad-request', message: 'm', details: { issues: [] } }).code).toBe('bad-request')
+    expect(rpcErrorSchema.parse({ code: 'cancelled', message: 'm', details: {} }).code).toBe('cancelled')
     expect(rpcErrorSchema.parse({ code: 'session-not-found', message: 'm', details: { sessionId: 's' } }).code).toBe('session-not-found')
     expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
     expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
@@ -134,6 +135,10 @@ describe('events frame schemas', () => {
     expect(askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?' }).id).toBe('q')
   })
 
+  it('rejects an empty question batch (ask() guarantees at least one, so an empty frame is host breakage)', () => {
+    expect(() => muxFrameSchema.parse({ type: 'question/requested', sessionId: 's', questions: [] })).toThrow()
+  })
+
   it('accepts every host frame branch', () => {
     const frames = [
       { type: 'host/session-added', sessionId: 's', parentSessionId: 'p' },

packages/host/runtime/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-host-runtime
 
-Host runtime assembly for `dsh`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence, system prompt, tools, agents, agent loop, workspace instructions, local bash), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
+Host runtime assembly for `dsh`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence, system prompt, tools, agents, agent loop, workspace instructions, local bash, and the provider-neutral user-interaction service), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
 
 Which plugins mount and with what defaults is decided only here — shells must not `ctx.plugin` to alter the assembly. `RunningHost.ctx` is a formal seam with exactly two sanctioned uses: mounting protocol front-door plugins (e.g. a future `dsh acp`) and headless session-event subscription; consuming clients must not bypass `api` through it.
 
@@ -15,7 +15,7 @@ Which plugins mount and with what defaults is decided only here — shells must
 
 ## ApiProxy implementation notes
 
-Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session on open; the host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
+Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session and every still-pending question with its original rpcId. Question responses, including blank per-item answers, are validated against the owning session and exact request before an atomic first-wins claim; answer, whole-request cancellation, owner abort, and provider disposal broadcast `question/resolved`. The host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
 
 ## Model Experience
 
@@ -27,6 +27,6 @@ No direct invalidation; the mounted model-facing plugins own their request-prefi
 
 ## Known Limitations and Deferred Work
 
-- **`respond` is a stub** — it always returns `not-pending`; the approval/question pending registry (stable-rpcId mint on accept, baseline replay on stream reopen, wire answerer) is the next host-side step.
+- **Question waits are process-memory state** — browser reconnects recover them, but a host process restart aborts the owning tool call instead of restoring the wait from persistence.
 - **`host.describe.version` is a placeholder** — it does not yet report the `apps/cli` package version.
 - **The assembly is fixed** — per-deployment plugin selection (user profile, log sinks, alternative persistence) has a documented home here but no configuration surface yet.

packages/host/runtime/package.json

@@ -36,6 +36,7 @@
     "@deepseek-ai/dsh-client-i18n": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-question": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
     "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
     "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
@@ -69,6 +70,7 @@
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@deepseek-ai/dsh-tool-workflow": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
     "@deepseek-ai/dsh-workspace-context": "workspace:^",
     "@deepseek-ai/dsh-workflow-workerthread": "workspace:^"
   },

packages/host/runtime/src/api-proxy.ts

@@ -1,8 +1,6 @@
 /**
- * Host-side ApiProxy implementation (minimal-first —
- * describe/list/create/history/prompt/cancel and both streams are real,
- * respond is a stub). Signature discipline: unary takes the narrow
- * RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
+ * Host-side ApiProxy implementation. Signature discipline: unary takes the
+ * narrow RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
  */
 
 import { randomUUID } from 'node:crypto'
@@ -12,9 +10,16 @@ import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
-import type { ApiProxy, HistoryEntry, HostFrame, MuxFrame, SessionSummary, ToolEventView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type {
+  ApiProxy, HistoryEntry, HostFrame, MuxFrame, QuestionResponsePayload, SessionSummary, ToolEventView,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+import { questionResponsePayloadSchema } from '@deepseek-ai/dsh-host-apiproxy/api/questions.schema'
 import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import type {
+  AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionRequest,
+} from '@deepseek-ai/dsh-user-interaction'
+import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
 
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -155,6 +160,35 @@ interface ToolCallData { callId: string; name: string; arguments: string }
 /** The tool/result payload fields the presenter path reads. */
 interface ToolResultData { callId: string; content: ContentBlock[]; isError: boolean; meta?: JsonValue }
 
+/** One host-owned question wait, addressed by the stable server-request id. */
+interface PendingQuestion {
+  rpcId: RpcId
+  sessionId: SessionId
+  questions: AskUserQuestionItem[]
+  resolve: (answer: AskUserQuestionAnswer) => void
+  reject: (error: UserInteractionError) => void
+  signal?: AbortSignal
+  onAbort?: () => void
+}
+
+/** Validate one answer batch against the exact question request it resolves. */
+function matchesQuestions(payload: QuestionResponsePayload, pending: PendingQuestion): boolean {
+  if (payload.sessionId !== pending.sessionId) return false
+  const answers = payload.answer.answers
+  if (answers.length !== pending.questions.length) return false
+  return answers.every((answer, index) => {
+    const question = pending.questions[index] as AskUserQuestionItem
+    if (answer.id !== question.id) return false
+    if (new Set(answer.selected).size !== answer.selected.length) return false
+    const custom = answer.custom?.trim()
+    if (custom !== undefined && custom === '') return false
+    if (custom !== undefined && answer.selected.length > 0) return false
+    if (question.multiSelect !== true && answer.selected.length > 1) return false
+    const labels = new Set(question.options?.map(option => option.label) ?? [])
+    return answer.selected.every(label => labels.has(label))
+  })
+}
+
 /**
  * Compute the render intent for a tool/call or tool/result event through the
  * presenters registered at this moment; every other event type gets none. A
@@ -219,12 +253,70 @@ class SessionNotFound extends Error {}
  * @param ctx - the root context returned by bootHost (sessions/agents services mounted).
  * @param defaults - host-level default provider/model: injected as
  * agentOptions on create/resume, reported by describe from the same source.
- * @returns the ApiProxy implementation (minimal-first; stubs noted per method).
+ * @returns the ApiProxy implementation.
  */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
   const agentOptions = { provider: defaults.provider, model: defaults.model }
   /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
   const resumes = new Map<SessionId, Promise<Agent>>()
+  const pendingQuestions = new Map<RpcId, PendingQuestion>()
+  const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()
+
+  /** Send one transient frame to every connected mux consumer. */
+  function broadcast(payload: MuxFrame): void {
+    const envelope = frame(payload)
+    for (const queue of muxQueues) queue.push(envelope)
+  }
+
+  /** Remove a wait before settling it: synchronous deletion makes the first claimant win. */
+  function claimQuestion(pending: PendingQuestion, outcome: 'answered' | 'cancelled'): void {
+    pendingQuestions.delete(pending.rpcId)
+    if (pending.signal !== undefined && pending.onAbort !== undefined) {
+      pending.signal.removeEventListener('abort', pending.onAbort)
+    }
+    broadcast({
+      type: 'question/resolved', sessionId: pending.sessionId,
+      questionRpcId: pending.rpcId, outcome,
+    })
+  }
+
+  const disposeProvider = ctx.userInteraction.registerProvider({
+    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer> {
+      const sessionId = request.agent?.id
+      if (sessionId === undefined) {
+        return Promise.reject(new UserInteractionError(
+          'web user interaction requires an agent-owned session', 'ASK_MISSING_AGENT'))
+      }
+      return new Promise<AskUserQuestionAnswer>((resolve, reject) => {
+        const rpcId = RpcId(randomUUID())
+        const pending: PendingQuestion = {
+          rpcId, sessionId, questions: request.questions, resolve, reject,
+          ...(request.signal === undefined ? {} : { signal: request.signal }),
+        }
+        const onAbort = (): void => {
+          claimQuestion(pending, 'cancelled')
+          reject(new UserInteractionError(
+            'ask_user_question was aborted before the user answered', 'ASK_ABORTED'))
+        }
+        pending.onAbort = onAbort
+        pendingQuestions.set(rpcId, pending)
+        request.signal?.addEventListener('abort', onAbort, { once: true })
+        const envelope: RpcRequest<MuxFrame> = {
+          rpcId,
+          payload: { type: 'question/requested', sessionId, questions: request.questions },
+        }
+        for (const queue of muxQueues) queue.push(envelope)
+      })
+    },
+  })
+  ctx.effect(() => () => {
+    disposeProvider()
+    for (const pending of [...pendingQuestions.values()]) {
+      claimQuestion(pending, 'cancelled')
+      pending.reject(new UserInteractionError(
+        'web user-interaction provider was disposed', 'ASK_ABORTED'))
+    }
+  }, 'api-proxy: user-interaction provider')
 
   /**
    * Gate the cold path on the store: an id absent from it, or naming a legacy
@@ -361,9 +453,19 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     events: {
       mux(_request, signal) {
         const queue = new FrameQueue<RpcRequest<MuxFrame>>()
+        muxQueues.add(queue)
         for (const session of ctx.sessions.list()) {
           queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
         }
+        for (const pending of pendingQuestions.values()) {
+          queue.push({
+            rpcId: pending.rpcId,
+            payload: {
+              type: 'question/requested', sessionId: pending.sessionId,
+              questions: pending.questions,
+            },
+          })
+        }
         // Per-session open-call table for result-view pairing. Bounded by the
         // per-turn call count: entries clear on turn/end; a table miss (stream
         // opened mid-turn) backscans the session's in-memory events instead.
@@ -393,7 +495,10 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             openCalls.delete(session.id)
           }),
         ]
-        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+        return queue.iterate(signal, () => {
+          muxQueues.delete(queue)
+          for (const dispose of disposers) dispose()
+        })
       },
 
       host(_request, signal) {
@@ -421,9 +526,38 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       },
     },
 
-    // TODO(step2): approval/question pending registry (wire answerer + proxy provider).
-    respond(_message: ClientResponse): Promise<RpcReceipt> {
-      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+    respond(message: ClientResponse): Promise<RpcReceipt> {
+      const pending = pendingQuestions.get(message.rpcId)
+      if (pending === undefined) return Promise.resolve({ accepted: false, reason: 'not-pending' })
+      if (!message.result.ok) {
+        if (message.result.error.code !== 'cancelled') {
+          return Promise.resolve({ accepted: false, reason: 'bad-response' })
+        }
+        claimQuestion(pending, 'cancelled')
+        pending.reject(new UserInteractionError(
+          'the user cancelled ask_user_question', 'ASK_CANCELLED'))
+        return Promise.resolve({ accepted: true })
+      }
+      const parsed = questionResponsePayloadSchema.safeParse(message.result.value)
+      if (!parsed.success) {
+        return Promise.resolve({ accepted: false, reason: 'bad-response' })
+      }
+      const payload: QuestionResponsePayload = {
+        sessionId: parsed.data.sessionId,
+        answer: {
+          answers: parsed.data.answer.answers.map(answer => ({
+            id: answer.id,
+            selected: answer.selected,
+            ...(answer.custom === undefined ? {} : { custom: answer.custom }),
+          })),
+        },
+      }
+      if (!matchesQuestions(payload, pending)) {
+        return Promise.resolve({ accepted: false, reason: 'bad-response' })
+      }
+      claimQuestion(pending, 'answered')
+      pending.resolve(payload.answer)
+      return Promise.resolve({ accepted: true })
     },
   }
 }

packages/host/runtime/src/boot.ts

@@ -38,6 +38,7 @@ import * as toolWorkflow from '@deepseek-ai/dsh-tool-workflow'
 import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
 import SpillLocal from '@deepseek-ai/dsh-spill-local'
 import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 
 /** Options for bootHost — the assembly-layer composition knobs. */
 export interface BootHostOptions {
@@ -94,6 +95,7 @@ export async function bootHost(options: BootHostOptions): Promise<HostHandle> {
   await ctx.plugin(SessionStore)
   await ctx.plugin(SystemPrompt, { persona: '' })
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(TaskService)
   await ctx.plugin(AgentLoop, { agents: [] })

packages/host/runtime/src/web-plugins.ts

@@ -1,16 +1,16 @@
 /**
  * Web UI plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
- * entry tree listing the eight UI plugin packages (the P-I config-source bar —
+ * entry tree listing the nine UI plugin packages (the P-I config-source bar —
  * a cordis.yml file form comes later; install/remove currently means editing
  * this list and restarting). The web plugin registry discovers the entries by
- * their package.json dshClient declarations; node halves are empty applies,
- * so mounting them here costs nothing beyond Loader governance.
+ * their package.json dshClient declarations; feature packages may also mount
+ * their interface-specific host half through the same lifecycle.
  */
 import { createRequire } from 'node:module'
 import type { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 
-/** The eight UI plugin packages served to the browser (order = manifest order). */
+/** The nine UI plugin packages served to the browser (order = manifest order). */
 export const WEB_UI_PLUGINS = [
   '@deepseek-ai/dsh-client-connection',
   '@deepseek-ai/dsh-client-runtime',
@@ -19,6 +19,7 @@ export const WEB_UI_PLUGINS = [
   '@deepseek-ai/dsh-client-ui-layout',
   '@deepseek-ai/dsh-client-ui-sidebar',
   '@deepseek-ai/dsh-client-ui-conversation',
+  '@deepseek-ai/dsh-client-ui-question',
   '@deepseek-ai/dsh-client-ui-trajectory',
 ] as const
 
@@ -41,7 +42,7 @@ export interface MountedWebPlugins {
 export async function mountWebPlugins(ctx: Context): Promise<MountedWebPlugins> {
   // The Loader resolves bare specifiers against ctx.baseUrl; without one the
   // import silently fails and every entry stays fiber-less. This package
-  // depends on all eight UI plugins, so its own URL is the right anchor.
+  // depends on all nine UI plugins, so its own URL is the right anchor.
   ctx.baseUrl ??= import.meta.url
   if (ctx.get('loader') === undefined) await ctx.plugin(Loader)
   const existing = new Set([...ctx.loader.entries()].map(entry => entry.options.name))

packages/host/runtime/tests/api-proxy-cold.spec.ts

@@ -12,6 +12,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -32,6 +33,7 @@ describe('sessions.list cold merge', () => {
   it('summarizes unattached sessions: log mtime, locate-less and vanished-log createdAt fallbacks, lineage', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
+    await ctx.plugin(UserInteractionService)
     const root = mkdtempSync(join(tmpdir(), 'dsh-cold-'))
     const logPath = join(root, 'a.log')
     writeFileSync(logPath, 'log-bytes')
@@ -76,6 +78,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
     const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
 
     const listed = await api.sessions.list(request({}))

packages/host/runtime/tests/api-proxy-view.spec.ts

@@ -18,6 +18,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { createApiProxy } from '../src/api-proxy.ts'
@@ -39,6 +40,7 @@ async function harness(): Promise<{ ctx: Context }> {
   await ctx.plugin(SessionStore)
   await ctx.plugin(SystemPrompt, { persona: '' })
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   ctx.tools.register(tool('gen', {
     presentCall: () => ({ card: 'generic', title: 'gen call' }),

packages/host/runtime/tests/host-runtime.spec.ts

@@ -418,10 +418,175 @@ describe('events streams', () => {
   })
 })
 
-describe('respond stub', () => {
-  it('always reports not-pending (step2 registry pending)', async () => {
-    const { api } = await boot()
-    const receipt = await api.respond({ type: 'client-response', rpcId: RpcId('r'), result: { ok: true, value: null } })
-    expect(receipt).toEqual({ accepted: false, reason: 'not-pending' })
+describe('question request / response', () => {
+  const questions = [{
+    id: 'mode', question: 'Choose a mode',
+    options: [
+      { label: 'Fast (Recommended)', description: 'Move quickly.' },
+      { label: 'Careful', description: 'Review first.' },
+    ],
+  }]
+
+  it('waits, replays the same rpcId on reconnect, validates, and resolves first-wins', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    await stream.next() // subscribed baseline starts the generator and installs the queue
+
+    const answerPromise = ctx.userInteraction.ask({ questions, agent })
+    const requested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(requested.payload).toMatchObject({ type: 'question/requested', sessionId, questions })
+
+    const wrongSession = await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId: 'session-other', answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }] } },
+      },
+    })
+    expect(wrongSession).toEqual({ accepted: false, reason: 'bad-response' })
+    const badChoice = await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Unknown'] }] } },
+      },
+    })
+    expect(badChoice).toEqual({ accepted: false, reason: 'bad-response' })
+    const invalidResults = [
+      { ok: true as const, value: null },
+      { ok: true as const, value: { sessionId, answer: { answers: [] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'wrong', selected: ['Fast (Recommended)'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)', 'Fast (Recommended)'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)', 'Careful'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: [], custom: '   ' }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Careful'], custom: 'Other' }] } } },
+      { ok: false as const, error: { code: 'internal' as const, message: 'wrong error', details: {} } },
+    ]
+    for (const result of invalidResults) {
+      expect(await api.respond({
+        type: 'client-response', rpcId: requested.rpcId, result,
+      })).toEqual({ accepted: false, reason: 'bad-response' })
+    }
+
+    const reconnectAbort = new AbortController()
+    const replay = api.events.mux(request({}), reconnectAbort.signal)[Symbol.asyncIterator]()
+    await replay.next()
+    const replayed = (await replay.next()).value as RpcRequest<MuxFrame>
+    expect(replayed.rpcId).toBe(requested.rpcId)
+    expect(replayed.payload).toEqual(requested.payload)
+
+    const response = {
+      type: 'client-response' as const,
+      rpcId: requested.rpcId,
+      result: {
+        ok: true as const,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }] } },
+      },
+    }
+    const [first, duplicate] = await Promise.all([api.respond(response), api.respond(response)])
+    expect([first, duplicate]).toContainEqual({ accepted: true })
+    expect([first, duplicate]).toContainEqual({ accepted: false, reason: 'not-pending' })
+    await expect(answerPromise).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }],
+    })
+
+    const resolved = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(resolved.payload).toMatchObject({
+      type: 'question/resolved', sessionId, questionRpcId: requested.rpcId, outcome: 'answered',
+    })
+    expect(await api.respond(response)).toEqual({ accepted: false, reason: 'not-pending' })
+
+    const customQuestions = [{ id: 'detail', question: 'What else?' }]
+    const customAnswer = ctx.userInteraction.ask({ questions: customQuestions, agent })
+    const customRequested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: customRequested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'detail', selected: [], custom: 'Keep traces' }] } },
+      },
+    })).toEqual({ accepted: true })
+    await expect(customAnswer).resolves.toEqual({
+      answers: [{ id: 'detail', selected: [], custom: 'Keep traces' }],
+    })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: customRequested.rpcId, outcome: 'answered',
+    })
+
+    const blankAnswer = ctx.userInteraction.ask({ questions, agent })
+    const blankRequested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: blankRequested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: [] }] } },
+      },
+    })).toEqual({ accepted: true })
+    await expect(blankAnswer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: [] }],
+    })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: blankRequested.rpcId, outcome: 'answered',
+    })
+    ac.abort()
+    reconnectAbort.abort()
+  })
+
+  it('distinguishes user cancellation from owner abort and rejects late responses', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const streamAbort = new AbortController()
+    const stream = api.events.mux(request({}), streamAbort.signal)[Symbol.asyncIterator]()
+    await stream.next()
+
+    const cancelled = ctx.userInteraction.ask({ questions, agent }).catch((error: unknown) => error)
+    const requested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: { ok: false, error: { code: 'cancelled', message: 'skip', details: {} } },
+    })).toEqual({ accepted: true })
+    await expect(cancelled).resolves.toMatchObject({ code: 'ASK_CANCELLED' })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', outcome: 'cancelled',
+    })
+
+    const ownerAbort = new AbortController()
+    const aborted = ctx.userInteraction.ask({ questions, agent, signal: ownerAbort.signal })
+      .catch((error: unknown) => error)
+    const abortRequest = (await stream.next()).value as RpcRequest<MuxFrame>
+    ownerAbort.abort()
+    await expect(aborted).resolves.toMatchObject({ code: 'ASK_ABORTED' })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: abortRequest.rpcId, outcome: 'cancelled',
+    })
+    expect(await api.respond({
+      type: 'client-response', rpcId: abortRequest.rpcId,
+      result: { ok: false, error: { code: 'cancelled', message: 'late', details: {} } },
+    })).toEqual({ accepted: false, reason: 'not-pending' })
+    streamAbort.abort()
+  })
+
+  it('rejects missing routing and pre-abort, then aborts outstanding waits on disposal', async () => {
+    const running = await boot()
+    const { ctx } = running
+    await expect(ctx.userInteraction.ask({ questions })).rejects.toMatchObject({ code: 'ASK_MISSING_AGENT' })
+    const { sessionId } = expectOk(await running.api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const alreadyAborted = new AbortController()
+    alreadyAborted.abort()
+    await expect(ctx.userInteraction.ask({ questions, agent, signal: alreadyAborted.signal }))
+      .rejects.toMatchObject({ code: 'ASK_ABORTED' })
+
+    const outstanding = ctx.userInteraction.ask({ questions, agent })
+    const disposed = running.dispose()
+    host = undefined
+    await expect(outstanding).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await disposed
   })
 })

packages/host/runtime/tests/web-plugins.e2e.ts

@@ -1,5 +1,5 @@
 /**
- * Web UI plugin assembly: the in-memory Loader tree mounts all eight UI
+ * Web UI plugin assembly: the in-memory Loader tree mounts all nine UI
  * packages (node halves), and the webserver registry built over it yields the
  * full __DSH_BOOT__ manifest — the P-I config-source bar end to end.
  *
@@ -10,6 +10,9 @@
 import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { Context } from 'cordis'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import { afterEach, describe, expect, it } from 'vitest'
 import { createHostWebPluginRegistry } from '@deepseek-ai/dsh-host-webserver'
 import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
@@ -31,8 +34,16 @@ afterEach(async () => {
 })
 
 describe.skipIf(!built)('mountWebPlugins + registry', () => {
-  it('mounts the eight-package in-memory Loader tree and projects the boot manifest', async () => {
+  async function rootWithHostServices(): Promise<Context> {
     root = new Context()
+    await root.plugin(SystemPrompt)
+    await root.plugin(ToolRegistry)
+    await root.plugin(UserInteractionService)
+    return root
+  }
+
+  it('mounts the nine-package in-memory Loader tree and projects the boot manifest', async () => {
+    root = await rootWithHostServices()
     const mounted = await mountWebPlugins(root)
     const registry = createHostWebPluginRegistry({
       ctx: root,
@@ -59,7 +70,7 @@ describe.skipIf(!built)('mountWebPlugins + registry', () => {
   })
 
   it('is idempotent: a second mount reuses the loader and creates no duplicate entries', async () => {
-    root = new Context()
+    root = await rootWithHostServices()
     await mountWebPlugins(root)
     const second = await mountWebPlugins(root)
     // ctx.loader hands out a fresh traced proxy per access, so loader identity

packages/host/runtime/tests/web-plugins.spec.ts

@@ -1,5 +1,5 @@
 /**
- * mountWebPlugins unit coverage (keyless; the real eight-package walk is the
+ * mountWebPlugins unit coverage (keyless; the real nine-package walk is the
  * built-artifact e2e). The Loader-facing behavior — baseUrl anchoring, entry
  * creation with idempotent reuse, the fiber-less fail-loud sweep, and the
  * resolver seam — is exercised against a stubbed loader service so it runs
@@ -85,7 +85,7 @@ describe('mountWebPlugins (stubbed loader)', () => {
 
   it('mounts the real Loader when none is present (the ctx.plugin(Loader) branch)', async () => {
     root = new Context()
-    // Environment-dependent outcome: with built lib/ the eight imports load
+    // Environment-dependent outcome: with built lib/ the nine imports load
     // and the mount resolves; without them every entry stays fiber-less and
     // the sweep throws its loud list. Either way the branch under test is the
     // Loader auto-mount. Manual try/catch keeps cordis-traced proxies out of
@@ -100,7 +100,7 @@ describe('mountWebPlugins (stubbed loader)', () => {
     }
     expect(outcome === 'resolved' || /UI plugin\(s\) failed to load/.test(outcome)).toBe(true)
     expect(root.get('loader') !== undefined).toBe(true)
-  }, 30_000) // built-env run imports eight real plugin packages through the Loader
+  }, 30_000) // built-env run imports nine real plugin packages through the Loader
 
   it('keeps a caller-set baseUrl (anchors only when absent)', async () => {
     const entriesList: FakeEntry[] = []

packages/host/runtime/tsconfig.json

@@ -140,6 +140,9 @@
     {
       "path": "../../client/ui-conversation"
     },
+    {
+      "path": "../../client/ui-question"
+    },
     {
       "path": "../../client/ui-trajectory"
     }

packages/plan/README.md

@@ -4,6 +4,6 @@ Plan mode is one logged, per-agent collaboration state. It is a single **product
 
 | Package | Role | ctx key |
 |---|---|---|
-| `plan-mode/` | `plan/mode` vocabulary + fold, boundary-applied state, the `plan:policy` guidance section, `/plan [message]`, and the model-facing `exit_plan_mode` review tool | `ctx.planMode` |
+| `plan-mode/` | `plan/mode` vocabulary + fold, boundary-applied state, the `plan:policy` guidance section, `/plan [message]` entry and `/plan off` exit, and the model-facing `exit_plan_mode` review tool | `ctx.planMode` |
 
 The active state is a pure function of the session log, so resume and fork restore it without extra machinery. The deployment supplies plan instructions through Cordis config, while `exit_plan_mode` stays registered when planning is inactive to keep the request tool catalog stable. ACP maps this capability onto its generic `default` / `plan` picker; sandbox mode and approval policy remain independent enforcement settings. Design: [plan-mode Agent Note](../../.agents/notes/implemented/feature/2026-07-07-plan-mode.md) and [plan-specific state simplification](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).

packages/plan/plan-mode/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-plan-mode
 
-Logged, per-agent plan collaboration state with deployment-owned guidance, a direct `/plan [message]` entry command, and the reviewed `exit_plan_mode` exit. Plan mode is soft guidance; sandbox mode and approval policy remain independent enforcement axes.
+Logged, per-agent plan collaboration state with deployment-owned guidance, direct `/plan [message]` entry and `/plan off` exit commands, and the reviewed `exit_plan_mode` exit. Plan mode is soft guidance; sandbox mode and approval policy remain independent enforcement axes.
 
 ## Durable state
 
@@ -12,7 +12,7 @@ Logged, per-agent plan collaboration state with deployment-owned guidance, a dir
 
 While active, `plan:policy` renders the configured `section`. The plugin always registers `exit_plan_mode`, keeping tool schemas stable across the transition; its execute path accepts only active plan mode and leaves it only after an exact user approval through `ctx.userInteraction`.
 
-When `ctx.commands` is composed, the package registers `/plan [message]`. The command selects plan mode first. A non-empty argument is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance; bare `/plan` only changes state.
+When `ctx.commands` is composed, the package registers `/plan [message]` and reserves the exact argument `off` for direct exit. Bare `/plan` selects plan mode; any other non-empty argument selects it first and is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance. `/plan off` selects inactive without sending model input; it also cancels a pending entry before plan mode reaches a request.
 
 ACP is an adapter, not the owner of this vocabulary: it advertises the fixed wire ids `default` and `plan`, maps `session/set_mode` to the boolean service, and translates committed `plan/mode` events back to `current_mode_update`.
 
@@ -53,19 +53,19 @@ Inactive mode adds no tokens; active mode adds the configured section to every r
 
 The section is stable within plan mode, but entering or leaving changes the system prompt from order 50 onward.
 
-### Optional command message
+### Human command
 
 #### What the model sees
 
-`/plan` and its terminal result stay outside model history; a non-empty suffix becomes one trimmed user text block through `agent.steer()` after plan mode is selected.
+`/plan`, `/plan off`, and their terminal results stay outside model history. A non-empty suffix other than the exact `off` argument becomes one trimmed user text block through `agent.steer()` after plan mode is selected. An active `/plan off` selection contributes the standard logged user-switch notice only when the last request header described plan mode; cancelling a pending entry contributes none because no request observed it.
 
 #### Token effect
 
-The suffix costs the same history tokens as submitting that text separately; a bare command adds none.
+The optional message costs the same history tokens as submitting that text separately; bare `/plan` and `/plan off` add none. A narrated active exit adds the small retained switch notice.
 
 #### KV Cache effect
 
-The user block is append-only conversation growth, while entering plan mode also changes the earlier policy section.
+The user block is append-only conversation growth. Entering or leaving plan mode changes the earlier policy section; a narrated exit notice is appended after the reusable request prefix.
 
 ### Exit tool schema and review exchange
 

packages/plan/plan-mode/src/index.ts

@@ -1,9 +1,10 @@
 /**
  * Plan mode is logged per-agent collaboration state: while active, a
  * deployment-owned guidance section shapes each model request, and
- * `exit_plan_mode` presents the completed plan for user review. It is
- * independent of sandbox mode and approval policy; those enforcement axes do
- * not read or write plan state.
+ * `exit_plan_mode` presents the completed plan for user review, while the
+ * `/plan off` command lets a user leave directly. Plan mode is independent of
+ * sandbox mode and approval policy; those enforcement axes do not read or
+ * write plan state.
  *
  * The state in force is folded from the session log (`plan/mode`, last one
  * wins), so resume and fork restore it without a live mirror. User selections
@@ -210,13 +211,27 @@ export class PlanModeService extends Service {
     ctx.inject(['commands'], (commandCtx) => {
       commandCtx.commands.register({
         name: 'plan',
-        description: 'Enter plan mode',
-        input: { hint: '[message]' },
+        description: 'Enter or leave plan mode',
+        input: { hint: '[off|message]' },
         handler: ({ agent, rawInput }) => {
           const message = rawInput.trim()
+          if (message === 'off') {
+            const state = this.get(agent)
+            this.set(agent, false)
+            if (state.active) {
+              return { kind: 'success', text: 'Leaving plan mode (applies from the next step).' }
+            }
+            if (state.pending === true) {
+              return { kind: 'success', text: 'Plan mode entry cancelled.' }
+            }
+            return { kind: 'success', text: 'Plan mode is already inactive.' }
+          }
           this.set(agent, true)
           if (message !== '') agent.steer([{ type: 'text', text: message }])
-          return { kind: 'success', text: 'Entering plan mode (applies from the next step).' }
+          return {
+            kind: 'success',
+            text: 'Entering plan mode (applies from the next step). Use /plan off to leave.',
+          }
         },
       })
     })

packages/plan/plan-mode/tests/plan-mode.spec.ts

@@ -546,14 +546,17 @@ describe('/plan', () => {
     const plainSteer = vi.fn()
     ;(plainAgent as unknown as { steer: typeof plainSteer }).steer = plainSteer
     expect(ctx.commands.list(plainAgent)).toEqual([
-      { name: 'plan', description: 'Enter plan mode', input: { hint: '[message]' } },
+      { name: 'plan', description: 'Enter or leave plan mode', input: { hint: '[off|message]' } },
     ])
 
     const signal = new AbortController().signal
     expect(await ctx.commands.execute(plainAgent, '/mode', signal)).toBeUndefined()
     expect(await ctx.commands.execute(plainAgent, '/review', signal)).toBeUndefined()
     const plain = await ctx.commands.execute(plainAgent, '/plan', signal)
-    expect(plain).toEqual({ kind: 'success', text: 'Entering plan mode (applies from the next step).' })
+    expect(plain).toEqual({
+      kind: 'success',
+      text: 'Entering plan mode (applies from the next step). Use /plan off to leave.',
+    })
     expect(ctx.planMode.get(plainAgent)).toEqual({ active: false, pending: true })
     expect(plainSteer).not.toHaveBeenCalled()
 
@@ -561,11 +564,50 @@ describe('/plan', () => {
     const messageSteer = vi.fn()
     ;(messageAgent as unknown as { steer: typeof messageSteer }).steer = messageSteer
     const plan = await ctx.commands.execute(messageAgent, '/plan   draft the migration  ', signal)
-    expect(plan).toEqual({ kind: 'success', text: 'Entering plan mode (applies from the next step).' })
+    expect(plan).toEqual({
+      kind: 'success',
+      text: 'Entering plan mode (applies from the next step). Use /plan off to leave.',
+    })
     expect(ctx.planMode.get(messageAgent)).toEqual({ active: false, pending: true })
     expect(messageSteer).toHaveBeenCalledExactlyOnceWith([{ type: 'text', text: 'draft the migration' }])
   })
 
+  it('leaves active plan mode, cancels a pending entry, and treats inactive exit as idempotent', async () => {
+    const ctx = await setup()
+    await ctx.plugin(CommandService)
+    await new Promise(resolve => setImmediate(resolve))
+    const signal = new AbortController().signal
+
+    const inactive = await agentWithSession(ctx, 'inactive-plan-command')
+    expect(await ctx.commands.execute(inactive, '/plan off', signal))
+      .toEqual({ kind: 'success', text: 'Plan mode is already inactive.' })
+    expect(ctx.planMode.get(inactive)).toEqual({ active: false })
+
+    const entering = await agentWithSession(ctx, 'entering-plan-command')
+    const enteringSteer = vi.fn()
+    ;(entering as unknown as { steer: typeof enteringSteer }).steer = enteringSteer
+    await ctx.commands.execute(entering, '/plan', signal)
+    expect(await ctx.commands.execute(entering, '/plan off', signal))
+      .toEqual({ kind: 'success', text: 'Plan mode entry cancelled.' })
+    expect(ctx.planMode.get(entering)).toEqual({ active: false, pending: false })
+    expect(enteringSteer).not.toHaveBeenCalled()
+    await boundary(ctx, entering, 'turn/start')
+    expect(ctx.planMode.get(entering)).toEqual({ active: false })
+    expect(entering.session.events.some(event => event.type === 'plan/mode')).toBe(false)
+
+    const active = await agentWithSession(ctx, 'active-plan-command', { active: true })
+    const activeSteer = vi.fn()
+    ;(active as unknown as { steer: typeof activeSteer }).steer = activeSteer
+    expect(await ctx.commands.execute(active, '/plan off', signal))
+      .toEqual({ kind: 'success', text: 'Leaving plan mode (applies from the next step).' })
+    expect(ctx.planMode.get(active)).toEqual({ active: true, pending: false })
+    expect(await ctx.commands.execute(active, '/plan off', signal))
+      .toEqual({ kind: 'success', text: 'Leaving plan mode (applies from the next step).' })
+    expect(activeSteer).not.toHaveBeenCalled()
+    await boundary(ctx, active, 'turn/start')
+    expect(ctx.planMode.get(active)).toEqual({ active: false })
+  })
+
   it('removes the contributed command when the plan-mode plugin is disposed', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)

packages/pty/pty-local/README.md

@@ -4,9 +4,11 @@ Local `node-pty` backend for `ctx.pty`. It starts an interactive shell under the
 
 ## Plugin (`pty-local`)
 
-The plugin injects `pty`, `sandbox`, and `sandboxPolicy`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The current session-level sandbox override is resolved at spawn and remains fixed for the PTY lifetime.
+The plugin injects `pty`, `sandbox`, and `sandboxPolicy`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a local-provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Linux readiness combines a foreground-verified private bash prompt marker, foreground-process-group syscall inspection, silence fallback, and absolute timeout. macOS uses the verified prompt marker plus silence/timeout because it has no `/proc` syscall surface. Unrecognized or unreadable process state is never a positive exact-idle signal. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit.
+Linux readiness combines a foreground-verified private bash prompt marker, foreground-process-group syscall inspection, silence fallback, and absolute timeout. macOS uses the verified prompt marker plus silence/timeout because it has no `/proc` syscall surface. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks. Unrecognized or unreadable process state is never a positive exact-idle signal. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason even when its foreground process group is not observable yet; if that close fails, `PtyBackendCleanupError` separately preserves the cleanup failure for registry disposal. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+
+Send cancellation resolves the current foreground process group and delivers a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close sends `SIGTERM` to descendants, waits, then sends `SIGKILL` to the union of captured survivors and newly scanned descendants so reparenting cannot hide a process from teardown. It verifies that every retained identity is gone or, on Linux, a non-executing zombie before stopping the shell; zombie entries are quiescent and are reaped as the shell exits. A survivor failure does not cache a permanently rejected close; a later close retries the teardown.
 
 ## Model Experience
 

packages/pty/pty-local/package.json

@@ -30,10 +30,12 @@
   },
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-pty": "^0.0.1",
     "@deepseek-ai/dsh-sandbox": "^0.0.1",
     "@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {

packages/pty/pty-local/src/index.ts

@@ -7,6 +7,9 @@
 import { Context } from 'cordis'
 import * as nodePty from 'node-pty'
 import type { IPtyForkOptions } from 'node-pty'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
 import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
@@ -20,10 +23,37 @@ export type { Config as PtyLocalConfig } from './config.ts'
 
 /** Cordis plugin name. */
 export const name = 'pty-local'
-/** Required services: registry plus the one shared confinement policy. */
+/** Required services: PTY registry plus the one shared confinement policy. */
 export const inject = ['pty', 'sandbox', 'sandboxPolicy']
 
 const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
+interface SandboxModeFenceState {
+  pty: Context['pty']
+  sandboxPolicy: Context['sandboxPolicy']
+}
+
+const sandboxModeFences = new WeakMap<Agent, SandboxModeFenceState>()
+
+function ensureSandboxModeFence(ctx: Context, owner: Agent): void {
+  const existing = sandboxModeFences.get(owner)
+  if (existing !== undefined) {
+    existing.pty = ctx.pty
+    existing.sandboxPolicy = ctx.sandboxPolicy
+    return
+  }
+  const state: SandboxModeFenceState = { pty: ctx.pty, sandboxPolicy: ctx.sandboxPolicy }
+  sandboxModeFences.set(owner, state)
+  owner.ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'session/event') return
+    const [session, event] = args as [Session, SessionEvent]
+    if (session !== owner.session || event.type !== 'sandbox/mode') return
+    const currentMode = effectiveSandboxMode(session.events) ?? state.sandboxPolicy.defaultMode
+    if (event.data.mode === currentMode || !state.pty.hasOwnerActivity(owner)) return
+    throw new Error(
+      `cannot change sandbox mode from "${currentMode}" to "${event.data.mode}" while persistent terminal sessions are open or being created; wait for creation to settle and close them first`,
+    )
+  }, { global: true })
+}
 
 function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {}
@@ -73,7 +103,8 @@ export class LocalPtyBackend implements PtyBackend {
   }
 
   async spawn(spec: PtyBackendSpawnSpec): Promise<LocalPtySession> {
-    if (spec.signal?.aborted === true) throw new Error('PTY spawn aborted')
+    spec.signal?.throwIfAborted()
+    ensureSandboxModeFence(this.ctx, spec.owner)
     const argv = spawnArgv(this.ctx, this.config, spec)
     const file = argv[0]
     if (file === undefined) throw new Error('pty-local: sandbox returned empty argv')
@@ -93,7 +124,7 @@ export class LocalPtyBackend implements PtyBackend {
       try {
         await session.close('PTY startup failed')
       } catch (closeError: unknown) {
-        throw new AggregateError([error, closeError], 'PTY startup and cleanup both failed')
+        throw new PtyBackendCleanupError(error, closeError)
       }
       throw error
     }

packages/pty/pty-local/src/process-inspector.ts

@@ -16,6 +16,7 @@ export interface ProcessInspector {
   isStdinWaiting(pgid: number): boolean
   /** Return the root and its current transitive descendants, children first. */
   processTree(rootPid: number): ProcessIdentity[]
+  /** Return whether the exact identity remains a non-quiescent process. */
   isAlive(identity: ProcessIdentity): boolean
   signalGroup(pgid: number, signal: PtySignal): void
   signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void
@@ -49,6 +50,7 @@ interface ProcStat {
   parentPid: number
   pgrp: number
   session: number
+  state: string
   tpgid: number
   started: string
 }
@@ -64,13 +66,15 @@ export function parseProcStat(text: string): ProcStat | undefined {
   if (open <= 0 || close <= open) return undefined
   const pid = Number(text.slice(0, open).trim())
   const rest = text.slice(close + 2).trim().split(/\s+/)
+  const state = rest[0] || ''
   const parentPid = Number(rest[1])
   const pgrp = Number(rest[2])
   const session = Number(rest[3])
   const tpgid = Number(rest[5])
   const started = rest[19]
-  if (![pid, parentPid, pgrp, session, tpgid].every(Number.isSafeInteger) || started === undefined) return undefined
-  return { pid, parentPid, pgrp, session, tpgid, started }
+  if (![pid, parentPid, pgrp, session, tpgid].every(Number.isSafeInteger)
+    || state.length !== 1 || started === undefined) return undefined
+  return { pid, parentPid, pgrp, session, state, tpgid, started }
 }
 
 function readLinuxStat(internals: ProcessInspectorInternals, pid: number): ProcStat | undefined {
@@ -269,7 +273,8 @@ class LinuxProcessInspector extends PosixProcessInspector {
   }
 
   isAlive(identity: ProcessIdentity): boolean {
-    return readLinuxStat(this.internals, identity.pid)?.started === identity.started
+    const stat = readLinuxStat(this.internals, identity.pid)
+    return stat?.started === identity.started && !/^[ZXx]$/.test(stat.state)
   }
 
 }

packages/pty/pty-local/src/sanitize.ts

@@ -9,6 +9,8 @@ export const PROMPT_MARKER_PREFIX = '133;D;'
 export interface SanitizedChunk {
   text: string
   prompt: boolean
+  /** Present when printable text followed the latest owned prompt marker. */
+  promptText?: true
 }
 
 /**
@@ -20,6 +22,8 @@ export class TerminalSanitizer {
   private pending = ''
   private discardMode: 'osc' | 'csi' | undefined
   private discardOscEscape = false
+  private trailingCarriageReturn = false
+  private awaitingPromptText = false
 
   constructor(private readonly maxPendingBytes: number) {}
 
@@ -32,15 +36,24 @@ export class TerminalSanitizer {
     this.pending += this.discardPrefix(chunk)
     let text = ''
     let prompt = false
+    let promptText = false
     let index = 0
+    const appendText = (value: string): boolean => {
+      text += value
+      if (this.awaitingPromptText && value.replace(/[\r\n\x07]/g, '').length > 0) {
+        this.awaitingPromptText = false
+        return true
+      }
+      return false
+    }
     while (index < this.pending.length) {
       const escape = this.pending.indexOf('\x1b', index)
       if (escape < 0) {
-        text += this.pending.slice(index)
+        promptText = appendText(this.pending.slice(index)) || promptText
         index = this.pending.length
         break
       }
-      text += this.pending.slice(index, escape)
+      promptText = appendText(this.pending.slice(index, escape)) || promptText
       if (escape + 1 >= this.pending.length) {
         index = escape
         break
@@ -59,7 +72,11 @@ export class TerminalSanitizer {
         }
         const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
         const content = this.pending.slice(escape + 2, end - terminatorBytes)
-        if (content.startsWith(PROMPT_MARKER_PREFIX)) prompt = true
+        if (content.startsWith(PROMPT_MARKER_PREFIX)) {
+          prompt = true
+          promptText = false
+          this.awaitingPromptText = true
+        }
         index = end
         continue
       }
@@ -82,7 +99,7 @@ export class TerminalSanitizer {
     }
     this.pending = this.pending.slice(index)
     this.enforcePendingBound()
-    return { text: normalizeTerminalText(text), prompt }
+    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
   }
 
   /**
@@ -94,7 +111,21 @@ export class TerminalSanitizer {
     this.pending = ''
     this.discardMode = undefined
     this.discardOscEscape = false
-    return normalizeTerminalText(text)
+    this.awaitingPromptText = false
+    const normalized = this.normalizeText(text)
+    if (!this.trailingCarriageReturn) return normalized
+    this.trailingCarriageReturn = false
+    return `${normalized}\n`
+  }
+
+  private normalizeText(text: string): string {
+    let complete = this.trailingCarriageReturn ? `\r${text}` : text
+    this.trailingCarriageReturn = false
+    if (complete.endsWith('\r')) {
+      complete = complete.slice(0, -1)
+      this.trailingCarriageReturn = true
+    }
+    return normalizeTerminalText(complete)
   }
 
   private enforcePendingBound(): void {

packages/pty/pty-local/src/session.ts

@@ -17,7 +17,7 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import type { ProcessInspector } from './process-inspector.ts'
+import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
 import { TerminalSanitizer } from './sanitize.ts'
 
 function delay(ms: number): Promise<void> {
@@ -148,9 +148,11 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private promptSeen = false
+  private promptTextSeen = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
+  private closing = false
   private closePromise: Promise<void> | undefined
 
   constructor(
@@ -184,27 +186,29 @@ export class LocalPtySession implements PtyBackendSession {
       if (result.waitReason === 'session_exit') throw new Error('PTY shell exited during startup')
       if (result.waitReason === 'timeout') throw new Error('PTY shell did not reach readiness before startup timeout')
       this.motd = result.viewport
+    } catch (error: unknown) {
+      signal?.throwIfAborted()
+      throw error
     } finally {
       this.initializing = false
     }
   }
 
   startSend(request: PtySendRequest): PtySendOperation {
-    if (this.closePromise !== undefined) throw new Error('PTY session is closing')
+    if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
     if (this.active !== undefined) throw new Error('PTY session already has an active send')
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
-    const operation = new LocalSendOperation(this.config.maxReadBytes, Date.now(), () => {
-      try {
-        this.terminal.write('\x03')
-      } catch (error: unknown) {
-        operation.fail(error)
-      }
-    })
+    const operation = new LocalSendOperation(
+      this.config.maxReadBytes,
+      Date.now(),
+      () => { this.interrupt(operation) },
+    )
     this.active = operation
     this.lastOutputAt = Date.now()
     this.promptSeen = false
+    this.promptTextSeen = false
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
@@ -267,8 +271,15 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   close(reason: string): Promise<void> {
-    this.closePromise ??= this.closeOnce(reason)
-    return this.closePromise
+    this.closing = true
+    if (this.closePromise !== undefined) return this.closePromise
+    const closing = this.closeOnce(reason).catch((error: unknown) => {
+      this.closePromise = undefined
+      this.failActive(error)
+      throw error
+    })
+    this.closePromise = closing
+    return closing
   }
 
   private onData(data: string): void {
@@ -279,8 +290,11 @@ export class LocalPtySession implements PtyBackendSession {
       if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
       if (foregroundPgid !== undefined && foregroundPgid === this.shellPgid) {
         this.promptSeen = true
+        this.promptTextSeen = sanitized.promptText === true
         this.lastOutputAt = Date.now()
       }
+    } else if (this.promptSeen && sanitized.promptText === true) {
+      this.promptTextSeen = true
     }
   }
 
@@ -297,7 +311,7 @@ export class LocalPtySession implements PtyBackendSession {
       this.settleActive('session_exit')
       return
     }
-    if (this.promptSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
+    if (this.promptSeen && this.promptTextSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
       this.settleActive('stdin_read')
       return
     }
@@ -337,58 +351,113 @@ export class LocalPtySession implements PtyBackendSession {
     this.active = undefined
   }
 
+  private failActive(error: unknown): void {
+    const operation = this.active
+    if (operation === undefined) return
+    this.clearActive()
+    operation.fail(error)
+  }
+
+  private interrupt(operation: LocalSendOperation): void {
+    if (this.active !== operation) return
+    try {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
+      this.inspector.signalGroup(pgid, 'SIGINT')
+    } catch (error: unknown) {
+      this.failActive(error)
+    }
+  }
+
+  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
+    return members.filter(member => this.inspector.isAlive(member))
+  }
+
+  private descendants(): ProcessIdentity[] {
+    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
+  }
+
+  private async waitForExit(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
+    const deadline = Date.now() + this.config.disposeGraceMs
+    let survivors = this.survivors(members)
+    while (survivors.length > 0 && Date.now() < deadline) {
+      await delay(Math.min(25, Math.max(1, deadline - Date.now())))
+      survivors = this.survivors(members)
+    }
+    return survivors
+  }
+
+  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
+    for (const member of members) {
+      try {
+        this.inspector.signalProcess(member, signal)
+      } catch (_alreadyExitedDuringSignal) {
+        // Identity is rechecked by the inspector; a same-tick exit is success.
+      }
+    }
+  }
+
+  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
+    const members: ProcessIdentity[] = []
+    const seen = new Set<string>()
+    for (const group of groups) {
+      for (const member of group) {
+        const key = JSON.stringify([member.pid, member.started])
+        if (seen.has(key)) continue
+        seen.add(key)
+        members.push(member)
+      }
+    }
+    return members
+  }
+
+  private async stopDescendants(): Promise<ProcessIdentity[]> {
+    const captured = this.descendants()
+    this.signalMembers(captured, 'SIGTERM')
+    const capturedSurvivors = await this.waitForExit(captured)
+    // A TERM-handling descendant may have forked while winding down. Rescan
+    // while the shell can still reap every member, then kill both the fresh
+    // tree and captured survivors that were reparented out of that tree.
+    const members = this.unionMembers(capturedSurvivors, this.descendants())
+    this.signalMembers(members, 'SIGKILL')
+    const survivors = await this.waitForExit(members)
+    return this.survivors(this.unionMembers(survivors, this.descendants()))
+  }
+
+  private async stopShell(): Promise<void> {
+    try {
+      this.terminal.kill('SIGTERM')
+    } catch (_topLevelAlreadyExitedDuringTerm) {
+      // The exit notification remains authoritative.
+    }
+    if (this.statusValue.kind === 'running') {
+      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (this.statusValue.kind === 'running') {
+      try {
+        this.terminal.kill('SIGKILL')
+      } catch (_topLevelAlreadyExitedDuringKill) {
+        // The exit notification remains authoritative.
+      }
+      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (this.statusValue.kind === 'running') {
+      throw new Error(`PTY cleanup failed; surviving pids: ${this.pid}`)
+    }
+  }
+
   private async closeOnce(reason: string): Promise<void> {
     this.dataDisposable.dispose()
     // Stop readiness polling but retain the active operation: teardown settles
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    const members = this.inspector.processTree(this.pid)
-    for (const member of members) {
-      try {
-        this.inspector.signalProcess(member, 'SIGTERM')
-      } catch (_alreadyExitedDuringTerm) {
-        // Identity is rechecked by the inspector; a same-tick exit is success.
-      }
-    }
-    try {
-      this.terminal.kill('SIGTERM')
-    } catch (_topLevelAlreadyExited) {
-      // onExit or identity checks below remain authoritative.
-    }
-
-    const deadline = Date.now() + this.config.disposeGraceMs
-    let survivors = members.filter(member => this.inspector.isAlive(member))
-    while (survivors.length > 0 && Date.now() < deadline) {
-      await delay(Math.min(25, this.config.disposeGraceMs))
-      survivors = members.filter(member => this.inspector.isAlive(member))
-    }
-    for (const survivor of survivors) {
-      try {
-        this.inspector.signalProcess(survivor, 'SIGKILL')
-      } catch (_alreadyExitedDuringKill) {
-        // Final identity check below decides success.
-      }
-    }
-    try {
-      this.terminal.kill('SIGKILL')
-    } catch (_topLevelAlreadyKilled) {
-      // The root may already have delivered onExit.
-    }
-
-    const killDeadline = Date.now() + this.config.disposeGraceMs
-    survivors = members.filter(member => this.inspector.isAlive(member))
-    while (survivors.length > 0 && Date.now() < killDeadline) {
-      await delay(Math.min(25, this.config.disposeGraceMs))
-      survivors = members.filter(member => this.inspector.isAlive(member))
-    }
-    const exitWaitMs = Math.max(0, killDeadline - Date.now())
-    await Promise.race([this.exitPromise.promise, delay(exitWaitMs)])
-    survivors = members.filter(member => this.inspector.isAlive(member))
-    this.settleActive('session_exit')
-    this.exitDisposable.dispose()
+    const survivors = await this.stopDescendants()
     if (survivors.length > 0) {
       throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
     }
+    await this.stopShell()
+    this.settleActive('session_exit')
+    this.exitDisposable.dispose()
   }
 }

packages/pty/pty-local/tests/index.spec.ts

@@ -2,12 +2,13 @@ import { describe, expect, it, vi } from 'vitest'
 import type { IPty, IPtyForkOptions } from 'node-pty'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
-import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
-import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
+import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/dsh-pty'
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import * as ptyLocal from '@deepseek-ai/dsh-pty-local'
 import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
@@ -62,6 +63,30 @@ function spec(owner: Agent, signal?: AbortSignal) {
   }
 }
 
+function stubLocalSession(initialize: () => Promise<void> = () => Promise.resolve()): LocalPtySession {
+  return {
+    motd: '',
+    initialize,
+    startSend: () => { throw new Error('unused') },
+    read: () => { throw new Error('unused') },
+    signal: () => Promise.resolve({ delivered: true, targetPgid: 1 }),
+    status: () => ({ kind: 'running' as const }),
+    close: () => Promise.resolve(),
+  } as unknown as LocalPtySession
+}
+
+function registerStubLocalBackend(ctx: Context, createSession: () => LocalPtySession) {
+  return ctx.inject(['pty', 'sandbox', 'sandboxPolicy'], (providerCtx) => {
+    providerCtx.pty.registerBackend(new LocalPtyBackend(
+      providerCtx,
+      { ...config(), backendType: 'stub' },
+      inspector,
+      (() => ({})) as never,
+      createSession,
+    ))
+  })
+}
+
 describe('LocalPtyBackend startup rollback', () => {
   it('rejects pre-aborted setup and empty sandbox argv', async () => {
     const ctx = new Context()
@@ -69,8 +94,9 @@ describe('LocalPtyBackend startup rollback', () => {
     await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/tmp' })
     const backend = new LocalPtyBackend(ctx, config(), inspector)
     const controller = new AbortController()
-    controller.abort()
-    await expect(backend.spawn(spec(agent(ctx), controller.signal))).rejects.toThrow('spawn aborted')
+    const abortReason = new Error('spawn aborted')
+    controller.abort(abortReason)
+    await expect(backend.spawn(spec(agent(ctx), controller.signal))).rejects.toBe(abortReason)
     await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('empty argv')
   })
 
@@ -86,12 +112,18 @@ describe('LocalPtyBackend startup rollback', () => {
     await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('startup failed')
     expect(closed).toHaveBeenCalledWith('PTY startup failed')
 
+    const startupFailure = new Error('startup failed')
+    const cleanupFailure = new Error('cleanup failed')
     const doublyFailed = {
-      initialize: () => Promise.reject(new Error('startup failed')),
-      close: () => Promise.reject(new Error('cleanup failed')),
+      initialize: () => Promise.reject(startupFailure),
+      close: () => Promise.reject(cleanupFailure),
     } as unknown as LocalPtySession
     const aggregate = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => doublyFailed)
-    await expect(aggregate.spawn(spec(agent(ctx)))).rejects.toThrow('startup and cleanup both failed')
+    await expect(aggregate.spawn(spec(agent(ctx)))).rejects.toEqual(expect.objectContaining({
+      name: 'PtyBackendCleanupError',
+      spawnError: startupFailure,
+      cleanupError: cleanupFailure,
+    } satisfies Partial<PtyBackendCleanupError>))
   })
 
   it('wraps confined argv, scrubs the environment, and returns initialized sessions', async () => {
@@ -175,6 +207,7 @@ describe('pty-local plugin shape', () => {
 
   it('validates config and registers the configured backend', async () => {
     const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(PtyService)
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
@@ -183,4 +216,90 @@ describe('pty-local plugin shape', () => {
     await fiber.dispose()
     expect(ctx.pty.listBackends()).toEqual([])
   })
+
+  it('ignores unrelated session events and mode changes without a live owner', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(PtyService)
+    await ctx.plugin(EmptySandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(ptyLocal, config())
+
+    const session = ctx.sessions.create(SessionId('unowned-mode'))
+    expect(() => {
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    }).not.toThrow()
+    expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
+  })
+
+  it('keeps the owner-lifetime sandbox fence after the local provider unloads', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(PtyService)
+    await ctx.plugin(RecordingSandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+
+    const session = ctx.sessions.create(SessionId('mode-owner'))
+    const ownerFiber = await ctx.plugin(() => {})
+    const owner: Agent = {
+      id: session.id, options: {}, session, status: 'idle', ctx: ownerFiber.ctx,
+      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    }
+    ctx.agents.register(owner)
+    const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
+    const created = await ctx.pty.spawn(owner, { type: 'stub' })
+
+    const unrelated = ctx.sessions.create(SessionId('unrelated-mode'))
+    expect(() => { setSandboxMode(unrelated, 'read-only') }).not.toThrow()
+    expect(() => {
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    }).not.toThrow()
+
+    expect(() => { setSandboxMode(session, 'danger-full-access') }).not.toThrow()
+    await providerFiber.dispose()
+    expect(ctx.pty.listBackends()).toEqual([])
+    expect(() => { setSandboxMode(session, 'read-only') }).toThrow(
+      'cannot change sandbox mode from "danger-full-access" to "read-only" while persistent terminal sessions are open or being created; wait for creation to settle and close them first',
+    )
+    expect(session.events.filter(event => event.type === 'sandbox/mode')).toHaveLength(1)
+
+    const replacementFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
+    const second = await ctx.pty.spawn(owner, { type: 'stub' })
+    await replacementFiber.dispose()
+    expect(() => { setSandboxMode(session, 'read-only') }).toThrow('open or being created')
+
+    await ctx.pty.kill(owner, created.sessionId)
+    await ctx.pty.kill(owner, second.sessionId)
+    expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
+    expect(session.events.filter(event => event.type === 'sandbox/mode')).toHaveLength(2)
+  })
+
+  it('also fences sandbox-mode changes across unpublished PTY creation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(PtyService)
+    await ctx.plugin(RecordingSandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+
+    const session = ctx.sessions.create(SessionId('pending-mode-owner'))
+    const ownerFiber = await ctx.plugin(() => {})
+    const owner: Agent = {
+      id: session.id, options: {}, session, status: 'idle', ctx: ownerFiber.ctx,
+      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    }
+    ctx.agents.register(owner)
+    const gate = Promise.withResolvers<undefined>()
+    await registerStubLocalBackend(ctx, () => stubLocalSession(() => gate.promise))
+    const spawning = ctx.pty.spawn(owner, { type: 'stub' })
+
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(true)
+    expect(() => { setSandboxMode(session, 'read-only') }).toThrow('open or being created')
+    gate.resolve(undefined)
+    const created = await spawning
+    await ctx.pty.kill(owner, created.sessionId)
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(false)
+  })
 })

packages/pty/pty-local/tests/local.spec.ts

@@ -7,6 +7,7 @@ import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import PtyService from '@deepseek-ai/dsh-pty'
+import type { PtySendOperation } from '@deepseek-ai/dsh-pty'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
@@ -62,6 +63,16 @@ async function harness(mode: 'danger-full-access' | 'workspace-write') {
   return { ctx, root, agent, fiber, sandbox: ctx.sandbox as PassthroughSandbox }
 }
 
+async function waitForOutput(operation: PtySendOperation, expected: string): Promise<void> {
+  const deadline = Date.now() + 2_000
+  let output = ''
+  while (!output.includes(expected) && Date.now() < deadline) {
+    output += operation.readOutput().delta
+    if (!output.includes(expected)) await new Promise(resolve => setTimeout(resolve, 10))
+  }
+  expect(output).toContain(expected)
+}
+
 describe('pty-local real shell', () => {
   it('persists cwd and environment across sends, scrubs secrets, and closes', async () => {
     const previous = process.env.DSH_TEST_SECRET
@@ -119,4 +130,26 @@ describe('pty-local real shell', () => {
     await ctx.pty.kill(agent, created.sessionId)
     expect(() => process.kill(pid, 0)).toThrow()
   }, 10_000)
+
+  it('cancels a raw-mode foreground process with a real SIGINT', async () => {
+    const { ctx, agent } = await harness('danger-full-access')
+    const created = await ctx.pty.spawn(agent, { type: 'shell' })
+    const controller = new AbortController()
+    const foreground = ctx.pty.startSend(agent, created.sessionId, {
+      text: 'python3 -c \'import signal,sys,termios,time; signal.signal(signal.SIGINT, lambda *_: (print("SIGINT_SEEN", flush=True), sys.exit(0))); attrs=termios.tcgetattr(0); attrs[3] &= ~termios.ISIG; termios.tcsetattr(0, termios.TCSANOW, attrs); print("RAW_READY", flush=True); time.sleep(60)\'',
+      submit: true,
+      signal: controller.signal,
+    })
+    await waitForOutput(foreground, 'RAW_READY')
+    controller.abort()
+    const result = await foreground.done
+    expect(result.waitReason).toBe('stdin_read')
+    const after = await ctx.pty.startSend(agent, created.sessionId, {
+      text: 'echo AFTER_SIGINT',
+      submit: true,
+    }).done
+    expect(after.viewport).toContain('AFTER_SIGINT')
+    expect(after.waitReason).toBe('stdin_read')
+    await ctx.pty.kill(agent, created.sessionId)
+  }, 10_000)
 })

packages/pty/pty-local/tests/process-inspector.spec.ts

@@ -2,8 +2,8 @@ import { describe, expect, it } from 'vitest'
 import { createProcessInspector, parseProcStat } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
 import type { ProcessInspectorInternals } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
 
-function stat(pid: number, pgrp: number, session: number, tpgid: number, started: string, parentPid = 1): string {
-  const rest = ['S', String(parentPid), String(pgrp), String(session), '99', String(tpgid)]
+function stat(pid: number, pgrp: number, session: number, tpgid: number, started: string, parentPid = 1, state = 'S'): string {
+  const rest = [state, String(parentPid), String(pgrp), String(session), '99', String(tpgid)]
   while (rest.length < 19) rest.push('0')
   rest.push(started)
   return `${pid} (command with space) ${rest.join(' ')}`
@@ -65,8 +65,10 @@ function fakeInternals() {
 describe('Linux process inspector', () => {
   it('parses stat safely, captures only the rooted process tree, and signals identities', () => {
     expect(parseProcStat('bad')).toBeUndefined()
+    expect(parseProcStat('1 () ')).toBeUndefined()
     expect(parseProcStat('1 () S')).toBeUndefined()
-    expect(parseProcStat(stat(10, 20, 30, 40, '500'))).toEqual({ pid: 10, parentPid: 1, pgrp: 20, session: 30, tpgid: 40, started: '500' })
+    expect(parseProcStat(stat(10, 20, 30, 40, '500', 1, 'SS'))).toBeUndefined()
+    expect(parseProcStat(stat(10, 20, 30, 40, '500'))).toEqual({ pid: 10, parentPid: 1, pgrp: 20, session: 30, state: 'S', tpgid: 40, started: '500' })
 
     const fake = fakeInternals()
     fake.dirs.set('/proc', ['x', '10', '11', '12', '13', '14'])
@@ -90,6 +92,10 @@ describe('Linux process inspector', () => {
     inspector.signalProcess({ pid: 10, started: '500' }, 'SIGTERM')
     inspector.signalProcess({ pid: 10, started: 'old' }, 'SIGKILL')
     expect(fake.kills).toEqual([[-40, 'SIGINT'], [10, 'SIGTERM']])
+    fake.files.set('/proc/10/stat', stat(10, 20, 30, 40, '500', 1, 'Z'))
+    expect(inspector.isAlive({ pid: 10, started: '500' })).toBe(false)
+    inspector.signalProcess({ pid: 10, started: '500' }, 'SIGKILL')
+    expect(fake.kills).toEqual([[-40, 'SIGINT'], [10, 'SIGTERM']])
   })
 
   it('detects read, select, poll, and epoll waits across non-leader threads', () => {

packages/pty/pty-local/tests/sanitize.spec.ts

@@ -7,7 +7,7 @@ describe('TerminalSanitizer', () => {
     expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
     expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
     expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
-    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
@@ -25,6 +25,20 @@ describe('TerminalSanitizer', () => {
     expect(normalizeTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
   })
 
+  it('carries a trailing carriage return across data chunks and flushes standalone CR', () => {
+    const sanitizer = new TerminalSanitizer(64)
+    expect(sanitizer.push('a\r')).toEqual({ text: 'a', prompt: false })
+    expect(sanitizer.push('\nb')).toEqual({ text: '\nb', prompt: false })
+    expect(sanitizer.push('\r')).toEqual({ text: '', prompt: false })
+    expect(sanitizer.flush()).toBe('\n')
+  })
+
+  it('reports printable prompt text that follows a marker in a later chunk', () => {
+    const sanitizer = new TerminalSanitizer(64)
+    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true })
+    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptText: true })
+  })
+
   it('bounds and discards unterminated control sequences through their terminators', () => {
     const oscBel = new TerminalSanitizer(8)
     expect(oscBel.push(`\x1b]0;${'x'.repeat(16)}`)).toEqual({ text: '', prompt: false })

packages/pty/pty-local/tests/session.spec.ts

@@ -15,6 +15,7 @@ class FakeTerminal {
   kills: string[] = []
   throwWrite = false
   throwKill = false
+  autoExitOnKill = true
   private dataListeners = new Set<(data: string) => void>()
   private exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>()
 
@@ -44,7 +45,7 @@ class FakeTerminal {
   kill(signal?: string): void {
     if (this.throwKill) throw new Error('kill failed')
     this.kills.push(signal ?? 'SIGHUP')
-    this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
+    if (this.autoExitOnKill) this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
   }
 
   resize() {}
@@ -148,7 +149,7 @@ describe('LocalPtySession readiness and output', () => {
     expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
   })
 
-  it('cancels with Ctrl-C, observes AbortSignal, and contains write failures', async () => {
+  it('cancels with foreground-group SIGINT, observes AbortSignal, and contains write failures', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
@@ -159,7 +160,8 @@ describe('LocalPtySession readiness and output', () => {
     const operation = session.startSend({ text: 'sleep', submit: true, signal: controller.signal })
     expect(() => session.startSend({ text: 'again', submit: true })).toThrow('active send')
     controller.abort()
-    expect(terminal.writes.at(-1)).toBe('\x03')
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    expect(terminal.writes).not.toContain('\x03')
     terminal.emitData('\x1b]133;D;130\x07dsh> ')
     await vi.advanceTimersByTimeAsync(10)
     await operation.done
@@ -196,11 +198,13 @@ describe('LocalPtySession readiness and output', () => {
     operationInternal.append('')
     const sessionInternal = session as unknown as {
       pollReadiness(operation: PtySendOperation): void
+      interrupt(operation: PtySendOperation): void
       statusValue: PtySessionStatus
       appendOutput(text: string): void
     }
     sessionInternal.appendOutput('')
     sessionInternal.pollReadiness({} as PtySendOperation)
+    sessionInternal.interrupt({} as PtySendOperation)
     sessionInternal.statusValue = { kind: 'exited', exitCode: 2, signal: null }
     sessionInternal.pollReadiness(operation)
     await operation.done
@@ -212,12 +216,23 @@ describe('LocalPtySession readiness and output', () => {
     expect(unknown.status()).toEqual({ kind: 'exited', exitCode: 1, signal: null })
 
     const cancelTerminal = new FakeTerminal()
-    const cancel = new LocalPtySession(cancelTerminal.asPty(), new FakeInspector(), config())
+    const cancelInspector = new FakeInspector()
+    const cancel = new LocalPtySession(cancelTerminal.asPty(), cancelInspector, config())
     await initialize(cancel, cancelTerminal)
     const cancellable = cancel.startSend({ text: '', submit: false })
-    cancelTerminal.throwWrite = true
+    cancelInspector.throwGroup = true
     expect(cancellable.cancel()).toBe(true)
-    await expect(cancellable.done).rejects.toThrow('write failed')
+    await expect(cancellable.done).rejects.toThrow('group failed')
+    expect(cancellable.cancel()).toBe(false)
+
+    const missingGroupTerminal = new FakeTerminal()
+    const missingGroupInspector = new FakeInspector()
+    const missingGroup = new LocalPtySession(missingGroupTerminal.asPty(), missingGroupInspector, config())
+    await initialize(missingGroup, missingGroupTerminal)
+    missingGroupInspector.pgid = undefined
+    const unresolved = missingGroup.startSend({ text: '', submit: false })
+    expect(unresolved.cancel()).toBe(true)
+    await expect(unresolved.done).rejects.toThrow('cannot resolve foreground process group')
   })
 
   it('does not treat zero-output startup silence as readiness and fails on startup timeout', async () => {
@@ -239,6 +254,38 @@ describe('LocalPtySession readiness and output', () => {
     await timedOut
   })
 
+  it('preserves the caller abort reason when startup cannot resolve a foreground group', async () => {
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    inspector.pgid = undefined
+    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const controller = new AbortController()
+    const reason = new Error('startup cancelled')
+
+    const initializing = session.initialize(controller.signal)
+    const rejected = expect(initializing).rejects.toBe(reason)
+    controller.abort(reason)
+
+    await rejected
+  })
+
+  it('waits for printable prompt text when the startup marker is split from PS1', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config())
+    let settled = false
+    const initializing = session.initialize().then(() => { settled = true })
+
+    terminal.emitData('\x1b]133;D;0\x07')
+    await vi.advanceTimersByTimeAsync(20)
+    expect(settled).toBe(false)
+
+    terminal.emitData('dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await initializing
+    expect(session.motd).toBe('dsh> ')
+  })
+
   it('trusts prompt markers only while the startup shell owns the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -328,14 +375,15 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     // readiness poll would otherwise mis-settle this as stdin_read once close
     // begins, so teardown must stop polling before its grace period.
     terminal.emitData('\x1b]133;D;0\x07dsh> ')
-    terminal.throwKill = true
+    terminal.autoExitOnKill = false
     const closing = session.close('mid-send')
-    await vi.advanceTimersByTimeAsync(60)
+    await vi.advanceTimersByTimeAsync(20)
+    terminal.emitExit(0, 15)
     expect((await operation.done).waitReason).toBe('session_exit')
     await closing
   })
 
-  it('waits for SIGKILL recipients to leave the process table after the shell exits', async () => {
+  it('keeps the shell alive until SIGKILL recipients leave the process table', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
@@ -348,11 +396,81 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     const closing = session.close('test').then(() => { settled = true })
     await vi.advanceTimersByTimeAsync(20)
     expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
+    expect(terminal.kills).toEqual([])
     expect(settled).toBe(false)
 
     inspector.alive.delete(124)
     await vi.advanceTimersByTimeAsync(20)
     await closing
+    expect(terminal.kills).toEqual(['SIGTERM'])
     expect(settled).toBe(true)
   })
+
+  it('rescans for descendants forked during TERM before stopping the shell', async () => {
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    let reads = 0
+    inspector.processTree = () => {
+      reads += 1
+      if (reads === 1) {
+        inspector.alive.add(124)
+        return [{ pid: 124, started: 'first' }]
+      }
+      if (reads === 2) {
+        inspector.alive.add(125)
+        return [{ pid: 125, started: 'late' }]
+      }
+      return []
+    }
+    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+
+    await session.close('test')
+
+    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [125, 'SIGKILL']])
+    expect(terminal.kills).toEqual(['SIGTERM'])
+  })
+
+  it('retains captured survivors that are reparented out of the teardown rescan', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const captured = { pid: 124, started: 'captured' }
+    let reads = 0
+    inspector.alive.add(captured.pid)
+    inspector.processTree = () => reads++ === 0 ? [captured] : []
+    inspector.signalProcess = (identity, signal) => {
+      inspector.processes.push([identity.pid, signal])
+      if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)
+    }
+    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 20 }))
+
+    const closing = session.close('test')
+    await vi.advanceTimersByTimeAsync(25)
+    await closing
+
+    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [124, 'SIGKILL']])
+    expect(terminal.kills).toEqual(['SIGTERM'])
+  })
+
+  it('allows teardown to retry after a descendant-survivor failure', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.removeOnSignal = false
+    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 10 }))
+
+    const first = session.close('first')
+    const rejected = expect(first).rejects.toThrow('surviving pids: 124')
+    await vi.advanceTimersByTimeAsync(25)
+    await rejected
+    expect(terminal.kills).toEqual([])
+
+    inspector.alive.delete(124)
+    const second = session.close('retry')
+    expect(second).not.toBe(first)
+    await second
+    expect(terminal.kills).toEqual(['SIGTERM'])
+  })
 })

packages/pty/pty-local/tsconfig.json

@@ -17,6 +17,12 @@
     {
       "path": "../../../vendor/schemastery"
     },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
     {
       "path": "../pty"
     },

packages/pty/pty/README.md

@@ -4,11 +4,16 @@ Owner-scoped persistent PTY seam. `PtyService` registers as `ctx.pty`, mints opa
 
 ## Contract
 
-- Backends register one stable `type` and return an unpublished `PtyBackendSession`; failed or cancelled setup must clean partial resources.
+- Backends register one stable `type` and return an unpublished `PtyBackendSession`; failed or cancelled setup must clean partial resources, and a failed cleanup rejects with `PtyBackendCleanupError` so the registry can retain it across cancellation.
+- Spawn cancellation preserves the caller's exact abort reason. Service disposal and owner loss remain distinct machine-routable failures after backend setup.
+- Owner and service disposal abort unpublished setup through a service-owned signal and await backend settlement plus rollback before returning.
+- A rollback-close or backend-reported startup cleanup failure rejects the disposing lifecycle instead of claiming quiescence. Caller-triggered cancellation still receives its exact reason; lifecycle-triggered rollback failure also rejects the pending spawn.
+- A backend cleanup failure that follows caller cancellation remains owner activity until owner or service disposal consumes and reports it, so lifecycle policy cannot mistake failed cleanup for quiescence.
+- `hasOwnerActivity(owner)` spans unpublished setup through final close, so lifecycle policy can fence the exact owner without a publication race.
 - A successful spawn publishes one `PtySessionId`. The optional `name` is owner-local display metadata, never authority.
 - One session accepts at most one live send operation. Reads and signals may observe it; another send fails until the operation settles.
 - `PtySendResult.waitReason` and `sessionStatus` are independent. `session_exit` describes the top-level PTY process, not an arbitrary foreground command.
-- `kill()` and disposal resolve only after the backend's captured process tree is quiescent. A cleanup failure rejects instead of claiming success.
+- `kill()` and disposal resolve only after the backend's captured process tree is quiescent. A cleanup failure rejects instead of claiming success and clears the matching backend and registry fences so a later close can retry without disturbing a newer attempt.
 
 The seam contains no `node-pty`, sandbox, tool-schema, prompt, task, or terminal-rendering policy. Implementations own terminal mechanics; consumers own model presentation and optional background-task registration.
 

packages/pty/pty/src/index.ts

@@ -6,6 +6,7 @@
 
 import { Context, Service } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import { PtyBackendCleanupError } from './types.ts'
 import type {
   PtyBackend,
   PtyBackendSession,
@@ -39,6 +40,7 @@ export type {
   PtySpawnResult,
   PtyWaitReason,
 } from './types.ts'
+export { PtyBackendCleanupError } from './types.ts'
 
 /** Opaque identity minted by {@link PtyService} for one live PTY session. */
 export type PtySessionId = PtySessionIdValue
@@ -77,10 +79,6 @@ export function PtySessionId(value: string): PtySessionId {
   return value as PtySessionId
 }
 
-function isAborted(signal: AbortSignal | undefined): boolean {
-  return signal?.aborted === true
-}
-
 interface SessionRecord {
   readonly id: PtySessionId
   readonly owner: Agent
@@ -91,11 +89,24 @@ interface SessionRecord {
   closing: Promise<void> | undefined
 }
 
+interface PendingSpawn {
+  readonly owner: Agent
+  readonly controller: AbortController
+  readonly settled: Promise<void>
+  cleanupFailure: { error: unknown } | undefined
+}
+
+interface SpawnReservation {
+  readonly signal: AbortSignal
+  release(cleanupFailure: { error: unknown } | undefined): void
+}
+
 /** In-process registry for replaceable PTY backends and exact-Agent sessions. */
 export class PtyService extends Service {
   private readonly backends = new Map<string, PtyBackend>()
   private readonly sessions = new Map<PtySessionId, SessionRecord>()
   private readonly reservedNames = new Map<Agent, Set<string>>()
+  private readonly pendingSpawns = new Map<Agent, Set<PendingSpawn>>()
   private readonly ownerCleanups = new Map<Agent, () => Promise<void> | void>()
   private readonly disposedOwners = new WeakSet<Agent>()
   private nextId = 0
@@ -142,15 +153,19 @@ export class PtyService extends Service {
    */
   async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult> {
     this.assertActive()
+    signal?.throwIfAborted()
     this.ensureOwnerCleanup(owner)
     const backend = this.backends.get(request.type)
     if (backend === undefined) throw new PtyError(`no PTY backend registered for "${request.type}"`, 'NO_BACKEND')
     if (request.name !== undefined && request.name.length === 0) throw new Error('PTY session name must be non-empty')
-    if (isAborted(signal)) throw new Error('PTY spawn aborted')
-
     const releaseName = this.reserveName(owner, request.name)
+    const spawnReservation = this.reserveSpawn(owner)
+    const backendSignal = signal === undefined
+      ? spawnReservation.signal
+      : AbortSignal.any([signal, spawnReservation.signal])
     const sessionId = PtySessionId(`pty-${++this.nextId}`)
     let session: PtyBackendSession | undefined
+    let cleanupFailure: { error: unknown } | undefined
     try {
       session = await backend.spawn({
         sessionId,
@@ -158,9 +173,13 @@ export class PtyService extends Service {
         type: request.type,
         ...request.name !== undefined ? { name: request.name } : {},
         ...request.cwd !== undefined ? { cwd: request.cwd } : {},
-        ...signal !== undefined ? { signal } : {},
+        signal: backendSignal,
       })
-      if (this.disposing || isAborted(signal) || !this.isLiveOwner(owner)) {
+      signal?.throwIfAborted()
+      if (this.disposing) {
+        throw new PtyError('PTY service is disposing', 'SERVICE_DISPOSING')
+      }
+      if (!this.isLiveOwner(owner)) {
         throw new PtyError('PTY owner is no longer live', 'OWNER_NOT_LIVE')
       }
       const record: SessionRecord = {
@@ -175,19 +194,45 @@ export class PtyService extends Service {
       this.sessions.set(sessionId, record)
       return this.snapshot(record, session.motd)
     } catch (error) {
+      if (error instanceof PtyBackendCleanupError) {
+        cleanupFailure = { error: error.cleanupError }
+      }
+      let rollbackFailure: { error: unknown } | undefined
       if (session !== undefined && !this.sessions.has(sessionId)) {
         try {
           await session.close('PTY spawn rolled back')
         } catch (closeError: unknown) {
-          throw new AggregateError([error, closeError], 'PTY spawn and rollback both failed')
+          rollbackFailure = { error: closeError }
+          cleanupFailure = rollbackFailure
         }
       }
-      throw error
+      let failure: unknown = error
+      try {
+        signal?.throwIfAborted()
+        spawnReservation.signal.throwIfAborted()
+      } catch (cancellation: unknown) {
+        failure = cancellation
+      }
+      if (rollbackFailure !== undefined && signal?.aborted !== true) {
+        throw new AggregateError([failure, rollbackFailure.error], 'PTY spawn and rollback both failed')
+      }
+      throw failure
     } finally {
+      spawnReservation.release(cleanupFailure)
       releaseName()
     }
   }
 
+  /**
+   * Test whether an exact owner has a published session or unpublished spawn.
+   * @param owner - exact live owner to inspect.
+   * @returns true across the entire spawn-to-close interval, with no publication gap.
+   */
+  hasOwnerActivity(owner: Agent): boolean {
+    return (this.pendingSpawns.get(owner)?.size ?? 0) > 0
+      || [...this.sessions.values()].some(record => record.owner === owner)
+  }
+
   /**
    * Start one exclusive interactive send.
    * @param owner - exact session owner.
@@ -302,6 +347,43 @@ export class PtyService extends Service {
     }
   }
 
+  private reserveSpawn(owner: Agent): SpawnReservation {
+    const controller = new AbortController()
+    const settlement = Promise.withResolvers<void>()
+    const pending: PendingSpawn = { owner, controller, settled: settlement.promise, cleanupFailure: undefined }
+    const owned = this.pendingSpawns.get(owner) ?? new Set<PendingSpawn>()
+    owned.add(pending)
+    this.pendingSpawns.set(owner, owned)
+    return {
+      signal: controller.signal,
+      release: (cleanupFailure) => {
+        pending.cleanupFailure = cleanupFailure
+        if (cleanupFailure === undefined) this.removePendingSpawn(pending)
+        settlement.resolve()
+      },
+    }
+  }
+
+  private removePendingSpawn(pending: PendingSpawn): void {
+    const owned = this.pendingSpawns.get(pending.owner)
+    if (owned === undefined) return
+    owned.delete(pending)
+    if (owned.size === 0) this.pendingSpawns.delete(pending.owner)
+  }
+
+  private async abortPendingSpawns(owner: Agent | undefined, reason: PtyError): Promise<void> {
+    const pending = owner === undefined
+      ? [...this.pendingSpawns.values()].flatMap(owned => [...owned])
+      : [...(this.pendingSpawns.get(owner) ?? [])]
+    for (const spawn of pending) spawn.controller.abort(reason)
+    await Promise.all(pending.map(spawn => spawn.settled))
+    const failures = pending.flatMap(spawn => spawn.cleanupFailure === undefined ? [] : [spawn.cleanupFailure.error])
+    for (const spawn of pending) this.removePendingSpawn(spawn)
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'failed to roll back unpublished PTY setup')
+    }
+  }
+
   private expectOwned(owner: Agent, id: PtySessionId): SessionRecord {
     const record = this.sessions.get(id)
     if (record === undefined) throw new PtyError(`unknown PTY session ${id}`, 'NO_SESSION')
@@ -322,23 +404,49 @@ export class PtyService extends Service {
     }
   }
 
+  private async abortAndClose(owner: Agent | undefined, abortReason: PtyError, closeReason: string): Promise<void> {
+    const failures: unknown[] = []
+    try {
+      await this.abortPendingSpawns(owner, abortReason)
+    } catch (error: unknown) {
+      failures.push(error)
+    }
+    const records = [...this.sessions.values()].filter(record => owner === undefined || record.owner === owner)
+    try {
+      await this.closeRecords(records, closeReason)
+    } catch (error: unknown) {
+      failures.push(error)
+    }
+    if (failures.length > 0) throw new AggregateError(failures, 'failed to clean up PTY lifecycle')
+  }
+
   private async disposeOwned(owner: Agent): Promise<void> {
-    const owned = [...this.sessions.values()].filter(record => record.owner === owner)
-    await this.closeRecords(owned, 'PTY owner disposed')
-    this.reservedNames.delete(owner)
+    try {
+      await this.abortAndClose(
+        owner,
+        new PtyError('PTY owner is no longer live', 'OWNER_NOT_LIVE'),
+        'PTY owner disposed',
+      )
+    } finally {
+      this.reservedNames.delete(owner)
+    }
   }
 
   private async disposeAll(): Promise<void> {
     this.disposing = true
-    const records = [...this.sessions.values()]
     // Teardown is best-effort: a close failure still clears registries and runs
     // owner cleanups before the aggregated error propagates, so one stuck
     // session cannot orphan backends, reservations, or owner detachers.
     try {
-      await this.closeRecords(records, 'PTY service disposed')
+      await this.abortAndClose(
+        undefined,
+        new PtyError('PTY service is disposing', 'SERVICE_DISPOSING'),
+        'PTY service disposed',
+      )
     } finally {
       this.backends.clear()
       this.reservedNames.clear()
+      this.pendingSpawns.clear()
       const cleanups = [...this.ownerCleanups.values()]
       this.ownerCleanups.clear()
       await Promise.all(cleanups.map(cleanup => Promise.resolve(cleanup())))
@@ -349,8 +457,14 @@ export class PtyService extends Service {
     const results = await Promise.allSettled(records.map(async (record) => {
       const closing = record.closing ?? record.session.close(reason)
       record.closing = closing
-      await closing
-      this.sessions.delete(record.id)
+      try {
+        await closing
+        this.sessions.delete(record.id)
+      } catch (error: unknown) {
+        // A concurrent retry may already own a newer fence; never clear it.
+        if (record.closing === closing) record.closing = undefined
+        throw error
+      }
     }))
     const failures = results
       .filter((result): result is PromiseRejectedResult => result.status === 'rejected')

packages/pty/pty/src/types.ts

@@ -10,6 +10,21 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 /** Internal exported basis for the public `PtySessionId` type/value pair. */
 export type PtySessionIdValue = Branded<'PtySessionId'>
 
+/**
+ * Backend-reported failure to clean partial resources after unpublished setup failed.
+ * @param spawnError - original setup or cancellation failure.
+ * @param cleanupError - failure that may leave backend-owned resources alive.
+ */
+export class PtyBackendCleanupError extends AggregateError {
+  constructor(
+    readonly spawnError: unknown,
+    readonly cleanupError: unknown,
+  ) {
+    super([spawnError, cleanupError], 'PTY backend startup and cleanup both failed')
+    this.name = 'PtyBackendCleanupError'
+  }
+}
+
 /** Why one interactive send returned control to its caller. */
 export type PtyWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
 
@@ -147,7 +162,7 @@ export interface PtyBackendSession {
 export interface PtyBackend {
   /** Stable type selected by {@link PtySpawnRequest.type}. */
   readonly type: string
-  /** Create an unpublished session or reject after cleaning partial resources. */
+  /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link PtyBackendCleanupError}. */
   spawn(spec: PtyBackendSpawnSpec): Promise<PtyBackendSession>
 }
 

packages/pty/pty/tests/service.spec.ts

@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import PtyService, { PtyError, PtySessionId } from '@deepseek-ai/dsh-pty'
+import PtyService, { PtyBackendCleanupError, PtyError, PtySessionId } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackend,
   PtyBackendSession,
@@ -160,6 +160,7 @@ describe('PtyService ownership and lifecycle', () => {
 
     const created = await ctx.pty.spawn(owner, { type: 'stub', name: 'main', cwd: '/tmp' })
     expect(created).toMatchObject({ sessionId: 'pty-1', name: 'main', type: 'stub', pid: 123, motd: 'stub ready', status: { kind: 'running' } })
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(true)
     expect(ctx.pty.list(owner)).toHaveLength(1)
     expect(ctx.pty.list(foreign)).toEqual([])
     expect(() => ctx.pty.read(foreign, created.sessionId)).toThrow('belongs to another agent')
@@ -178,8 +179,9 @@ describe('PtyService ownership and lifecycle', () => {
     const created = await ctx.pty.spawn(owner, { type: 'stub', name: 'main' })
     await expect(ctx.pty.spawn(owner, { type: 'stub', name: '' })).rejects.toThrow('must be non-empty')
     const aborted = new AbortController()
-    aborted.abort()
-    await expect(ctx.pty.spawn(owner, { type: 'stub' }, aborted.signal)).rejects.toThrow('spawn aborted')
+    const abortReason = new Error('spawn aborted')
+    aborted.abort(abortReason)
+    await expect(ctx.pty.spawn(owner, { type: 'stub' }, aborted.signal)).rejects.toBe(abortReason)
     await expect(ctx.pty.spawn(owner, { type: 'stub', name: 'main' })).rejects.toMatchObject({ code: 'DUPLICATE_NAME' })
 
     const operation = ctx.pty.startSend(owner, created.sessionId, { text: 'echo hi', submit: true })
@@ -205,12 +207,222 @@ describe('PtyService ownership and lifecycle', () => {
     ctx.agents.register(owner)
     const pending = ctx.pty.spawn(owner, { type: 'slow', name: 'main' })
     await expect(ctx.pty.spawn(owner, { type: 'slow', name: 'main' })).rejects.toMatchObject({ code: 'DUPLICATE_NAME' })
-    await disposeAgentScope(owner)
+    const disposal = disposeAgentScope(owner)
     gate.resolve(session)
     await expect(pending).rejects.toMatchObject({ code: 'OWNER_NOT_LIVE' })
+    await disposal
     expect(session.closed).toEqual(['PTY spawn rolled back'])
   })
 
+  it('preserves caller cancellation when a pending backend spawn completes', async () => {
+    const ctx = await harness()
+    const gate = Promise.withResolvers<PtyBackendSession>()
+    const session = new StubSession()
+    ctx.pty.registerBackend({ type: 'slow', spawn: () => gate.promise })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+    const controller = new AbortController()
+    const reason = new Error('cancelled by caller')
+
+    const pending = ctx.pty.spawn(owner, { type: 'slow' }, controller.signal)
+    controller.abort(reason)
+    gate.resolve(session)
+
+    await expect(pending).rejects.toBe(reason)
+    expect(session.closed).toEqual(['PTY spawn rolled back'])
+    expect(ctx.agents.get(owner.id)).toBe(owner)
+  })
+
+  it('preserves caller cancellation when unpublished rollback fails', async () => {
+    const ctx = await harness()
+    const gate = Promise.withResolvers<PtyBackendSession>()
+    const session = new StubSession()
+    session.rejectClose = true
+    ctx.pty.registerBackend({ type: 'slow', spawn: () => gate.promise })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+    const controller = new AbortController()
+    const reason = new Error('cancelled by caller')
+
+    const pending = ctx.pty.spawn(owner, { type: 'slow' }, controller.signal)
+    controller.abort(reason)
+    gate.resolve(session)
+
+    await expect(pending).rejects.toBe(reason)
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(true)
+    const internal = ctx.pty as unknown as { disposeAll(): Promise<void> }
+    await expect(internal.disposeAll()).rejects.toThrow('failed to clean up PTY lifecycle')
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(false)
+    expect(session.closed).toEqual(['PTY spawn rolled back'])
+  })
+
+  it('preserves caller cancellation when a backend rejects in response to it', async () => {
+    const ctx = await harness()
+    const started = Promise.withResolvers<undefined>()
+    const backendFailure = new Error('backend observed cancellation')
+    ctx.pty.registerBackend({
+      type: 'abortable',
+      spawn: ({ signal }) => new Promise((_resolve, reject) => {
+        if (signal === undefined) throw new Error('missing spawn signal')
+        started.resolve(undefined)
+        signal.addEventListener('abort', () => { reject(backendFailure) }, { once: true })
+      }),
+    })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+    const controller = new AbortController()
+    const reason = new Error('cancelled by caller')
+
+    const pending = ctx.pty.spawn(owner, { type: 'abortable' }, controller.signal)
+    await started.promise
+    controller.abort(reason)
+
+    await expect(pending).rejects.toBe(reason)
+  })
+
+  it.each(['owner', 'service'] as const)('retains caller-triggered backend cleanup failure until %s disposal', async (scope) => {
+    const ctx = await harness()
+    const started = Promise.withResolvers<undefined>()
+    const cleanupFailure = new Error('backend cleanup failed')
+    ctx.pty.registerBackend({
+      type: 'cleanup-failing',
+      spawn: ({ signal }) => new Promise((_resolve, reject) => {
+        if (signal === undefined) throw new Error('missing spawn signal')
+        started.resolve(undefined)
+        signal.addEventListener('abort', () => {
+          reject(new PtyBackendCleanupError(signal.reason, cleanupFailure))
+        }, { once: true })
+      }),
+    })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+    const controller = new AbortController()
+    const reason = new Error('cancelled by caller')
+
+    const pending = ctx.pty.spawn(owner, { type: 'cleanup-failing' }, controller.signal)
+    await started.promise
+    controller.abort(reason)
+
+    await expect(pending).rejects.toBe(reason)
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(true)
+    const internal = ctx.pty as unknown as {
+      disposeOwned(owner: Agent): Promise<void>
+      disposeAll(): Promise<void>
+    }
+    const disposal = scope === 'owner' ? internal.disposeOwned(owner) : internal.disposeAll()
+    await expect(disposal).rejects.toThrow('failed to clean up PTY lifecycle')
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(false)
+  })
+
+  it.each([
+    { scope: 'owner', code: 'OWNER_NOT_LIVE' },
+    { scope: 'service', code: 'SERVICE_DISPOSING' },
+  ] as const)('$scope disposal aborts and awaits unpublished backend setup', async ({ scope, code }) => {
+    const ctx = await harness()
+    const gate = Promise.withResolvers<PtyBackendSession>()
+    const started = Promise.withResolvers<undefined>()
+    const session = new StubSession()
+    let backendSignal: AbortSignal | undefined
+    ctx.pty.registerBackend({
+      type: 'slow',
+      spawn: (spec) => {
+        backendSignal = spec.signal
+        started.resolve(undefined)
+        return gate.promise
+      },
+    })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+
+    const pending = ctx.pty.spawn(owner, { type: 'slow' })
+    const pendingFailure = pending.then(
+      () => { throw new Error('pending spawn unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    await started.promise
+    let disposalSettled = false
+    const disposal = (scope === 'owner' ? disposeAgentScope(owner) : disposePtyService(ctx))
+      .then(() => { disposalSettled = true })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const signalAbortedBeforeRelease = backendSignal?.aborted ?? false
+    const signalReasonBeforeRelease = backendSignal?.reason as unknown
+    const disposalSettledBeforeRelease = disposalSettled
+    gate.resolve(session)
+
+    expect(await pendingFailure).toMatchObject({ code })
+    await disposal
+    expect(signalAbortedBeforeRelease).toBe(true)
+    expect(signalReasonBeforeRelease).toMatchObject({ code })
+    expect(disposalSettledBeforeRelease).toBe(false)
+    expect(session.closed).toEqual(['PTY spawn rolled back'])
+  })
+
+  it('reports unpublished rollback failure through service disposal', async () => {
+    const ctx = await harness()
+    const gate = Promise.withResolvers<PtyBackendSession>()
+    const session = new StubSession()
+    session.rejectClose = true
+    ctx.pty.registerBackend({ type: 'slow', spawn: () => gate.promise })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+
+    const pending = ctx.pty.spawn(owner, { type: 'slow' })
+    const pendingFailure = expect(pending).rejects.toThrow('PTY spawn and rollback both failed')
+    const internal = ctx.pty as unknown as { disposeAll(): Promise<void> }
+    const disposalFailure = expect(internal.disposeAll()).rejects.toThrow('failed to clean up PTY lifecycle')
+    gate.resolve(session)
+
+    await pendingFailure
+    await disposalFailure
+    expect(session.closed).toEqual(['PTY spawn rolled back'])
+  })
+
+  it.each([
+    { scope: 'owner', code: 'OWNER_NOT_LIVE' },
+    { scope: 'service', code: 'SERVICE_DISPOSING' },
+  ] as const)('$scope disposal retains backend-side startup cleanup failure', async ({ scope, code }) => {
+    const ctx = await harness()
+    const started = Promise.withResolvers<undefined>()
+    const cleanupFailure = new Error('backend cleanup failed')
+    let backendAbortReason: unknown
+    ctx.pty.registerBackend({
+      type: 'cleanup-failing',
+      spawn: ({ signal }) => new Promise((_resolve, reject) => {
+        if (signal === undefined) throw new Error('missing spawn signal')
+        started.resolve(undefined)
+        signal.addEventListener('abort', () => {
+          backendAbortReason = signal.reason
+          reject(new PtyBackendCleanupError(signal.reason, cleanupFailure))
+        }, { once: true })
+      }),
+    })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+
+    const pending = ctx.pty.spawn(owner, { type: 'cleanup-failing' })
+    await started.promise
+    const internal = ctx.pty as unknown as {
+      disposeOwned(owner: Agent): Promise<void>
+      disposeAll(): Promise<void>
+    }
+    const disposal = scope === 'owner' ? internal.disposeOwned(owner) : internal.disposeAll()
+    const pendingError = await pending.then(
+      () => { throw new Error('pending spawn unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+
+    expect(pendingError).toBe(backendAbortReason)
+    expect(pendingError).toMatchObject({ code })
+    const disposalError = await disposal.then(
+      () => { throw new Error('disposal unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    expect(disposalError).toMatchObject({ message: 'failed to clean up PTY lifecycle' })
+    const rollbackError = (disposalError as AggregateError).errors[0] as unknown
+    const cleanupErrors = (rollbackError as AggregateError).errors as unknown[]
+    expect(cleanupErrors).toEqual([cleanupFailure])
+  })
+
   it('keeps independent reservations and handles provider failure before publication', async () => {
     const ctx = await harness()
     const firstGate = Promise.withResolvers<PtyBackendSession>()
@@ -254,14 +466,27 @@ describe('PtyService ownership and lifecycle', () => {
     ctx.agents.register(owner)
     const failedSpawn = new StubSession()
     failedSpawn.rejectClose = true
+    let ownerDisposal = Promise.resolve()
+    const internal = ctx.pty as unknown as {
+      disposedOwners: WeakSet<Agent>
+      disposeOwned(owner: Agent): Promise<void>
+    }
     ctx.pty.registerBackend({
       type: 'bad-spawn',
-      async spawn() {
-        await disposeAgentScope(owner)
+      async spawn({ signal }) {
+        if (signal === undefined) throw new Error('missing spawn signal')
+        internal.disposedOwners.add(owner)
+        ownerDisposal = internal.disposeOwned(owner)
+        if (!signal.aborted) {
+          await new Promise<undefined>((resolve) => {
+            signal.addEventListener('abort', () => { resolve(undefined) }, { once: true })
+          })
+        }
         return failedSpawn
       },
     })
     await expect(ctx.pty.spawn(owner, { type: 'bad-spawn' })).rejects.toThrow('spawn and rollback both failed')
+    await expect(ownerDisposal).rejects.toThrow('failed to clean up PTY lifecycle')
 
     const nextOwner = stubAgent(ctx, 'next')
     ctx.agents.register(nextOwner)
@@ -338,8 +563,15 @@ describe('PtyService ownership and lifecycle', () => {
       sessions: Map<PtySessionIdType, unknown>
       closeRecords(records: unknown[], reason: string): Promise<void>
     }
-    await expect(internal.closeRecords([...internal.sessions.values()], 'test failure')).rejects.toThrow('failed to close 1 PTY session')
+    const records = [...internal.sessions.values()]
+    const firstFailure = expect(internal.closeRecords(records, 'test failure')).rejects.toThrow('failed to close 1 PTY session')
+    const joinedFailure = expect(internal.closeRecords(records, 'joined failure')).rejects.toThrow('failed to close 1 PTY session')
+    await firstFailure
+    await joinedFailure
     b.sessions[0]!.rejectClose = false
+    await expect(internal.closeRecords([...internal.sessions.values()], 'retry')).resolves.toBeUndefined()
+    expect(b.sessions[0]!.closed).toEqual(['test failure', 'retry'])
+    expect(internal.sessions.size).toBe(0)
     await disposePtyService(ctx)
     await expect(service.spawn(owner, { type: 'stub' })).rejects.toMatchObject({ code: 'SERVICE_DISPOSING' })
   })
@@ -360,7 +592,7 @@ describe('PtyService ownership and lifecycle', () => {
     }
     // Teardown surfaces the close failure, but its finally still clears the
     // backend and owner-cleanup registries instead of orphaning them.
-    await expect(internal.disposeAll()).rejects.toThrow('failed to close 1 PTY session')
+    await expect(internal.disposeAll()).rejects.toThrow('failed to clean up PTY lifecycle')
     expect(internal.backends.size).toBe(0)
     expect(internal.ownerCleanups.size).toBe(0)
   })

packages/pty/tool-pty/README.md

@@ -2,7 +2,16 @@
 
 Six model-facing tools over `ctx.pty`: `terminal_open`, `terminal_send`, `terminal_read`, `terminal_signal`, `terminal_close`, and `terminal_list`. Every operation requires the exact initiating `Agent`, so a model cannot address another agent's terminal even if it learns the id.
 
-`terminal_send(run_in_background: true)` reuses `ctx.tasks`; task preflight occurs before any terminal write, completion is collected with `task_output`, and `task_kill` requests `Ctrl-C`. Foreground sends use terminal ACP cards; lifecycle, history, signal, and list calls use generic cards.
+`terminal_send(run_in_background: true)` reuses `ctx.tasks`; task preflight and the PTY service's exclusive per-session send reservation occur before the task id is returned, completion is collected with `task_output`, and `task_kill` delivers `SIGINT` to the foreground process group. Foreground sends use terminal ACP call/result cards. Background sends use a generic execute card; open, read, signal, close, and list use generic `execute`, `read`, `execute`, `delete`, and `read` cards respectively. None declares source locations.
+
+## Config
+
+| key | default | meaning |
+|---|---:|---|
+| `enableRunInBackground` | `true` | expose and accept `run_in_background`; false omits the schema field and rejects a forced undeclared argument |
+| `maxResultBytes` | `262144` | UTF-8 cap (minimum `64`) for each complete terminal result or PTY task output after wait, session, pagination, truncation, and task-status metadata |
+
+Both values are validated at load. The minimum result cap keeps every registry-issued session or task id visible in its creation acknowledgement. When a result exceeds `maxResultBytes`, rendering reserves space for control metadata and a truncation marker when they fit; cuts preserve UTF-8 boundaries. Each terminal definition's final-content callback applies the same cap after normalized pre-, around-, and post-execute policy failures, denials, short-circuits, replacements, or blocks; a structured multi-block policy result retains its shape.
 
 ## Model Experience
 
@@ -44,11 +53,11 @@ Prefix-stable while tool visibility and definitions are unchanged.
 
 #### What the model sees
 
-Spawn returns the id and bounded MOTD. Send/read return bounded terminal text plus readiness/history markers. Background mode returns a generic task id. Results remain in session history until compaction; incremental task reads do not repeat consumed output. Programmatic callers receive typed session snapshots, bounded send/read DTOs, signal and close outcomes, or `{ kind: "background", taskId }`; Native rendering preserves the text above.
+Spawn returns the id and bounded MOTD. Send/read return bounded terminal text plus readiness/history markers. Background mode returns a generic task id. Every terminal-owned or policy-produced single-text result is capped by `maxResultBytes` after normalized tool or pipeline errors, denials, short-circuits, replacements, blocks, and generic task status text. Structured multi-block policy results retain their shape. Results remain in session history until compaction; incremental task reads do not repeat consumed output. Programmatic callers receive typed session snapshots, bounded provider read/send DTOs, signal and close outcomes, or `{ kind: "background", taskId }`; Native rendering applies the presentation cap above.
 
 #### Token effect
 
-Data-dependent and bounded by the backend; each returned result remains in history until compaction.
+Terminal-owned and policy-produced single-text results are data-dependent and bounded by `maxResultBytes`; a policy that deliberately substitutes structured multi-block content owns that content's bound. Each returned result remains in history until compaction.
 
 #### KV Cache effect
 

packages/pty/tool-pty/package.json

@@ -26,11 +26,15 @@
     "src"
   ],
   "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-pty": "^0.0.1",
+    "@deepseek-ai/dsh-retention": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
@@ -44,6 +48,7 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-pty": "workspace:^",
     "@deepseek-ai/dsh-pty-local": "workspace:^",
+    "@deepseek-ai/dsh-retention": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",

packages/pty/tool-pty/src/index.ts

@@ -5,13 +5,15 @@
  */
 
 import { Context } from 'cordis'
+import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { PtySessionId } from '@deepseek-ai/dsh-pty'
 import type { PtySendResult, PtySessionId as PtySessionIdType, PtySignal } from '@deepseek-ai/dsh-pty'
 import type {} from '@deepseek-ai/dsh-tasks'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ToolResult } from '@deepseek-ai/dsh-tools'
-import { renderList, renderRead, renderSend, renderSendRead, renderSpawn } from './render.ts'
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import { boundTerminalText, renderList, renderRead, renderSend, renderSendRead, renderSpawn } from './render.ts'
 
 declare module '@deepseek-ai/dsh-tasks' {
   interface TaskKindMap {
@@ -24,6 +26,25 @@ export const name = 'tool-pty'
 /** Required capability, registry, and prompt services. */
 export const inject = ['pty', 'tools', 'systemPrompt']
 
+/** Default cap for one complete model-facing terminal result. */
+export const DEFAULT_MAX_RESULT_BYTES = 256 * 1024
+/** Smallest cap that preserves every counter-backed PTY and task id in its creation acknowledgement. */
+export const MIN_MAX_RESULT_BYTES = 64
+
+/** Model-facing terminal tool configuration. */
+export interface Config {
+  /** Expose `run_in_background` and accept background sends (default true). */
+  enableRunInBackground?: boolean
+  /** Maximum UTF-8 bytes in one complete terminal or task-output result. */
+  maxResultBytes?: number
+}
+
+/** Schemastery configuration for the terminal tool consumer. */
+export const Config: z<Config> = z.object({
+  enableRunInBackground: z.boolean().default(true),
+  maxResultBytes: z.number().step(1).min(MIN_MAX_RESULT_BYTES).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RESULT_BYTES),
+})
+
 interface SpawnArgs {
   type: string
   name?: string
@@ -105,9 +126,13 @@ function sessionId(args: SessionArgs): PtySessionIdType {
   return PtySessionId(args.sessionId)
 }
 
-function rawResultText(result: ToolResult): string | undefined {
-  if (result.content.length !== 1) return undefined
-  const block = result.content[0]
+function textResult(text: string, maxBytes: number): ContentBlock[] {
+  return [{ type: 'text', text: boundTerminalText(text, maxBytes) }]
+}
+
+function rawContentText(content: readonly ContentBlock[]): string | undefined {
+  if (content.length !== 1) return undefined
+  const block = content[0]
   return block?.type === 'text' ? block.text : undefined
 }
 
@@ -118,7 +143,16 @@ function sendDetail(result: PtySendResult): string {
 }
 
 /** Register all terminal tools and the minimal usage guidance. */
-export function apply(ctx: Context): void {
+export function apply(ctx: Context, config: Config = {}): void {
+  const enableRunInBackground = config.enableRunInBackground ?? true
+  const maxResultBytes = config.maxResultBytes ?? DEFAULT_MAX_RESULT_BYTES
+  if (!Number.isSafeInteger(maxResultBytes) || maxResultBytes < MIN_MAX_RESULT_BYTES) {
+    throw new Error(`tool-pty: maxResultBytes must be a safe integer of at least ${MIN_MAX_RESULT_BYTES}`)
+  }
+  const finalizeContent: NonNullable<ToolDefinition['finalizeContent']> = (_exec, result) => {
+    const raw = rawContentText(result.content)
+    return raw === undefined ? undefined : textResult(raw, maxResultBytes)
+  }
   ctx.systemPrompt.section({
     name: 'tool:pty',
     order: 106,
@@ -133,6 +167,7 @@ export function apply(ctx: Context): void {
       name: { type: 'string', description: 'Optional owner-local display name such as "main" or "gdb".' },
       cwd: { type: 'string', description: 'Initial working directory. Defaults to the deployment workspace root.' },
     },
+    finalizeContent,
     output: {
       schema: {
         type: 'object',
@@ -142,7 +177,7 @@ export function apply(ctx: Context): void {
           motd: { type: 'string', required: true },
         },
       },
-      render: (_args, value) => [{ type: 'text', text: renderSpawn(value) }],
+      render: (_args, value) => [{ type: 'text', text: renderSpawn(value, maxResultBytes) }],
     },
     async execute(args: SpawnArgs, exec) {
       if (args.type.length === 0) throw new Error('type must be a non-empty string')
@@ -161,13 +196,17 @@ export function apply(ctx: Context): void {
 
   ctx.tools.register(defineTool({
     name: 'terminal_send',
-    description: 'Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit. Background mode returns a task id for task_output/task_kill.',
+    description: 'Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit.'
+      + (enableRunInBackground ? ' Background mode returns a task id for task_output/task_kill.' : ''),
     parameters: {
       sessionId: { type: 'string', required: true, description: 'Terminal session id returned by terminal_open or terminal_list.' },
       text: { type: 'string', required: true, description: 'UTF-8 text to write to the terminal.' },
       submit: { type: 'boolean', description: 'Submit Enter after text (default true). Set false for control characters or incomplete REPL input.' },
-      run_in_background: { type: 'boolean', description: 'Return a task id immediately; collect with task_output or stop with task_kill.' },
+      ...enableRunInBackground
+        ? { run_in_background: { type: 'boolean' as const, description: 'Return a task id immediately; collect with task_output or stop with task_kill.' } }
+        : {},
     },
+    finalizeContent,
     output: {
       schema: {
         oneOf: [
@@ -193,7 +232,7 @@ export function apply(ctx: Context): void {
         type: 'text',
         text: value.kind === 'background'
           ? `started background task ${value.taskId}`
-          : renderSend(value),
+          : renderSend(value, maxResultBytes),
       }],
       presentationMeta: (_args, value) => value.kind === 'foreground'
         ? {
@@ -209,6 +248,7 @@ export function apply(ctx: Context): void {
       const id = sessionId(args)
       const request = { text: args.text, submit: args.submit ?? true }
       if (args.run_in_background === true) {
+        if (!enableRunInBackground) throw new Error('background terminal sends are disabled by tool-pty configuration')
         const tasks = ctx.get('tasks')
         if (tasks === undefined) throw new Error('background terminal sends require @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
         let cancelRequested = false
@@ -216,6 +256,7 @@ export function apply(ctx: Context): void {
           kind: 'pty-send',
           label: `${id}: ${args.text || '(input)'}`,
           owner,
+          outputLimitBytes: maxResultBytes,
           run: () => {
             const operation = ctx.pty.startSend(owner, id, request)
             return {
@@ -247,7 +288,7 @@ export function apply(ctx: Context): void {
     },
     presentResult(args, result) {
       if ((args as Partial<SendArgs>).run_in_background === true || result.isError) return undefined
-      const raw = rawResultText(result)
+      const raw = rawContentText(result.content)
       return raw === undefined ? undefined : { card: 'terminal', output: raw }
     },
   }))
@@ -260,6 +301,7 @@ export function apply(ctx: Context): void {
       offset: { type: 'number', description: 'Newest-relative line offset (default 0).' },
       count: { type: 'number', description: 'Requested line count (default 500; backend caps apply).' },
     },
+    finalizeContent,
     output: {
       schema: {
         type: 'object',
@@ -272,7 +314,7 @@ export function apply(ctx: Context): void {
           truncated: { type: 'boolean', required: true },
         },
       },
-      render: (_args, value) => [{ type: 'text', text: renderRead(value) }],
+      render: (_args, value) => [{ type: 'text', text: renderRead(value, maxResultBytes) }],
     },
     execute(args: ReadArgs, exec) {
       const result = ctx.pty.read(requireAgent(exec.agent), sessionId(args), {
@@ -291,6 +333,7 @@ export function apply(ctx: Context): void {
       sessionId: { type: 'string', required: true, description: 'Terminal session id.' },
       signal: { type: 'string', required: true, enum: ['SIGINT', 'SIGTERM', 'SIGKILL', 'SIGTSTP', 'SIGHUP'], description: 'Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.' },
     },
+    finalizeContent,
     output: {
       schema: {
         type: 'object',
@@ -314,6 +357,7 @@ export function apply(ctx: Context): void {
     parameters: {
       sessionId: { type: 'string', required: true, description: 'Terminal session id.' },
     },
+    finalizeContent,
     output: {
       schema: {
         type: 'object',
@@ -342,9 +386,10 @@ export function apply(ctx: Context): void {
     name: 'terminal_list',
     description: 'List persistent terminal sessions owned by the current agent.',
     parameters: {},
+    finalizeContent,
     output: {
       schema: { type: 'array', items: SESSION_SNAPSHOT_SCHEMA },
-      render: (_args, value) => [{ type: 'text', text: renderList(value) }],
+      render: (_args, value) => [{ type: 'text', text: renderList(value, maxResultBytes) }],
     },
     execute(_args: Record<string, never>, exec) {
       return Promise.resolve(ctx.pty.list(requireAgent(exec.agent)))

packages/pty/tool-pty/src/render.ts

@@ -1,5 +1,7 @@
 /** Model and ACP rendering for persistent terminal tool results. */
 
+import { TextRetainer } from '@deepseek-ai/dsh-retention'
+
 interface RenderedSessionStatusRunning {
   kind: 'running'
 }
@@ -44,56 +46,126 @@ interface RenderedReadResult {
   truncated: boolean
 }
 
+const encoder = new TextEncoder()
+const TRUNCATED = '\n[output truncated]'
+
+function byteLength(text: string): number {
+  return encoder.encode(text).byteLength
+}
+
+function retain(text: string, maxBytes: number, kind: 'head' | 'tail'): string {
+  const retainer = new TextRetainer({ kind, maxBytes })
+  retainer.push(text)
+  return retainer.finish().text
+}
+
+function fitWithSuffix(content: string, suffix: string, maxBytes: number): string {
+  const fixedBytes = byteLength(suffix)
+  if (fixedBytes >= maxBytes) return retain(suffix, maxBytes, 'tail')
+  return `${retain(content, maxBytes - fixedBytes, 'tail')}${suffix}`
+}
+
+function fitWithPrefix(prefix: string, content: string, maxBytes: number): string {
+  const fixed = `${prefix}${TRUNCATED}`
+  const fixedBytes = byteLength(fixed)
+  if (fixedBytes >= maxBytes) return retain(fixed, maxBytes, 'head')
+  return `${prefix}${retain(content, maxBytes - fixedBytes, 'tail')}${TRUNCATED}`
+}
+
+function boundBodyWithSuffix(
+  content: string,
+  metadata: string,
+  upstreamTruncated: boolean,
+  maxBytes: number,
+): string {
+  const suffix = `${metadata}${upstreamTruncated ? TRUNCATED : ''}`
+  const complete = `${content}${suffix}`
+  if (byteLength(complete) <= maxBytes) return complete
+  return fitWithSuffix(content, `${metadata}${TRUNCATED}`, maxBytes)
+}
+
+/**
+ * Bound one complete terminal acknowledgement while preserving UTF-8 cuts.
+ * @param text - complete acknowledgement text.
+ * @param maxBytes - positive final result cap.
+ * @returns bounded text with a truncation marker when it fits.
+ */
+export function boundTerminalText(text: string, maxBytes: number): string {
+  if (byteLength(text) <= maxBytes) return text
+  const markerBytes = byteLength(TRUNCATED)
+  if (markerBytes >= maxBytes) return retain(TRUNCATED, maxBytes, 'tail')
+  return `${retain(text, maxBytes - markerBytes, 'head')}${TRUNCATED}`
+}
+
 /**
  * Render one created session and its bounded MOTD.
  * @param result - published spawn result.
+ * @param maxBytes - complete UTF-8 result cap.
  * @returns Model-facing session acknowledgement.
  */
-export function renderSpawn(result: RenderedSpawnResult): string {
+export function renderSpawn(result: RenderedSpawnResult, maxBytes: number): string {
   const label = result.name === undefined ? result.sessionId : `${result.sessionId} (${result.name})`
-  return `started terminal session ${label} [type: ${result.type}]\n${result.motd || '(no startup output)'}`
+  const prefix = `started terminal session ${label} [type: ${result.type}]\n`
+  const motd = result.motd || '(no startup output)'
+  const complete = `${prefix}${motd}`
+  return byteLength(complete) <= maxBytes ? complete : fitWithPrefix(prefix, motd, maxBytes)
 }
 
 /**
  * Render one settled interactive send.
  * @param result - settled send outcome.
+ * @param maxBytes - complete UTF-8 result cap.
  * @returns Terminal output plus wait/session markers.
  */
-export function renderSend(result: RenderedSendResult): string {
+export function renderSend(result: RenderedSendResult, maxBytes: number): string {
   const output = result.viewport || '(no new output)'
   const status = result.sessionStatus.kind === 'running'
     ? 'running'
     : `exited code=${result.sessionStatus.exitCode ?? 'null'} signal=${result.sessionStatus.signal ?? 'null'}`
-  return `${output}\n[wait: ${result.waitReason}]\n[session: ${status}]${result.truncated ? '\n[output truncated]' : ''}`
+  return boundBodyWithSuffix(
+    output,
+    `\n[wait: ${result.waitReason}]\n[session: ${status}]`,
+    result.truncated,
+    maxBytes,
+  )
 }
 
 /**
  * Render one incremental background operation read.
  * @param read - consuming operation delta.
- * @returns Delta plus truncation marker when needed.
+ * @returns Delta plus its upstream truncation marker. The generic task control
+ *   applies the producer's complete-result cap after adding task status.
  */
 export function renderSendRead(read: RenderedSendRead): string {
-  return `${read.delta}${read.truncated ? `${read.delta.endsWith('\n') || read.delta.length === 0 ? '' : '\n'}[output truncated]` : ''}`
+  const separator = read.delta.endsWith('\n') || read.delta.length === 0 ? '' : '\n'
+  return `${read.delta}${read.truncated ? `${separator}[output truncated]` : ''}`
 }
 
 /**
  * Render one bounded historical page.
  * @param result - retained scrollback page.
+ * @param maxBytes - complete UTF-8 result cap.
  * @returns Page text plus pagination and truncation markers.
  */
-export function renderRead(result: RenderedReadResult): string {
+export function renderRead(result: RenderedReadResult, maxBytes: number): string {
   const output = result.text || '(no retained output)'
-  return `${output}\n[lines: ${result.lineBegin}-${result.lineEnd} of ${result.totalLines}]${result.truncated ? '\n[output truncated]' : ''}`
+  return boundBodyWithSuffix(
+    output,
+    `\n[lines: ${result.lineBegin}-${result.lineEnd} of ${result.totalLines}]`,
+    result.truncated,
+    maxBytes,
+  )
 }
 
 /**
  * Render owner-visible live sessions.
  * @param sessions - fresh owner-scoped snapshots.
+ * @param maxBytes - complete UTF-8 result cap.
  * @returns One line per session or the empty marker.
  */
-export function renderList(sessions: readonly RenderedSessionSnapshot[]): string {
+export function renderList(sessions: readonly RenderedSessionSnapshot[], maxBytes: number): string {
   if (sessions.length === 0) return '(no terminal sessions)'
-  return sessions.map((session) => {
+  const text = sessions.map((session) => {
     const name = session.name === undefined ? '' : ` (${session.name})`
     const pid = session.pid === undefined ? '' : ` pid=${session.pid}`
     const status = session.status.kind === 'running'
@@ -101,4 +173,5 @@ export function renderList(sessions: readonly RenderedSessionSnapshot[]): string
       : `exited code=${session.status.exitCode ?? 'null'} signal=${session.status.signal ?? 'null'}`
     return `${session.sessionId}${name} [${session.type}] ${status}${pid}`
   }).join('\n')
+  return boundBodyWithSuffix(text, '', false, maxBytes)
 }

packages/pty/tool-pty/tests/render.spec.ts

@@ -1,23 +1,23 @@
 import { describe, expect, it } from 'vitest'
 import { PtySessionId } from '@deepseek-ai/dsh-pty'
-import { renderList, renderRead, renderSend, renderSendRead, renderSpawn } from '@deepseek-ai/dsh-tool-pty/src/render.ts'
+import { boundTerminalText, renderList, renderRead, renderSend, renderSendRead, renderSpawn } from '@deepseek-ai/dsh-tool-pty/src/render.ts'
 
 describe('tool-pty rendering', () => {
   it('renders spawn with and without names or MOTD', () => {
-    expect(renderSpawn({ sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' }, motd: '' }))
+    expect(renderSpawn({ sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' }, motd: '' }, 1024))
       .toBe('started terminal session pty-1 [type: shell]\n(no startup output)')
-    expect(renderSpawn({ sessionId: PtySessionId('pty-2'), name: 'main', type: 'shell', pid: 2, status: { kind: 'running' }, motd: 'ready' }))
+    expect(renderSpawn({ sessionId: PtySessionId('pty-2'), name: 'main', type: 'shell', pid: 2, status: { kind: 'running' }, motd: 'ready' }, 1024))
       .toContain('pty-2 (main)')
   })
 
   it('renders running, exited, empty, and truncated sends', () => {
-    expect(renderSend({ viewport: '', waitReason: 'timeout', sessionStatus: { kind: 'running' }, truncated: true }))
+    expect(renderSend({ viewport: '', waitReason: 'timeout', sessionStatus: { kind: 'running' }, truncated: true }, 1024))
       .toBe('(no new output)\n[wait: timeout]\n[session: running]\n[output truncated]')
-    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGTERM' }, truncated: false }))
+    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGTERM' }, truncated: false }, 1024))
       .toContain('exited code=null signal=SIGTERM')
-    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: 2, signal: null }, truncated: false }))
+    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: 2, signal: null }, truncated: false }, 1024))
       .toContain('exited code=2 signal=null')
-    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: null }, truncated: false }))
+    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: null }, truncated: false }, 1024))
       .toContain('exited code=null signal=null')
     expect(renderSendRead({ delta: '', truncated: true })).toBe('[output truncated]')
     expect(renderSendRead({ delta: 'x', truncated: true })).toBe('x\n[output truncated]')
@@ -26,14 +26,48 @@ describe('tool-pty rendering', () => {
   })
 
   it('renders history and every list status shape', () => {
-    expect(renderRead({ text: '', totalLines: 0, lineBegin: 0, lineEnd: 0, truncated: true }))
+    expect(renderRead({ text: '', totalLines: 0, lineBegin: 0, lineEnd: 0, truncated: true }, 1024))
       .toBe('(no retained output)\n[lines: 0-0 of 0]\n[output truncated]')
-    expect(renderList([])).toBe('(no terminal sessions)')
+    expect(renderList([], 1024)).toBe('(no terminal sessions)')
     expect(renderList([
       { sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' } },
       { sessionId: PtySessionId('pty-2'), name: 'done', type: 'shell', pid: 9, status: { kind: 'exited', exitCode: 2, signal: null } },
       { sessionId: PtySessionId('pty-3'), type: 'shell', status: { kind: 'exited', exitCode: null, signal: 'SIGTERM' } },
       { sessionId: PtySessionId('pty-4'), type: 'shell', status: { kind: 'exited', exitCode: null, signal: null } },
-    ])).toBe('pty-1 [shell] running\npty-2 (done) [shell] exited code=2 signal=null pid=9\npty-3 [shell] exited code=null signal=SIGTERM\npty-4 [shell] exited code=null signal=null')
+    ], 1024)).toBe('pty-1 [shell] running\npty-2 (done) [shell] exited code=2 signal=null pid=9\npty-3 [shell] exited code=null signal=SIGTERM\npty-4 [shell] exited code=null signal=null')
+  })
+
+  it('bounds complete UTF-8 results while retaining terminal metadata when it fits', () => {
+    const send = renderSend({
+      viewport: `prefix-${'界'.repeat(40)}`,
+      waitReason: 'stdin_read',
+      sessionStatus: { kind: 'running' },
+      truncated: false,
+    }, 64)
+    expect(Buffer.byteLength(send)).toBeLessThanOrEqual(64)
+    expect(send).toContain('[wait: stdin_read]')
+    expect(send).toContain('[output truncated]')
+
+    const read = renderRead({
+      text: 'x'.repeat(200), totalLines: 20, lineBegin: 0, lineEnd: 10, truncated: false,
+    }, 48)
+    expect(Buffer.byteLength(read)).toBeLessThanOrEqual(48)
+    expect(read).toContain('[lines: 0-10 of 20]')
+
+    expect(Buffer.byteLength(renderSpawn({
+      sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' }, motd: 'x'.repeat(200),
+    }, 32))).toBeLessThanOrEqual(32)
+
+    const boundedSpawn = renderSpawn({
+      sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' }, motd: 'x'.repeat(200),
+    }, 96)
+    expect(boundedSpawn).toContain('started terminal session pty-1')
+    expect(boundedSpawn).toContain('[output truncated]')
+
+    expect(Buffer.byteLength(renderSend({
+      viewport: 'x'.repeat(200), waitReason: 'stdin_read', sessionStatus: { kind: 'running' }, truncated: false,
+    }, 8))).toBeLessThanOrEqual(8)
+    expect(boundTerminalText('x'.repeat(200), 8)).toHaveLength(8)
+    expect(boundTerminalText('x'.repeat(200), 32).endsWith('[output truncated]')).toBe(true)
   })
 })

packages/pty/tool-pty/tests/tools.spec.ts

@@ -32,20 +32,23 @@ class StubSession implements PtyBackendSession {
   autoSettle = true
   rejectOperation = false
   closeGate: PromiseWithResolvers<undefined> | undefined
+  viewport = 'command output'
+  delta = 'live output'
+  deltaTruncated = false
 
   startSend(_request: PtySendRequest): PtySendOperation {
     let settle!: () => void
     let reject!: (error: unknown) => void
     let cancelled = false
     const done = new Promise<void>((resolve, rejectPromise) => { settle = resolve; reject = rejectPromise }).then(() => ({
-      viewport: cancelled ? '^C' : 'command output',
+      viewport: cancelled ? '^C' : this.viewport,
       waitReason: 'stdin_read' as const,
       sessionStatus: this.statusValue,
       truncated: false,
     }))
     const operation: PtySendOperation = {
       done,
-      readOutput: () => ({ delta: 'live output', truncated: false }),
+      readOutput: () => ({ delta: this.delta, truncated: this.deltaTruncated }),
       cancel: () => {
         if (cancelled) return false
         cancelled = true
@@ -88,7 +91,13 @@ function stubBackend() {
   return { backend, sessions }
 }
 
-async function setup(tasks: boolean) {
+async function setup(tasks: boolean, config: ToolPty.Config = {}) {
+  const base = await setupBase(tasks)
+  await base.ctx.plugin(ToolPty, config)
+  return base
+}
+
+async function setupBase(tasks: boolean) {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
@@ -100,7 +109,6 @@ async function setup(tasks: boolean) {
     await ctx.plugin(TaskService)
     await ctx.plugin(ToolTasks)
   }
-  await ctx.plugin(ToolPty)
   return { ctx, stub, agent: fakeAgent(ctx, tasks ? 'with-tasks' : 'foreground') }
 }
 
@@ -291,6 +299,101 @@ describe('tool-pty foreground surface', () => {
     expect(ctx.tools.get('terminal_close')?.presentCall?.({ sessionId: 'pty-1' })).toMatchObject({ card: 'generic', title: 'Close terminal pty-1' })
     expect(ctx.tools.get('terminal_list')?.presentCall?.({})).toMatchObject({ card: 'generic', title: 'List terminal sessions' })
   })
+
+  it('configuration-gates background sends and validates the final result bound', async () => {
+    const disabled = await setup(true, { enableRunInBackground: false })
+    const definition = disabled.ctx.tools.get('terminal_send')
+    expect(definition?.parameters).not.toHaveProperty('properties.run_in_background')
+    expect(definition?.description).not.toContain('Background mode')
+    await call(disabled.ctx, 'terminal_open', { type: 'stub' }, disabled.agent)
+    expect((await call(disabled.ctx, 'terminal_send', {
+      sessionId: 'pty-1', text: 'work', run_in_background: true,
+    }, disabled.agent)).isError).toBe(true)
+
+    const defaults = await setupBase(false)
+    ToolPty.apply(defaults.ctx)
+    expect(defaults.ctx.tools.get('terminal_send')?.parameters).toHaveProperty('properties.run_in_background')
+
+    const invalid = await setupBase(false)
+    expect(() => { ToolPty.apply(invalid.ctx, { maxResultBytes: 0 }) }).toThrow('maxResultBytes')
+    expect(() => { ToolPty.apply(invalid.ctx, { maxResultBytes: 63 }) }).toThrow('at least 64')
+  })
+
+  it('bounds normalized errors and preserves allocated ids at the minimum result cap', async () => {
+    const { ctx, agent } = await setup(true, { maxResultBytes: 64 })
+    const failed = await call(ctx, 'terminal_open', { type: 'x'.repeat(1_000) }, agent)
+    expect(failed.isError).toBe(true)
+    expect(Buffer.byteLength(text(failed))).toBeLessThanOrEqual(64)
+    expect(text(failed)).toContain('[output truncated]')
+
+    const opened = await call(ctx, 'terminal_open', { type: 'stub', name: 'n'.repeat(1_000) }, agent)
+    expect(text(opened)).toContain('pty-1')
+    expect(Buffer.byteLength(text(opened))).toBeLessThanOrEqual(64)
+    const background = await call(ctx, 'terminal_send', {
+      sessionId: 'pty-1', text: 'work', run_in_background: true,
+    }, agent)
+    expect(text(background)).toContain('pty-send-1')
+    expect(Buffer.byteLength(text(background))).toBeLessThanOrEqual(64)
+  })
+
+  it('bounds terminal results after policy decisions and pipeline failures', async () => {
+    const { ctx, agent } = await setup(false, { maxResultBytes: 64 })
+    ctx.on('tools/pre-execute', async (exec, next) => {
+      if (exec.name === 'terminal_list') return { kind: 'deny', reason: 'd'.repeat(1_000) }
+      if (exec.name === 'terminal_signal') throw new Error(`pre failed: ${'p'.repeat(1_000)}`)
+      return next()
+    })
+    ctx.on('tools/execute', async (exec, next) => {
+      if (exec.name === 'terminal_close') throw new Error(`around failed: ${'e'.repeat(1_000)}`)
+      return next()
+    })
+    ctx.on('tools/post-execute', async (exec, _result, next) => {
+      if (exec.name === 'terminal_open') {
+        return { kind: 'accept', content: [{ type: 'text', text: 'a'.repeat(1_000) }] }
+      }
+      if (exec.name === 'terminal_read') {
+        return { kind: 'block', feedback: [{ type: 'text', text: 'b'.repeat(1_000) }] }
+      }
+      if (exec.name === 'terminal_send') throw new Error(`post failed: ${'o'.repeat(1_000)}`)
+      return next()
+    })
+
+    const denied = await call(ctx, 'terminal_list', {}, agent)
+    expect(denied.isError).toBe(true)
+    expect(Buffer.byteLength(text(denied))).toBeLessThanOrEqual(64)
+    expect(text(denied)).toContain('[output truncated]')
+
+    const replaced = await call(ctx, 'terminal_open', { type: 'stub' }, agent)
+    expect(replaced.isError).toBe(false)
+    expect(Buffer.byteLength(text(replaced))).toBeLessThanOrEqual(64)
+    expect(text(replaced)).toContain('[output truncated]')
+
+    const blocked = await call(ctx, 'terminal_read', { sessionId: 'pty-1' }, agent)
+    expect(blocked.isError).toBe(true)
+    expect(Buffer.byteLength(text(blocked))).toBeLessThanOrEqual(64)
+    expect(text(blocked)).toContain('[output truncated]')
+
+    const failures = [
+      await call(ctx, 'terminal_signal', { sessionId: 'pty-1', signal: 'SIGINT' }, agent),
+      await call(ctx, 'terminal_close', { sessionId: 'pty-1' }, agent),
+      await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'work' }, agent),
+    ]
+    for (const failure of failures) {
+      expect(failure.isError).toBe(true)
+      expect(Buffer.byteLength(text(failure))).toBeLessThanOrEqual(64)
+      expect(text(failure)).toContain('[output truncated]')
+    }
+  })
+
+  it('leaves a structured around-dispatch failure unchanged', async () => {
+    const { ctx, agent } = await setup(false, { maxResultBytes: 64 })
+    ctx.on('tools/execute', async (exec, next) => exec.name === 'terminal_list'
+      ? { content: [], isError: true, error: { message: 'structured failure' } }
+      : next())
+    const result = await call(ctx, 'terminal_list', {}, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([])
+  })
 })
 
 describe('tool-pty task integration', () => {
@@ -305,6 +408,23 @@ describe('tool-pty task integration', () => {
     expect(text(output)).toContain('[status: completed, wait: stdin_read]')
   })
 
+  it('bounds foreground and background results after terminal and task metadata', async () => {
+    const { ctx, agent, stub } = await setup(true, { maxResultBytes: 64 })
+    await call(ctx, 'terminal_open', { type: 'stub' }, agent)
+    stub.sessions[0]!.viewport = '界'.repeat(100)
+    const foreground = await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'foreground' }, agent)
+    expect(Buffer.byteLength(text(foreground))).toBeLessThanOrEqual(64)
+
+    stub.sessions[0]!.delta = '界'.repeat(100)
+    stub.sessions[0]!.deltaTruncated = true
+    await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'background', run_in_background: true }, agent)
+    const background = await call(ctx, 'task_output', { task_id: 'pty-send-1', wait: true }, agent)
+    expect(Buffer.byteLength(text(background))).toBeLessThanOrEqual(64)
+    expect(text(background)).toContain('[status: completed')
+    expect(text(background).match(/\[output truncated\]/g)).toHaveLength(1)
+    expect(text(background)).toContain('[output truncated]\n[status: completed')
+  })
+
   it('rejects pre-aborted background calls, maps task cancellation, and contains operation failure', async () => {
     const { ctx, agent, stub } = await setup(true)
     await call(ctx, 'terminal_open', { type: 'stub' }, agent)

packages/pty/tool-pty/tsconfig.json

@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../util/retention"
+    },
     {
       "path": "../pty"
     },

packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts

@@ -19,7 +19,11 @@ class TestPersistence extends SessionPersistence {
   load(_id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     return Promise.reject(new Error('not used'))
   }
+  inspect(_id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return Promise.reject(new Error('not used'))
+  }
   list(): Promise<SessionHeader[]> { return Promise.resolve([]) }
+  listSnapshots(): Promise<never[]> { return Promise.resolve([]) }
 }
 
 class RecordingAdapter extends LlmAdapter {

packages/session-persistence/session-persistence-jsonl/README.md

@@ -37,7 +37,9 @@ A root belongs to one encoding. Startup discovery and targeted lookup reject the
 - **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s the encoded header and first batch in a temporary file. POSIX publishes it without overwrite via a hard link and `fsync`s the parent directory. Windows publishes it without overwrite via `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` and creates missing directories through the same write-through pattern. A created-but-never-appended session leaves nothing on disk and is absent from `list`.
 - **Append-only.** Flushed events are never rewritten. Subsequent raw batches append lines; compressed batches append one frame. Both paths `fsync`, and a caught write or sync failure rolls the file back to its prior byte length.
 - **Crash recovery — preserve valid tail work.** `load` validates every complete compressed frame and scans their decompressed JSONL. If the last frame is structurally incomplete, the reader keeps its complete decoded records, truncates from that frame's start, and re-encodes those records with the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md). Raw mode truncates from its first incomplete line. A checksum/decompression failure in a complete frame, or a defect at or before the last committed `turn/end`, is corruption and rejects.
+- **Non-mutating inspection.** `inspect()` returns the detached valid prefix without truncating an incomplete tail or closing an interrupted turn, and leaves the lightweight revision unchanged.
 - **Contiguous-seq.** `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type.
+- **Lightweight revisions.** `listSnapshots()` identifies a log by its device, inode, size, and nanosecond timestamps, avoiding a full-log parse while changing after append, repair, replacement, or store changes.
 
 ## Write path
 

packages/session-persistence/session-persistence-jsonl/src/index.ts

@@ -9,12 +9,13 @@
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { readdirSync } from 'node:fs'
-import { open, mkdir, readFile, readdir, link, rm, stat as fsStat, truncate } from 'node:fs/promises'
+import { open, mkdir, readFile, readdir, link, rm, stat, truncate } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { randomBytes } from 'node:crypto'
 import {
-  SessionPersistence, PersistenceCoordinator,
-  type PersistenceBackend, type SessionLocation, type StoredPrefix,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
+  type StoredPrefix,
 } from '@deepseek-ai/dsh-session-persistence'
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
@@ -130,6 +131,10 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     return this.coordinator.load(id)
   }
 
+  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id)
+  }
+
   // One method serves both public `list` and the backend hook; delegating it to
   // the coordinator would call this hook recursively.
 
@@ -243,11 +248,38 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
 
   /** List valid unique stored sessions' metadata (header line only — no full-log parse). */
   async list(): Promise<SessionHeader[]> {
+    return (await this.listArtifacts()).map(artifact => artifact.header)
+  }
+
+  /** List metadata plus a stat-derived identity for each append-only log. */
+  async listSnapshots(): Promise<SessionPersistenceSnapshot[]> {
+    const snapshots: SessionPersistenceSnapshot[] = []
+    for (const artifact of await this.listArtifacts()) {
+      try {
+        const identity = await stat(artifact.path, { bigint: true })
+        snapshots.push({
+          header: artifact.header,
+          revision: SessionPersistenceRevision([
+            identity.dev,
+            identity.ino,
+            identity.size,
+            identity.mtimeNs,
+            identity.ctimeNs,
+          ].join(':')),
+        })
+      } catch (error: unknown) {
+        if (!isENOENT(error)) throw error
+      }
+    }
+    return snapshots
+  }
+
+  private async listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>> {
     await this.ensureRootEncoding()
-    const metas: SessionHeader[] = []
+    const artifacts: Array<{ header: SessionHeader; path: string }> = []
     const ids = new Set<SessionId>()
     for (const dir of await this.listCwdDirs()) {
-      for (const name of await this.listArtifacts(dir)) {
+      for (const name of await this.listArtifactNames(dir)) {
         const path = join(dir, name)
         // Read only headers so listing scales with session count, not log size.
         const first = this.compression === 'zstd'
@@ -261,10 +293,10 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
           throw new Error(`duplicate JSONL session id "${meta.id}" appears in multiple cwd buckets`)
         }
         ids.add(meta.id)
-        metas.push(meta)
+        artifacts.push({ header: meta, path })
       }
     }
-    return metas
+    return artifacts
   }
 
   // --- materialization / append / repair (file mechanics) ---
@@ -564,7 +596,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     }
   }
 
-  private async listArtifacts(dir: string): Promise<string[]> {
+  private async listArtifactNames(dir: string): Promise<string[]> {
     const entries = await readdir(dir)
     const oppositeSuffix = logSuffix(this.oppositeCompression())
     const incompatible = entries.find(name => name.endsWith(oppositeSuffix))
@@ -629,7 +661,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
   private async assertLogParentAllowsAbsence(path: string): Promise<void> {
     try {
       const parent = dirname(path)
-      const info = await fsStat(parent)
+      const info = await stat(parent)
       if (info.isDirectory()) return
       const error = new Error(`ENOTDIR: parent path exists but is not a directory: ${parent}`) as NodeJS.ErrnoException
       error.code = 'ENOTDIR'

packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts

@@ -209,6 +209,62 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     expect(loaded.events).toEqual(log) // chunks preserved, contiguous seqs
   })
 
+  it('source-qualifies revisions across roots while preserving same-log reopen identity', async () => {
+    const m = meta('revision-source')
+    await ctx.sessionPersistence.create(m)
+    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const revision = (await ctx.sessionPersistence.listSnapshots())[0]?.revision
+
+    const reopenedCtx = new Context()
+    await reopenedCtx.plugin(SessionStore)
+    await reopenedCtx.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
+    expect((await reopenedCtx.sessionPersistence.listSnapshots())[0]?.revision).toBe(revision)
+
+    const otherRoot = await freshRoot()
+    const otherCtx = new Context()
+    await otherCtx.plugin(SessionStore)
+    await otherCtx.plugin(SessionPersistenceJsonl, { root: otherRoot, compression: 'none' })
+    await otherCtx.sessionPersistence.create(m)
+    await otherCtx.sessionPersistence.append(m.id, oneTurnLog())
+    expect((await otherCtx.sessionPersistence.listSnapshots())[0]?.revision).not.toBe(revision)
+
+    await reopenedCtx.fiber.dispose()
+    await otherCtx.fiber.dispose()
+  })
+
+  it('omits a snapshot artifact removed after discovery', async () => {
+    const m = meta('vanishing-snapshot')
+    await ctx.sessionPersistence.create(m)
+    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const persistence = ctx.sessionPersistence as unknown as {
+      listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>>
+    }
+    const listArtifacts = persistence.listArtifacts.bind(persistence)
+    const discovery = vi.spyOn(persistence, 'listArtifacts').mockImplementation(async () => {
+      const artifacts = await listArtifacts()
+      await rm(artifacts[0]!.path)
+      return artifacts
+    })
+
+    await expect(ctx.sessionPersistence.listSnapshots()).resolves.toEqual([])
+    discovery.mockRestore()
+  })
+
+  it('surfaces non-ENOENT snapshot stat failures after discovery', async () => {
+    const blocker = join(root, 'snapshot-not-a-directory')
+    await writeFile(blocker, 'x')
+    const persistence = ctx.sessionPersistence as unknown as {
+      listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>>
+    }
+    const discovery = vi.spyOn(persistence, 'listArtifacts').mockResolvedValue([{
+      header: meta('snapshot-stat-failure'),
+      path: join(blocker, 'session.jsonl'),
+    }])
+
+    await expect(ctx.sessionPersistence.listSnapshots()).rejects.toThrow(/ENOTDIR/)
+    discovery.mockRestore()
+  })
+
   it('rejects a stored v0 log containing a legacy request/header-delta event', async () => {
     const m = meta('legacy-header-delta', '/legacy')
     const path = rawLogPath(root, m.cwd, m.id)

packages/session-persistence/session-persistence-sqlite/README.md

@@ -8,7 +8,7 @@ A SQLite durable session-persistence backend — a second `SessionPersistence` i
 
 ## Storage model
 
-Each `SessionEvent` maps 1:1 onto a row in an `events` table `(session_id, seq, type, time, data, source_event_seqs, surface_op)` — `data` is the event payload as JSON text, so the row shape is the event verbatim (including `assistant/chunk`, keeping `seq` contiguous). The two `TEXT` columns `source_event_seqs` and `surface_op` are nullable; they store the event's optional surface-metadata fields (see [session surface](../../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md)). Out-of-log metadata (`SessionHeader`) lives in a `sessions` row. A `sessions` row is written only by the first `append` — its existence is the lazy-materialization signal (`list` reports exactly the sessions that have a row), so no separate column is needed.
+Each `SessionEvent` maps 1:1 onto a row in an `events` table `(session_id, seq, type, time, data, source_event_seqs, surface_op)` — `data` is the event payload as JSON text, so the row shape is the event verbatim (including `assistant/chunk`, keeping `seq` contiguous). The two `TEXT` columns `source_event_seqs` and `surface_op` are nullable; they store the event's optional surface-metadata fields (see [session surface](../../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md)). Out-of-log metadata (`SessionHeader`), a per-materialization incarnation id, and a monotonic per-log revision live in a `sessions` row; a singleton state row carries the immutable store id. A `sessions` row is written only by the first `append` — its existence is the lazy-materialization signal (`list` reports exactly the sessions that have a row).
 
 The repository's Node range supports unflagged `node:sqlite`. The database enables foreign keys and uses the configured journal mode (`wal` by default; use a rollback mode where WAL shared-memory files are unsuitable). `PRAGMA user_version` stores the table-layout version; databases with any other version are rejected because this unreleased format has no migrations.
 
@@ -19,6 +19,8 @@ On filesystems with POSIX modes, the backend requests mode `0700` for missing di
 - **Append = a transaction.** `append` runs `BEGIN`/`COMMIT` around the batch: it materializes the `sessions` row (if still lazy) and INSERTs every event, asserting the contiguous-seq contract first (the first event's `seq` must equal the stored next-seq). A mid-batch failure (a UNIQUE violation on a duplicated seq) rolls back entirely, so the stored log and the in-memory cursor stay consistent. (`load()` already balanced the stored log, so `append` never has to repair a crash tail.)
 - **Lazy materialization.** `create()` records intent in memory only — no row is written until the first `append`. A created-but-never-appended session has no `sessions` row, so it is absent from `list()` (which reports exactly the sessions that have a row).
 - **Interrupted-turn close on load.** `load()` implements the shared [crash-recovery contract](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md): preserve the valid interrupted turn, append its synthetic closing events in one transaction, and remove only a torn tail row. Committed parse errors or sequence gaps make the session unloadable. Because recovery mutates stored rows, the next append starts from a balanced log and accurate cursor.
+- **Non-mutating inspection.** `inspect()` returns the detached valid row prefix without deleting a torn tail row or appending recovery closers, and leaves the lightweight revision unchanged.
+- **Lightweight revisions.** `listSnapshots()` combines the immutable store and database-file identity, a per-materialization incarnation id, and a per-session counter incremented in each mutating transaction. This keeps unchanged observations stable without parsing event rows and distinguishes independent stores and recreated same-id logs.
 
 ## Configuration (schemastery)
 

packages/session-persistence/session-persistence-sqlite/src/index.ts

@@ -8,12 +8,15 @@
 
 import { Context } from 'cordis'
 import z from 'schemastery'
+import { randomUUID } from 'node:crypto'
+import { statSync } from 'node:fs'
 import { DatabaseSync } from 'node:sqlite'
 import { mkdir, open } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import {
-  SessionPersistence, PersistenceCoordinator,
-  type PersistenceBackend, type SessionLocation, type StoredPrefix,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
+  type StoredPrefix,
 } from '@deepseek-ai/dsh-session-persistence'
 import type { SessionEvent, SurfaceEventType, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
@@ -93,6 +96,7 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
   override readonly name = 'session-persistence-sqlite'
 
   private db!: DatabaseSync
+  private storeIdentity!: string
   private ready: Promise<void>
   private coordinator: PersistenceCoordinator<number>
 
@@ -105,13 +109,32 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
   }
 
   private async openDb(path: string, journalMode: JournalMode): Promise<void> {
-    if (path !== ':memory:') {
-      const abs = resolve(path)
-      await mkdir(dirname(abs), { recursive: true, mode: 0o700 })
-      await createDatabaseFile(abs)
-      this.db = openDatabase(abs, journalMode)
-    } else {
-      this.db = openDatabase(path, journalMode)
+    const actual = path === ':memory:' ? path : resolve(path)
+    if (actual !== ':memory:') {
+      await mkdir(dirname(actual), { recursive: true, mode: 0o700 })
+      await createDatabaseFile(actual)
+    }
+    this.db = openDatabase(actual, journalMode)
+    try {
+      const row = this.db.prepare(
+        'SELECT store_id FROM persistence_state WHERE singleton = 1',
+      ).get() as { store_id: string } | undefined
+      /* v8 ignore next -- openDatabase inserts the singleton before returning. */
+      if (row === undefined) {
+        throw new Error(`session database at "${actual}" has no store identity`)
+      }
+      if (row.store_id.length === 0) {
+        throw new Error(`session database at "${actual}" has no valid store identity`)
+      }
+      if (actual !== ':memory:') {
+        const identity = statSync(actual, { bigint: true })
+        this.storeIdentity = `file:${identity.dev}:${identity.ino}:${identity.birthtimeNs}:store:${row.store_id}`
+      } else {
+        this.storeIdentity = `memory:store:${row.store_id}`
+      }
+    } catch (error: unknown) {
+      this.db.close()
+      throw error
     }
   }
 
@@ -134,6 +157,10 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     return this.coordinator.load(id)
   }
 
+  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id)
+  }
+
   // One method serves both public `list` and the backend hook; delegating it to
   // the coordinator would call this hook recursively.
 
@@ -179,6 +206,7 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
         const [surfaceSeqs, surfaceOp] = surfaceBindings(event)
         insertEvent.run(meta.id, event.seq, event.type, event.time, JSON.stringify(event.data), surfaceSeqs, surfaceOp)
       }
+      this.db.prepare('UPDATE sessions SET revision = revision + 1 WHERE id = ?').run(meta.id)
       this.db.exec('COMMIT')
     } catch (error) {
       this.db.exec('ROLLBACK')
@@ -207,6 +235,9 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
           insertEvent.run(meta.id, event.seq, event.type, event.time, JSON.stringify(event.data), surfaceSeqs, surfaceOp)
         }
       }
+      if (tornMarker !== undefined || closers.length > 0) {
+        this.db.prepare('UPDATE sessions SET revision = revision + 1 WHERE id = ?').run(meta.id)
+      }
       this.db.exec('COMMIT')
     } catch (error) {
       // The DELETE+INSERT cannot collide (a row at a closer's seq is preserved or
@@ -228,6 +259,18 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     return rows.map(rowToMeta)
   }
 
+  /** List metadata with a source-qualified monotonic revision per session. */
+  async listSnapshots(): Promise<SessionPersistenceSnapshot[]> {
+    await this.ready
+    const rows = this.db.prepare('SELECT * FROM sessions').all() as unknown as SessionRow[]
+    return rows.map(row => ({
+      header: rowToMeta(row),
+      revision: SessionPersistenceRevision(
+        `${this.storeIdentity}:incarnation:${row.incarnation}:revision:${row.revision}`,
+      ),
+    }))
+  }
+
   /** Close the database handle (awaited by the coordinator's dispose, post-drain). */
   async close(): Promise<void> {
     await this.ready
@@ -248,8 +291,9 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
    */
   private writeRow(meta: SessionHeader): void {
     this.db.prepare(`
-      INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length, delegation_depth)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO sessions
+        (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, incarnation, revision)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)
       ON CONFLICT(id) DO UPDATE SET
         version = excluded.version,
         created_at = excluded.created_at,
@@ -265,6 +309,7 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
       meta.parentSession ?? null,
       meta.seedLength ?? null,
       meta.delegationDepth ?? null,
+      randomUUID(),
     )
   }
 }

packages/session-persistence/session-persistence-sqlite/src/schema.ts

@@ -1,12 +1,14 @@
 /**
  * Schema + load-time helpers for the SQLite session-persistence backend: the
- * DDL (a `sessions` metadata table and a 1:1 `events` row per `SessionEvent`),
- * the database open/configure step, and the last-`turn/end` cut that gives the
- * SQLite backend the SAME crash-tail-on-load semantics as the JSONL backend.
+ * DDL (a store-identity row, `sessions` metadata, and a 1:1 `events` row per
+ * `SessionEvent`), the database open/configure step, and the last-`turn/end`
+ * cut that gives the SQLite backend the SAME crash-tail-on-load semantics as
+ * the JSONL backend.
  *
  * @module dsh-session-persistence-sqlite/schema
  */
 
+import { randomUUID } from 'node:crypto'
 import { DatabaseSync } from 'node:sqlite'
 import type { SessionEvent, SessionId, SessionHeader, SurfaceOp } from '@deepseek-ai/dsh-session'
 
@@ -15,7 +17,7 @@ import type { SessionEvent, SessionId, SessionHeader, SurfaceOp } from '@deepsee
  * layout; orthogonal to a session's own `version` (which versions the EVENT
  * vocabulary, stored per session in the `sessions` row).
  */
-export const SCHEMA_VERSION = 5
+export const SCHEMA_VERSION = 8
 
 /**
  * A row of the `sessions` table — the out-of-log metadata ({@link SessionHeader}).
@@ -31,6 +33,10 @@ export interface SessionRow {
   cwd: string | null
   parent_session: string | null
   seed_length: number | null
+  /** Stable identity assigned when this log is materialized. */
+  incarnation: string
+  /** Monotonic log-change token incremented in each mutating transaction. */
+  revision: number
   delegation_depth: number | null
 }
 
@@ -62,23 +68,41 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
  * rather than being migrated in place.
  * @param path - the SQLite database file to open (created when absent).
  * @param journalMode - validated journal pragma.
- * @returns the open handle with pragmas applied and both tables ensured.
+ * @returns the open handle with pragmas applied and all three tables ensured.
  */
 export function openDatabase(path: string, journalMode: JournalMode): DatabaseSync {
   const db = new DatabaseSync(path)
+  try {
+    configureDatabase(db, path, journalMode)
+    return db
+  } catch (error: unknown) {
+    db.close()
+    throw error
+  }
+}
+
+function configureDatabase(db: DatabaseSync, path: string, journalMode: JournalMode): void {
   db.exec('PRAGMA foreign_keys = ON')
   // The validated union is safe to interpolate into a non-bindable PRAGMA.
   db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
   // `PRAGMA user_version` always returns exactly one row { user_version }.
   const { user_version: onDisk } = db.prepare('PRAGMA user_version').get() as { user_version: number }
   if (onDisk !== 0 && onDisk !== SCHEMA_VERSION) {
-    db.close()
     throw new Error(`session database at "${path}" has schema version ${onDisk}, incompatible with this build (${SCHEMA_VERSION})`)
   }
   if (onDisk === 0) {
     // Stamp fresh or pre-versioning databases.
     db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS persistence_state (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      store_id  TEXT NOT NULL
+    ) STRICT
+  `)
+  db.prepare(
+    'INSERT OR IGNORE INTO persistence_state (singleton, store_id) VALUES (1, ?)',
+  ).run(randomUUID())
   db.exec(`
     CREATE TABLE IF NOT EXISTS sessions (
       id             TEXT PRIMARY KEY,
@@ -87,7 +111,9 @@ export function openDatabase(path: string, journalMode: JournalMode): DatabaseSy
       cwd              TEXT,
       parent_session   TEXT,
       seed_length      INTEGER,
-      delegation_depth INTEGER
+      delegation_depth INTEGER,
+      incarnation      TEXT NOT NULL,
+      revision         INTEGER NOT NULL
     ) STRICT
   `)
   db.exec(`
@@ -102,7 +128,6 @@ export function openDatabase(path: string, journalMode: JournalMode): DatabaseSy
       PRIMARY KEY (session_id, seq)
     ) STRICT
   `)
-  return db
 }
 
 /**

packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { existsSync } from 'node:fs'
-import { chmod, mkdtemp, rm, stat, writeFile } from 'node:fs/promises'
+import { chmod, mkdtemp, rm, stat, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
@@ -155,8 +155,8 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     const path = await freshDbPath()
     const m = meta('legacy-header-delta', '/legacy')
     const db = openDatabase(path, 'wal')
-    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length) VALUES (?, ?, ?, ?, NULL, NULL)')
-      .run(m.id, m.version, m.createdAt, m.cwd ?? null)
+    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, incarnation, revision) VALUES (?, ?, ?, ?, NULL, NULL, NULL, ?, 1)')
+      .run(m.id, m.version, m.createdAt, m.cwd ?? null, 'legacy-header-delta')
     const insert = db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)')
     insert.run(m.id, 0, 'turn/start', 1, JSON.stringify({ turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }))
     insert.run(m.id, 1, 'request/header-delta', 2, JSON.stringify({ config: { model: 'legacy' } }))
@@ -172,8 +172,8 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     const path = await freshDbPath()
     const m = meta('legacy-header-fallback', '/legacy')
     const db = openDatabase(path, 'wal')
-    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length) VALUES (?, ?, ?, ?, NULL, NULL)')
-      .run(m.id, m.version, m.createdAt, m.cwd ?? null)
+    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, incarnation, revision) VALUES (?, ?, ?, ?, NULL, NULL, NULL, ?, 1)')
+      .run(m.id, m.version, m.createdAt, m.cwd ?? null, 'legacy-header-fallback')
     db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)')
       .run(m.id, 0, 'request/header', 1, JSON.stringify({
         header: { config: { model: 'legacy' } },
@@ -294,22 +294,20 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     dbNewer.close()
     expect(() => openDatabase(path, 'wal')).toThrow(/incompatible with this build/)
 
-    // A stale OLDER version (e.g. a pre-summary-drop v1 DB) is also rejected —
-    // we do not migrate (unreleased software, no backward-compat).
+    // The immediately preceding layout lacks the required store identity and is
+    // rejected rather than migrated (unreleased software, no backward-compat).
     const olderPath = await freshDbPath()
     openDatabase(olderPath, 'wal').close()
     const dbOlder = openDatabase(olderPath, 'wal')
-    dbOlder.exec('PRAGMA user_version = 1')
+    dbOlder.exec(`PRAGMA user_version = ${SCHEMA_VERSION - 1}`)
     dbOlder.close()
     expect(() => openDatabase(olderPath, 'wal')).toThrow(/incompatible with this build/)
   })
 
   it('rejects a sibling v3 database (the merge-collided version) rather than opening it against missing columns', async () => {
-    // Two unmerged branches each shipped a DISTINCT layout under user_version 3 (one added only
-    // `seed_length`, the other only the surface columns). The merged v4 cannot interpret that
-    // ambiguous, incomplete layout and must reject it.
+    // Version 3 identified two incompatible sibling layouts, so it is always rejected.
     const path = await freshDbPath()
-    openDatabase(path, 'wal').close() // creates + stamps user_version = SCHEMA_VERSION (4)
+    openDatabase(path, 'wal').close() // creates + stamps user_version = SCHEMA_VERSION
     const db = openDatabase(path, 'wal')
     db.exec('PRAGMA user_version = 3')
     db.close()
@@ -382,12 +380,95 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     await fiber2.dispose()
   })
 
+  it('source-qualifies revisions across stores while preserving same-file reopen identity', async () => {
+    const pathA = await freshDbPath()
+    const pathB = await freshDbPath()
+    const m = meta('revision-source')
+    const a = await backend(pathA)
+    await a.ctx.sessionPersistence.create(m)
+    await a.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const revisionA = (await a.ctx.sessionPersistence.listSnapshots())[0]?.revision
+    await a.dispose()
+
+    const probeA = openDatabase(pathA, 'wal')
+    const storeIdA = (probeA.prepare(
+      'SELECT store_id FROM persistence_state WHERE singleton = 1',
+    ).get() as { store_id: string }).store_id
+    probeA.close()
+
+    const aliasA = `${pathA}.alias`
+    await symlink(pathA, aliasA)
+    const reopenedA = await backend(aliasA)
+    expect((await reopenedA.ctx.sessionPersistence.listSnapshots())[0]?.revision).toBe(revisionA)
+    await reopenedA.dispose()
+
+    const b = await backend(pathB)
+    await b.ctx.sessionPersistence.create(m)
+    await b.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const revisionB = (await b.ctx.sessionPersistence.listSnapshots())[0]?.revision
+    const probeB = openDatabase(pathB, 'wal')
+    const storeIdB = (probeB.prepare(
+      'SELECT store_id FROM persistence_state WHERE singleton = 1',
+    ).get() as { store_id: string }).store_id
+    probeB.close()
+    expect(storeIdB).not.toBe(storeIdA)
+    expect(revisionB).not.toBe(revisionA)
+    expect(String(revisionA)).toMatch(/:revision:1$/)
+    expect(String(revisionB)).toMatch(/:revision:1$/)
+    await b.dispose()
+  })
+
+  it('changes revisions when a deleted session id is materialized again in the same database', async () => {
+    const path = await freshDbPath()
+    const m = meta('recreated-revision')
+    const first = await backend(path)
+    await first.ctx.sessionPersistence.create(m)
+    await first.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const before = (await first.ctx.sessionPersistence.listSnapshots())[0]?.revision
+    await first.dispose()
+
+    const cleanup = openDatabase(path, 'wal')
+    cleanup.prepare('DELETE FROM sessions WHERE id = ?').run(m.id)
+    cleanup.close()
+
+    const second = await backend(path)
+    await second.ctx.sessionPersistence.create(m)
+    await second.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const after = (await second.ctx.sessionPersistence.listSnapshots())[0]?.revision
+    expect(after).not.toBe(before)
+    expect(String(before)).toMatch(/:revision:1$/)
+    expect(String(after)).toMatch(/:revision:1$/)
+    await second.dispose()
+  })
+
   it('exposes the schema version constant', () => {
-    expect(SCHEMA_VERSION).toBe(5)
+    expect(SCHEMA_VERSION).toBe(8)
+  })
+
+  it('keeps the revision stable for an empty repair hook', async () => {
+    const b = await backend()
+    const m = meta('empty-repair')
+    await b.ctx.sessionPersistence.create(m)
+    await b.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const before = await b.ctx.sessionPersistence.listSnapshots()
+    await (b.ctx.sessionPersistence as SessionPersistenceSqlite).commitRepair(m, undefined, [])
+    expect(await b.ctx.sessionPersistence.listSnapshots()).toEqual(before)
+    await b.dispose()
   })
 })
 
 describe('SessionPersistenceSqlite: edge cases', () => {
+  it('rejects and closes a current-schema database with an invalid store identity', async () => {
+    const path = await freshDbPath()
+    const db = openDatabase(path, 'wal')
+    db.exec("UPDATE persistence_state SET store_id = '' WHERE singleton = 1")
+    db.close()
+
+    const b = await backend(path)
+    await expect(b.ctx.sessionPersistence.listSnapshots()).rejects.toThrow(/no valid store identity/)
+    await expect(b.dispose()).resolves.toBeUndefined()
+  })
+
   it('creates a new database and WAL sidecars with owner-only modes without changing its parent mode', async () => {
     if (process.platform === 'win32') return
     const path = await freshDbPath()

packages/session-persistence/session-persistence/README.md

@@ -12,7 +12,9 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 | `create(meta): Promise<void>` | Register a new session's metadata. MAY defer the physical write until the first `append` (lazy materialization). |
 | `append(id, events): Promise<void>` | Durably persist a batch (from the `session/flush` drain). Append-only; first event `seq` == stored next-seq after any repair; rejects non-JSON-serializable data naming the offending type. |
 | `load(id): Promise<{ meta; events }>` | Reload meta + log. Preserves an interrupted (unclosed) final turn and closes it with synthetic closers — an error `tool/result` per unanswered `tool-call`, then `step/end?`+`turn/end {interrupted}` (a turn can be huge — never truncated); only a torn tail fragment is dropped. Events contiguous (`events[i].seq === i`); rejects a committed-region gap/parse error or unknown `version`. |
+| `inspect(id): Promise<{ meta; events }>` | Return a detached valid stored prefix without truncating a torn tail, synthesizing recovery closers, or publishing coordinator state. Serialized with same-id writes; intended for read models and other observers that must never recover a log. |
 | `list(): Promise<SessionHeader[]>` | Lightweight listing from metadata, no full-log parse. A zero-event lazily-materialized session is absent from `list`. |
+| `listSnapshots(): Promise<SessionPersistenceSnapshot[]>` | Lightweight metadata plus an opaque branded per-log revision, without loading event logs. A revision stays equal while that log and its backing store are unchanged, changes after append or mutating load repair, and cannot collide solely because two stores use the same local counter. |
 
 ## Invariants every backend must honor
 
@@ -23,7 +25,7 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 
 ## The write coordinator
 
-`PersistenceCoordinator` owns per-id state, write-behind buffers and serialization, the `session/event` → `session/flush` drain, lazy materialization, crash-tail repair, session adoption, and quiescent disposal. A first-party backend composes one, implements the small `PersistenceBackend` storage hook interface, and delegates its four public service methods. JSONL and SQLite therefore share lifecycle correctness while retaining different storage primitives; see the [coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md).
+`PersistenceCoordinator` owns per-id state, write-behind buffers and serialization, the `session/event` → `session/flush` drain, lazy materialization, crash-tail repair, session adoption, and quiescent disposal. A first-party backend composes one, implements the small `PersistenceBackend` storage hook interface, and delegates its stateful methods. JSONL and SQLite therefore share lifecycle correctness while retaining different storage primitives. Side-effect-free location queries and lightweight snapshot listing remain backend-owned because they describe storage topology and revision identity; see the [coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md).
 
 The coordinator implements durability at checkpoints but does not select their schedule. Persisted deployments explicitly compose [`dsh-session-checkpoint-policy`](../session-checkpoint-policy) when they want request-, tool-dispatch-, and completed-step recovery boundaries; omitting it leaves the loop's coarser checkpoints intact.
 
@@ -36,17 +38,17 @@ The `PersistenceBackend<TornMarker>` hooks (the only seam between the coordinato
 | Hook | Role |
 |---|---|
 | `name` | Backend label for the dispose-failure `AggregateError`. |
-| `loadStored(id)` | Read a stored prefix by id across every storage scope. Used by resume/load, live adoption, and the create-collision probe. Returned metadata identifies `id`; an opaque `tornMarker` is present iff a torn tail must be truncated. |
+| `loadStored(id)` | Read a stored prefix by id across every storage scope. Used by resume/load, non-mutating inspect, live adoption, and the create-collision probe. Returned metadata identifies `id`; an opaque `tornMarker` is present iff a torn tail must be truncated. |
 | `appendBatch(meta, events, isMaterialized)` | Durably append a contiguous batch, lazily materializing ATOMICALLY when not yet materialized. |
 | `commitRepair(meta, tornMarker, closers)` | Make a crash repair durable: truncate the torn tail (iff `tornMarker !== undefined` — a marker may be falsy, e.g. seq/offset `0`) and append `closers`. NOT required to be atomic. Used by load (truncate + closers) and live-adoption (truncate only). |
 | `list()` | List all stored metadata. |
 | `close?()` | Optional lifecycle teardown (e.g. close a db handle), awaited after the dispose drain. |
 
-The coordinator asserts the stored id and compares stored/live cwd before repair or live adoption. The `tornMarker` is fully OPAQUE: the coordinator only tests `!== undefined` and round-trips it to `commitRepair`, never inspecting its value (the JSONL backend uses the byte offset to truncate to, the SQLite backend the seq to delete from). The public `SessionPersistence` service shape is unchanged, so a third-party backend MAY still implement the abstract service directly without the coordinator. See [the write-coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md).
+The coordinator asserts the stored id and compares stored/live cwd before repair or live adoption. Its `inspect()` path validates and clones the prefix without calling `commitRepair` or publishing write state. The `tornMarker` is fully OPAQUE: the coordinator only tests `!== undefined` and round-trips it to `commitRepair`, never inspecting its value (the JSONL backend uses the byte offset to truncate to, the SQLite backend the seq to delete from). A third-party backend MAY implement the abstract service directly without the coordinator, but it must provide the same non-mutating inspection and trustworthy lightweight snapshot revisions. See [the write-coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md).
 
 ## Testing backends
 
-Import `runPersistenceContract` from `tests/contract.ts` (the public-API contract) and `runCoordinatorContract` from `tests/coordinator-contract.ts` (the shared write-path orchestration: adoption, HMR, collision, dispose-drain, crash-tail repair) and call each with a fixture for your backend. Every backend is held to the same append-only / contiguous-seq / lazy-materialization / serializability semantics AND the same orchestration, so a backend's own spec is left with only storage-mechanics tests (path sanitization, fsync rollback; schema version, transaction rollback) on top.
+Import `runPersistenceContract` from `tests/contract.ts` (the public API, including stable/change-sensitive lightweight revisions) and `runCoordinatorContract` from `tests/coordinator-contract.ts` (the shared write-path orchestration: adoption, HMR, collision, dispose-drain, crash-tail repair) and call each with a fixture for your backend. Every backend is held to the same append-only / contiguous-seq / lazy-materialization / serializability semantics AND the same orchestration, so a backend's own spec is left with only storage-mechanics tests (path sanitization, fsync rollback; schema version, transaction rollback) on top.
 
 Three backends run these suites: an in-memory reference (in `tests/`), `dsh-session-persistence-jsonl` (append-only file log) and `dsh-session-persistence-sqlite` (`node:sqlite`, each `SessionEvent` one row `(session_id, seq, type, time, data, source_event_seqs, surface_op)`). All passing the same contract + coordinator suite is the proof that the seam is genuinely backend-agnostic — lazy materialization, crash-tail-on-load, and contiguous-seq hold identically over file bytes and over a transactional store.
 

packages/session-persistence/session-persistence/package.json

@@ -27,11 +27,13 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",

packages/session-persistence/session-persistence/src/coordinator.ts

@@ -132,7 +132,7 @@ function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId):
 /**
  * Owns the backend-agnostic session write-path orchestration. A backend
  * constructs one (`new PersistenceCoordinator(ctx, this)`), implements
- * {@link PersistenceBackend}, and delegates its four public service methods to
+ * {@link PersistenceBackend}, and delegates its write/read service methods to
  * the matching coordinator methods.
  *
  * All per-id operations are serialized (a per-id promise chain) so concurrent
@@ -252,6 +252,28 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     return this.serialize(id, () => this.loadCore(id))
   }
 
+  /**
+   * Read a detached valid stored prefix without recovery mutations or
+   * coordinator-state publication.
+   * @param id - persisted session to inspect.
+   * @returns stored header and events before any synthetic recovery closers.
+   */
+  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.serialize(id, () => this.inspectCore(id))
+  }
+
+  private async inspectCore(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    const stored = await this.backend.loadStored(id)
+    if (stored === undefined) throw new Error(`session "${id}" not found`)
+    this.assertStoredId(id, stored.meta)
+    this.assertVersion(stored.meta)
+    assertSupportedEvents(stored.events, id)
+    return {
+      meta: structuredClone(stored.meta),
+      events: structuredClone(stored.events),
+    }
+  }
+
   private async loadCore(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     const stored = await this.backend.loadStored(id)
     if (stored === undefined) throw new Error(`session "${id}" not found`)

packages/session-persistence/session-persistence/src/index.ts

@@ -7,9 +7,19 @@
 
 import { Context, Service } from 'cordis'
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
+import type { SessionPersistenceRevision } from './revision.ts'
 
 // Re-export the metadata vocabulary so consumers import it from the seam.
 export type { SessionHeader } from '@deepseek-ai/dsh-session'
+export { SessionPersistenceRevision } from './revision.ts'
+
+/** Lightweight immutable source identity returned without loading a full log. */
+export interface SessionPersistenceSnapshot {
+  /** Detached metadata for one materialized session. */
+  header: SessionHeader
+  /** Opaque source-qualified token that changes whenever this stored log changes. */
+  revision: SessionPersistenceRevision
+}
 
 // The backend-agnostic write-path orchestration first-party backends compose.
 export { PersistenceCoordinator } from './coordinator.ts'
@@ -83,11 +93,32 @@ export abstract class SessionPersistence extends Service {
    */
   abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
 
+  /**
+   * Inspect a header and its valid contiguous stored prefix without repairing
+   * a torn tail, closing an interrupted turn, or publishing coordinator state.
+   * This read is serialized with writes for the same id and returns detached
+   * values, so observers cannot mutate backend-owned state.
+   * @param id - the persisted session to inspect.
+   * @returns the header and valid stored event prefix exactly as observed.
+   */
+  abstract inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
   /**
    * Lightweight listing from metadata, without a full-log parse.
    * @returns one header per materialized session.
    */
   abstract list(): Promise<SessionHeader[]>
+
+  /**
+   * List materialized sessions with cheap per-log change tokens.
+   *
+   * Repeated observations of an unchanged log return the same revision. A
+   * successful mutating {@link load} repair changes the next listed revision.
+   * Revisions also distinguish independently backed stores so backend-local
+   * counters cannot compare equal across different persistence sources.
+   * @returns one header and opaque revision per materialized session without loading full logs.
+   */
+  abstract listSnapshots(): Promise<SessionPersistenceSnapshot[]>
 }
 
 export default SessionPersistence

packages/session-persistence/session-persistence/src/revision.ts

@@ -0,0 +1,18 @@
+/** Opaque revision identity for lightweight persistence observations. */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/**
+ * Backend-owned token that identifies both one storage source and one revision
+ * of a persisted session log.
+ */
+export type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
+
+/**
+ * Brand a backend revision for the provider-neutral persistence contract.
+ * @param value - backend-owned opaque revision representation.
+ * @returns the same runtime string with persistence-revision identity.
+ */
+export function SessionPersistenceRevision(value: string): SessionPersistenceRevision {
+  return value as SessionPersistenceRevision
+}

packages/session-persistence/session-persistence/tests/contract.ts

@@ -96,11 +96,25 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
           { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } },
         ])
+        const beforeRepair = (await persistence.listSnapshots())
+          .find(snapshot => snapshot.header.id === m.id)?.revision
+
+        const inspected = await persistence.inspect(m.id)
+        const afterInspect = (await persistence.listSnapshots())
+          .find(snapshot => snapshot.header.id === m.id)?.revision
+        expect(afterInspect).toBe(beforeRepair)
+        expect(inspected.events.map(e => e.type)).toEqual([
+          'turn/start', 'user/message', 'step/start', 'assistant/message', 'step/end', 'turn/end',
+          'turn/start', 'step/start',
+        ])
 
         // load PRESERVES the interrupted turn's events (a turn can be huge — they
         // must not be truncated) and closes the orphaned turn with synthetic
         // boundary events: step/end (the step was open) then turn/end {interrupted}.
         const loaded = await persistence.load(m.id)
+        const afterRepair = (await persistence.listSnapshots())
+          .find(snapshot => snapshot.header.id === m.id)?.revision
+        expect(afterRepair).not.toBe(beforeRepair)
         expect(loaded.events.map(e => e.type)).toEqual([
           'turn/start', 'user/message', 'step/start', 'assistant/message', 'step/end', 'turn/end', // turn 1
           'turn/start', 'step/start', 'step/end', 'turn/end', // turn 2: real events + synthetic closers
@@ -201,18 +215,33 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
       try {
         await persistence.create(meta('empty'))
         expect((await persistence.list()).map(m => m.id)).not.toContain(SessionId('empty'))
+        expect((await persistence.listSnapshots()).map(snapshot => snapshot.header.id))
+          .not.toContain(SessionId('empty'))
       } finally {
         await dispose()
       }
     })
 
-    it('list() includes a session once it has events', async () => {
+    it('lists stable lightweight revisions that change after an append', async () => {
       const { persistence, dispose } = await make()
       try {
         const m = meta('s2')
         await persistence.create(m)
         await persistence.append(m.id, oneTurnLog())
         expect((await persistence.list()).map(x => x.id)).toContain(m.id)
+        const first = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
+        const repeated = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
+        expect(first).toBeDefined()
+        expect(repeated?.revision).toBe(first?.revision)
+
+        await persistence.append(m.id, [{
+          type: 'turn/start',
+          seq: 6,
+          time: 7,
+          data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } },
+        }])
+        const changed = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
+        expect(changed?.revision).not.toBe(first?.revision)
       } finally {
         await dispose()
       }

packages/session-persistence/session-persistence/tests/coordinator-contract.ts

@@ -643,11 +643,12 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
-    it('load rejects a missing session', async () => {
+    it('load and inspect reject a missing session', async () => {
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
         await expect(ctx.sessionPersistence.load(SessionId('nope'))).rejects.toThrow(/not found/)
+        await expect(ctx.sessionPersistence.inspect(SessionId('nope'))).rejects.toThrow(/not found/)
       } finally {
         await fiber.dispose()
         await fix.cleanup()

packages/session-persistence/session-persistence/tests/persistence.spec.ts

@@ -3,8 +3,8 @@ import { Context } from 'cordis'
 import SessionStore, { SessionId, isJsonValue } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
-  SessionPersistence, PersistenceCoordinator,
-  type PersistenceBackend, type StoredPrefix,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  type PersistenceBackend, type SessionPersistenceSnapshot, type StoredPrefix,
 } from '../src/index.ts'
 import { runPersistenceContract, meta, oneTurnLog } from './contract.ts'
 import { runCoordinatorContract, type CoordinatorFixture } from './coordinator-contract.ts'
@@ -96,6 +96,10 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     return this.coordinator.load(id)
   }
 
+  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id)
+  }
+
   // --- PersistenceBackend hooks (the Map storage primitives) ---
 
   // A Map-backed store has no torn tails, so `tornMarker` is never set.
@@ -133,6 +137,13 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
   async list(): Promise<SessionHeader[]> {
     return [...this.store.values()].map(e => structuredClone(e.meta))
   }
+
+  async listSnapshots(): Promise<SessionPersistenceSnapshot[]> {
+    return [...this.store.values()].map(entry => ({
+      header: structuredClone(entry.meta),
+      revision: SessionPersistenceRevision(`events:${entry.events.length}`),
+    }))
+  }
 }
 
 /** Controllable storage primitive for serialization and retirement failure tests. */

packages/session-persistence/session-persistence/tsconfig.json

@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../util/brand"
+    },
     {
       "path": "../../core/session"
     },

packages/session-query/README.md

@@ -1,9 +1,10 @@
 # session-query/ — session retrieval capability family
 
-Trusted exact reads and relationship traces over live and durable session logs. The family contains one interface package that owns `ctx.sessionQuery`, logical-corpus precedence, title folding, surface classification, bounded event reads, lineage, and direct event relationships.
+Trusted exact reads, relationship traces, provider-independent semantic filtering, and SQLite full-text search over live and durable session logs.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`session-query/`](session-query/README.md) | Logical-corpus title, event, lineage, and relationship reads | `ctx.sessionQuery` |
+| [`session-query/`](session-query/README.md) | Combined service contract with concrete logical-corpus reads, traces, and semantic filters plus abstract full-text methods | `ctx.sessionQuery` |
+| [`session-query-sqlite/`](session-query-sqlite/README.md) | Concrete service backend with SQLite FTS5 persistent bases and live overlays | `ctx.sessionQuery` |
 
-The family is independent of compaction: it reads canonical lineage, surface operations, and logged provenance but does not participate in compaction policy or execution. Full-text search remains a proposed SQLite package rather than a speculative provider seam in this interface package.
+The family is independent of compaction: it reads canonical lineage, surface operations, logged provenance, and semantic event text but does not participate in compaction policy or execution. One abstract service combines every query operation, and one concrete backend owns the full-text lifecycle without a provider registry or coordinator.

packages/session-query/session-query-sqlite/README.md

@@ -0,0 +1,51 @@
+# @deepseek-ai/dsh-session-query-sqlite
+
+Concrete `ctx.sessionQuery` backend. `SessionQuerySqlite` inherits exact reads, traces, and provider-independent filters from the interface package and implements its two full-text methods with SQLite FTS5. Search uses the live-preferred logical session corpus and groups cross-session results by their strongest event.
+
+## Search contract
+
+`searchSessions(request, exec?)` returns `SessionSearchHit` pages across the corpus; `searchEvents(request, exec?)` returns `SessionEventSearchHit` pages within one session. Queries are required, trimmed, whitespace-normalized literal phrases. FTS5 syntax such as quotes, `OR`, `NEAR`, and `*` is treated as data rather than executable MATCH syntax. Metadata filters are parameterized SQL predicates applied before ranking. To keep SQLite FTS5 MATCH in a supported outer-predicate context, cross-session requests may compile at most 14 combined session and event filter predicates; within-session requests may compile at most 13 filter predicates because the fixed target-session predicate consumes one slot. Each range endpoint compiles as one predicate. A request exceeding either predicate budget or SQLite's portable limit of 32,766 total bindings, including fixed query and pagination values, fails with `SESSION_QUERY_INVALID_FILTER` before statement preparation.
+
+Relevance is source-comparable across persistent and TEMP tables: actual FTS5 highlighted-match span count descending, then stored document code-point length ascending. Event time, session id where applicable, and seq break remaining ties. Cross-session results expose the selected event as `bestMatch`; both scopes derive whitespace-normalized plain text from FTS5 highlight positions and bound it in Unicode code points. Cursors are opaque branded values, bind to the normalized request and service instance, and fail when the relevant generation changes. A within-session cursor survives unrelated-session changes; a cross-session cursor does not.
+
+All three surfaces (`current`, `shadowed`, and `log-only`) are searchable by default. Pass a surface filter to narrow them.
+
+## Source and index lifecycle
+
+The service requires `ctx.sessions` and observes optional `ctx.sessionPersistence` dynamically. One serialized state machine compares source-qualified lightweight durable snapshot revisions, non-mutatingly inspects only new or changed logs, extracts shared semantic documents, reconciles changes transactionally, and runs the query. Session queries never invoke the persistence backend's crash-repairing `load()`; an owner attaching during inspection cannot mutate its log, and the stable-observation retry makes the result live-preferred. The TEMP live row still records persisted availability, and the durable base refreshes after that live owner detaches. Repeated queries and an unchanged same-store reopen perform no full durable-log inspection; switching stores, or observing new, changed, deleted, or externally load-repaired sources, reconciles on the next stable observation. Source or transaction failure commits nothing, and the next search retries.
+
+Persisted FTS rows live in a dedicated derived database. Connection-local TEMP tables hold live rows, which shadow the durable base for the same session and reveal it when the live owner disappears. Unmounting persistence hides durable rows without discarding the cache; remounting reconciles it. Closing or reopening the database drops every live overlay while retaining persisted rows.
+
+The database is disposable but reset is guarded: every recognized schema version rejects unknown user tables before mutating journal mode, and only a recognized incompatible schema containing derived tables rebuilds in place. An unrelated or canonical database is refused. Never point `path` at the session-persistence database. On filesystems with POSIX modes, missing directories and databases are created owner-only (`0700` and `0600` before the process umask), and SQLite sidecars inherit the database mode; existing modes are preserved. Exactly one service in one process owns a derived-index path; external writers or a second process are unsupported because generations and TEMP shadow state are connection-owned.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `path` | required | Dedicated derived-index SQLite path; `:memory:` is supported. Missing filesystem paths are created owner-only on POSIX filesystems. |
+| `journalMode` | `wal` | `wal`, `delete`, `truncate`, or `persist`. |
+| `defaultLimit` | `20` | Page size when a request omits `limit`; at most `Number.MAX_SAFE_INTEGER - 1`. |
+| `maxLimit` | `100` | Largest accepted request page size; at most `Number.MAX_SAFE_INTEGER - 1`. |
+| `snippetChars` | `240` | Maximum snippet length in Unicode code points. |
+| `readWindowMax` | `50` | Maximum `before` or `after` raw-event count for inherited `readEvent()`. |
+
+## Tokenizer and limits
+
+The index uses FTS5 `unicode61`. In the implementation experiment it supported the two-character query `AI` and produced an index about 2.1× smaller than the trigram alternative. The trade-off is token/phrase recall rather than arbitrary substring recall: `AI` does not match the token `BRAID`. Use `ctx.sessionQuery.filterEvents()` with a `text` clause when a literal whitespace-flexible substring scan is required. NUL is rejected in queries; reserved highlight markers and NUL in documents are normalized before indexing so presentation markers cannot collide with source text.
+
+Abort signals stop queued work and caller waits around asynchronous source observation. Node's synchronous `DatabaseSync` API cannot interrupt a MATCH statement already executing on the JavaScript thread; the signal is checked immediately before and after the serialized observation/reconciliation boundary.
+
+## Model Experience
+
+None, as this trusted search backend returns hits only to callers and registers no model-facing prompt, schema, tool, or message.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No caller authorization** — this is a trusted context-wide service; a model tool or UI must enforce its own access policy.
+- **Synchronous query execution** — `DatabaseSync` blocks the JavaScript thread during MATCH execution and cannot interrupt a statement already running.
+- **Token recall, not arbitrary substrings** — the `unicode61` tokenizer does not match substrings inside a larger token; use `filterEvents()` for literal scans.
+- **Single-owner derived index** — one service in one process must own each index path; external writers and multi-process sharing are unsupported.

packages/session-query/session-query-sqlite/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-session-query-sqlite",
+  "description": "Concrete ctx.sessionQuery backend with SQLite FTS5 search",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
+    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}