fix(session): harden cross-session references

.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-21-cross-session-references.md: fa167f639abd9bab4a443088dd770d59f2ad1780
-2026-07-21-cross-session-references.zh.md: e3a93db0865041f6026b4e6b8e9a8bd85537959f
+2026-07-21-cross-session-references.md: aa02b5657634dca5b8c108b5c923feeed83d7de5
+2026-07-21-cross-session-references.zh.md: 21f40f35ed2693ec0e9761173b6985c18db18500

.agents/notes/implemented/feature/2026-07-21-cross-session-references.md

@@ -18,7 +18,7 @@ The service uses `ctx.sessionQuery.readSurface(sessionId)`, which loads one live
 
 ## Snapshot and projection
 
-Preparation deduplicates in first-appearance order, rejects the target id, enforces at most three references by default, and performs all reads in parallel. It returns no partially prepared context: any read, cancellation, validation, or budget error rejects the operation before `send()` or `steer()`. A source is read before enqueue, so later source messages, compaction, deletion, or persistence replacement cannot change the target session.
+Preparation deduplicates in first-appearance order, rejects the target id, enforces at most three references by default, and performs all reads in parallel. It returns no partially prepared context: any read, cancellation, validation, or budget error rejects the operation before `send()` or `steer()`. Cancellation races in-flight discovery and exact reads, so a host settles promptly even when a persistence backend cannot interrupt its pending operation; any late backend settlement is observed but cannot enqueue the message. A source is read before enqueue, so later source messages, compaction, deletion, or persistence replacement cannot change the target session.
 
 Projection retains direct-user messages and steering, completed assistant text, and checkpoint user messages carrying the canonical source exported by `dsh-compact`. That marker is part of the compaction capability contract rather than a backend package name. Projection excludes shadowed pre-compaction nodes, tools and results, reasoning, injected context, other plugin user messages, log-only records, and incomplete assistant chunks. Repeated compaction therefore exposes only the latest folded checkpoint lineage still on the current surface plus its retained tail; there is no raw/current switch and no shadow recovery.
 
@@ -26,13 +26,13 @@ One aggregated context is serialized as JSON beneath a fixed untrusted-backgroun
 
 ## Message ownership
 
-`send()` and `steer()` snapshot content, resolved source, and contexts together as one deeply frozen lossless-JSON inbox record. A claimed ordinary message exposes its attached contexts as the default `agent/prompt-submit` additional contexts; a block writes neither user message nor contexts. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream content and contexts unless it intentionally replaces them. Drained steering bypasses `agent/prompt-submit` and writes `steering/message` before its contexts. Late steering retains the same record when converted to queued input, while cancellation, disposal, and terminal discard drop message and contexts together. `agent/queued` reports the frozen contexts so the observation event describes the complete retained item.
+`send()` and `steer()` snapshot content, resolved source, and contexts together as one deeply frozen lossless-JSON inbox record. Synthetic `inject()` accepts source and model-hidden metadata but not attached contexts, which belong to inbox messages. A claimed ordinary message exposes its attached contexts as the default `agent/prompt-submit` additional contexts; a block writes neither user message nor contexts. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream content and contexts unless it intentionally replaces them. Drained steering bypasses `agent/prompt-submit` and writes `steering/message` before its contexts. Late steering retains the same record when converted to queued input, while cancellation, disposal, and terminal discard drop message and contexts together. `agent/queued` reports the frozen contexts so the observation event describes the complete retained item.
 
 This preserves host driving semantics: TUI decides `send()` versus `steer()` from the agent state after preparation, so only its queued path dispatches UserPromptSubmit hooks; ACP continues to call `send()` once per `session/prompt`. Reference preparation is not a new steering protocol and does not create a turn by itself.
 
 ## Host adapters
 
-TUI combines session candidates with the existing `@` file provider. It prepares only submissions containing structured mentions, disables duplicate submit while awaiting snapshots, restores failed input, and renders persisted session-reference context as a compact source list instead of exposing the complete JSON in the terminal.
+TUI combines session candidates with the existing `@` file provider. Candidate lookup follows the editor's cancellation signal, and session id, cwd, and mention labels escape external terminal controls while the canonical URI retains the original id. TUI prepares only submissions containing structured mentions, disables duplicate submit while awaiting snapshots, restores failed input, and renders persisted session-reference context as a compact source list instead of exposing the complete JSON in the terminal.
 
 ACP extracts `dsh-session:` resource links and canonical inline mentions while preserving ordinary resource-link rendering. A valid reference without the optional service returns a capability-unavailable RPC error, and preparation failure occurs before the in-flight turn slot and agent send. A preparation-specific abort owner makes `session/cancel` and bridge teardown stop pending reads. Picker UI remains an ACP client responsibility.
 
@@ -51,8 +51,8 @@ The defaults cap one serialized reference at 65,536 UTF-8 bytes and the complete
 
 ## Verification
 
-Unit and integration coverage pins URI round-trips and text-boundary punctuation, explicit malformed references, candidate ranking, projection exclusions, backend-independent compact checkpoints, tag-safe framing, deduplication, self-reference, count limits, all-or-nothing reads, cancellation, byte retention, frozen message ownership, prompt blocking, send/steer ordering, missing capability, ordinary ACP resource links, and compact TUI rendering. A keyless TUI snapshot runs the real agent loop: the source surface replaces old user/assistant history with a compact checkpoint, the target submits a mention, and the captured model request contains the checkpoint and retained tail but not either shadowed string.
+Unit and integration coverage pins URI round-trips and text-boundary punctuation, explicit malformed references, candidate ranking, terminal-control escaping, projection exclusions, backend-independent compact checkpoints, tag-safe framing, deduplication, self-reference, count limits, all-or-nothing reads, prompt cancellation against a non-settling storage read, byte retention, frozen message ownership, prompt blocking, send/steer ordering, missing capability, ordinary ACP resource links, and compact TUI rendering. A keyless TUI snapshot runs the real agent loop: the source surface replaces old user/assistant history with a compact checkpoint, the target submits a mention, and the captured model request contains the checkpoint and retained tail but not either shadowed string.
 
 ## Consequences
 
-The new plugin is the stable semantic boundary and adds no persistence schema, event type, FTS dependency, source subscription, or compact shadow access. Standard TUI/ACP demo bundles mount it explicitly; custom hosts remain unchanged until they mount the service and adapt their input. Reference contexts increase target history size within configured bounds and can later be summarized by ordinary target compaction, after which the source session is irrelevant.
+The new plugin is the stable semantic boundary and adds no persistence schema, event type, FTS dependency, source subscription, or compact shadow access. Standard TUI/ACP demo bundles mount it explicitly and expose its count and byte budgets in their own config; custom hosts remain unchanged until they mount the service and adapt their input. Reference contexts increase target history size within configured bounds and can later be summarized by ordinary target compaction, after which the source session is irrelevant.

.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md

@@ -18,7 +18,7 @@ TUI 与 ACP（Agent Client Protocol）用户需要把另一场对话中的相关
 
 ## 快照与投影
 
-准备过程按首次出现的顺序去重、拒绝目标会话自身的 id，并且默认最多允许三个引用，所有读取均并行执行。该过程不会返回部分完成的上下文：任何读取、取消、校验或预算错误都会在调用 `send()` 或 `steer()` 前拒绝本次操作。源会话在入队前完成读取，因此源会话后续新增消息、执行压缩、被删除或替换持久化内容，都无法改变目标会话中的快照。
+准备过程按首次出现的顺序去重、拒绝目标会话自身的 id，并且默认最多允许三个引用，所有读取均并行执行。该过程不会返回部分完成的上下文：任何读取、取消、校验或预算错误都会在调用 `send()` 或 `steer()` 前拒绝本次操作。取消会与进行中的候选发现和精确读取竞速，因此即使持久化后端无法中断待处理操作，宿主也能及时结束等待；后端迟到的完成结果仍会被观察，但不能让消息入队。源会话在入队前完成读取，因此源会话后续新增消息、执行压缩、被删除或替换持久化内容，都无法改变目标会话中的快照。
 
 投影会保留直接用户消息与 steering（中途引导）、已完成的 assistant 文本，以及携带由 `dsh-compact` 导出的规范来源标记的检查点用户消息。该标记属于压缩功能契约的一部分，而非某个后端包名称。投影会排除压缩前已被遮蔽的节点、工具及其结果、推理（reasoning）、注入的上下文、其他插件用户消息、仅用于日志的记录，以及尚未完成的 assistant 分片。因此，重复压缩只会暴露当前表层仍保留的最新折叠检查点谱系及其尾部消息；系统不提供 raw/current 开关，也不恢复被遮蔽的内容。
 
@@ -26,13 +26,13 @@ TUI 与 ACP（Agent Client Protocol）用户需要把另一场对话中的相关
 
 ## 消息所有权
 
-`send()` 与 `steer()` 会把内容、解析后的来源和上下文一起快照为一条深度冻结、无损 JSON 的收件箱记录。普通消息被认领后，其附带的上下文会作为 `agent/prompt-submit` 的默认附加上下文公开；提示词被阻止时，系统既不写入用户消息，也不写入上下文。waterfall（瀑布式事件）返回的 allow 结果具有最终权威性，因此监听器包装 `next()` 时会保留下游内容与上下文，除非它有意替换这些值。排空 steering 消息时会绕过 `agent/prompt-submit`，先写入 `steering/message`，再写入其上下文。延迟到达的 steering 转换为排队输入时保留同一条记录；取消、dispose（资源释放）和到达终止态后的丢弃则会同时丢弃消息与上下文。`agent/queued` 会报告已冻结的上下文，使观察事件能够描述完整的保留项。
+`send()` 与 `steer()` 会把内容、解析后的来源和上下文一起快照为一条深度冻结、无损 JSON 的收件箱记录。合成的 `inject()` 接受来源和模型不可见的元数据，但不接受附加上下文，因为上下文属于收件箱消息。普通消息被认领后，其附带的上下文会作为 `agent/prompt-submit` 的默认附加上下文公开；提示词被阻止时，系统既不写入用户消息，也不写入上下文。waterfall（瀑布式事件）返回的 allow 结果具有最终权威性，因此监听器包装 `next()` 时会保留下游内容与上下文，除非它有意替换这些值。排空 steering 消息时会绕过 `agent/prompt-submit`，先写入 `steering/message`，再写入其上下文。延迟到达的 steering 转换为排队输入时保留同一条记录；取消、dispose（资源释放）和到达终止态后的丢弃则会同时丢弃消息与上下文。`agent/queued` 会报告已冻结的上下文，使观察事件能够描述完整的保留项。
 
 这保留了宿主的驱动语义：TUI 在准备完成后根据 agent 状态决定调用 `send()` 还是 `steer()`，因此只有它的排队路径才会分派 UserPromptSubmit 钩子；ACP 则继续调用 `send()`，每个 `session/prompt` 调用一次。引用准备过程不是新的 steering 协议，本身也不会创建轮次。
 
 ## 宿主适配器
 
-TUI 把会话候选与现有 `@` 文件提供方组合在一起。它只准备包含结构化提及标记的提交；等待快照时禁用重复提交；失败时恢复输入；渲染持久化的会话引用上下文时只显示精简的来源列表，不在终端中暴露完整 JSON。
+TUI 把会话候选与现有 `@` 文件提供方组合在一起。候选查询遵循编辑器的取消信号；session id、cwd 和提及标签中的外部终端控制字符会被转义，但规范 URI 仍保留原始 id。TUI 只准备包含结构化提及标记的提交；等待快照时禁用重复提交；失败时恢复输入；渲染持久化的会话引用上下文时只显示精简的来源列表，不在终端中暴露完整 JSON。
 
 ACP 提取 `dsh-session:` 资源链接和规范的行内提及标记，同时保留普通资源链接的渲染方式。若引用有效但可选服务未挂载，系统会返回「功能不可用」RPC 错误；准备失败会发生在占用进行中轮次槽位并调用 agent send 之前。引用准备过程单独拥有中止控制权，因此 `session/cancel` 和桥接释放都能停止待处理的读取。选择器 UI 仍由 ACP 客户端负责。
 
@@ -51,8 +51,8 @@ ACP 提取 `dsh-session:` 资源链接和规范的行内提及标记，同时保
 
 ## 验证
 
-单元与集成测试覆盖 URI 无损往返与文本边界标点、显式格式错误的引用、候选排序、投影排除规则、与后端无关的压缩检查点、标签安全封套、去重、自引用、数量限制、读取的全有或全无、取消、字节保留、冻结的消息所有权、提示词阻止、send／steer 顺序、功能缺失、普通 ACP 资源链接，以及 TUI 精简渲染。无密钥 TUI 快照会运行真实的 agent loop（智能体循环）：源表层用一个压缩检查点替换旧的用户／assistant 历史，目标会话提交一个提及标记，捕获到的模型请求包含该检查点和保留的尾部消息，但不包含任一被遮蔽的字符串。
+单元与集成测试覆盖 URI 无损往返与文本边界标点、显式格式错误的引用、候选排序、终端控制字符转义、投影排除规则、与后端无关的压缩检查点、标签安全封套、去重、自引用、数量限制、读取的全有或全无、存储读取不结束时取消提示词、字节保留、冻结的消息所有权、提示词阻止、send／steer 顺序、功能缺失、普通 ACP 资源链接，以及 TUI 精简渲染。无密钥 TUI 快照会运行真实的 agent loop（智能体循环）：源表层用一个压缩检查点替换旧的用户／assistant 历史，目标会话提交一个提及标记，捕获到的模型请求包含该检查点和保留的尾部消息，但不包含任一被遮蔽的字符串。
 
 ## 后果
 
-新插件构成稳定的语义边界，不会新增持久化 schema、事件类型、FTS 依赖、源会话订阅或对压缩所遮蔽内容的访问。标准 TUI／ACP 演示组合包会显式挂载它；自定义宿主在挂载该服务并适配输入前保持不变。引用上下文会在配置的界限内增大目标历史，随后可由目标会话的普通压缩进行摘要；完成压缩后，源会话便不再相关。
+新插件构成稳定的语义边界，不会新增持久化 schema、事件类型、FTS 依赖、源会话订阅或对压缩所遮蔽内容的访问。标准 TUI／ACP 演示组合包会显式挂载它，并在各自的配置中暴露引用数量和字节预算；自定义宿主在挂载该服务并适配输入前保持不变。引用上下文会在配置的界限内增大目标历史，随后可由目标会话的普通压缩进行摘要；完成压缩后，源会话便不再相关。

docs/config-catalog.md

@@ -60,6 +60,8 @@ export interface Config {
   persistenceRoot?: string
   /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
   persistenceCompression?: JsonlCompression
+  /** Cross-session reference discovery and snapshot byte budgets. */
+  sessionReferences?: SessionReferenceConfig
   /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
   workspaceContext: agentCore.Config['workspaceContext']
   /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
@@ -75,7 +77,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`SessionReferenceConfig`](#deepseek-aidsh-session-reference) · [`ToolsConfig`](#deepseek-aidsh-tools)
 
 Source: [`packages/examples/acp-demo/src/index.ts:40`](../packages/examples/acp-demo/src/index.ts)
 
@@ -1384,6 +1386,8 @@ export interface Config {
   persistenceRoot?: string
   /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
   persistenceCompression?: JsonlCompression
+  /** Cross-session reference discovery and snapshot byte budgets. */
+  sessionReferences?: SessionReferenceConfig
   /** TUI subtitle rendered on start. Defaults to `ready.`. */
   welcome?: string
   /** Full-screen TUI presentation settings. */
@@ -1403,7 +1407,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`uiTui`](../packages/ui/tui/src/index.ts)
+Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`SessionReferenceConfig`](#deepseek-aidsh-session-reference) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`uiTui`](../packages/ui/tui/src/index.ts)
 
 Source: [`packages/examples/tui-demo/src/index.ts:35`](../packages/examples/tui-demo/src/index.ts)
 

docs/cordis-catalog/services.md

@@ -854,9 +854,10 @@ Exact-read consumer that prepares immutable cross-session message context.
  * @param agent - target agent; self is excluded and its cwd drives ranking.
  * @param query - optional case-insensitive session-id/cwd substring.
  * @param limit - optional positive result cap.
+ * @param signal - optional cancellation boundary for host autocomplete teardown.
  * @returns candidate records in stable source creation order within each rank.
  */
-async listCandidates(agent: Agent, query = '', limit = this.config.candidateLimit): Promise<SessionReferenceCandidate[]>
+async listCandidates( agent: Agent, query = '', limit = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
 
 /**
  * Snapshot all references before enqueue and return one aggregated durable context.

docs/core-data-structures/core.md

@@ -356,11 +356,11 @@ interface SendOptions {
 }
 ```
 
-`InjectOptions` extends ordinary message attribution with durable model-hidden JSON metadata:
+`InjectOptions` accepts ordinary message attribution and durable model-hidden JSON metadata. Attached contexts belong only to queued or steering input, so synthetic injection cannot accept them:
 
 ```ts type-equiv
 /** Options specific to durable synthetic context injection. */
-interface InjectOptions extends SendOptions {
+interface InjectOptions extends Omit<SendOptions, 'contexts'> {
   /** Opaque JSON state retained in the session event but hidden from the model. */
   meta?: JsonValue
 }

packages/context/session-reference/src/index.ts

@@ -102,15 +102,22 @@ export class SessionReferenceService extends Service {
    * @param agent - target agent; self is excluded and its cwd drives ranking.
    * @param query - optional case-insensitive session-id/cwd substring.
    * @param limit - optional positive result cap.
+   * @param signal - optional cancellation boundary for host autocomplete teardown.
    * @returns candidate records in stable source creation order within each rank.
    */
-  async listCandidates(agent: Agent, query = '', limit = this.config.candidateLimit): Promise<SessionReferenceCandidate[]> {
+  async listCandidates(
+    agent: Agent,
+    query = '',
+    limit = this.config.candidateLimit,
+    signal?: AbortSignal,
+  ): Promise<SessionReferenceCandidate[]> {
     if (!Number.isSafeInteger(limit) || limit <= 0) {
       throw new SessionReferenceError('candidate limit must be a positive safe integer', 'SESSION_REFERENCE_INVALID_REFERENCE')
     }
     const needle = query.toLocaleLowerCase()
     const targetCwd = agent.session.header.cwd
-    const records = (await this.ctx.sessionQuery.listSessions())
+    assertNotCancelled(signal)
+    const records = (await settleWithCancellation(this.ctx.sessionQuery.listSessions(), signal))
       .filter(record => record.header.id !== agent.id)
       .filter((record) => {
         if (needle === '') return true
@@ -149,10 +156,13 @@ export class SessionReferenceService extends Service {
     assertNotCancelled(signal)
     let prepared: PreparedSource[]
     try {
-      prepared = await Promise.all(inputs.map(async input => ({
-        input,
-        snapshot: await this.ctx.sessionQuery.readSurface(input.sessionId),
-      })))
+      prepared = await settleWithCancellation(
+        Promise.all(inputs.map(async input => ({
+          input,
+          snapshot: await this.ctx.sessionQuery.readSurface(input.sessionId),
+        }))),
+        signal,
+      )
     } catch (error: unknown) {
       if (signal?.aborted === true) throw cancelled(signal)
       throw new SessionReferenceError(
@@ -258,6 +268,25 @@ function assertNotCancelled(signal: AbortSignal | undefined): void {
   if (signal?.aborted === true) throw cancelled(signal)
 }
 
+function settleWithCancellation<T>(work: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return work
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => { reject(cancelled(signal)) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    void work.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(error instanceof Error ? error : new Error(String(error)))
+      },
+    )
+    if (signal.aborted) onAbort()
+  })
+}
+
 function cancelled(signal: AbortSignal): SessionReferenceError {
   return new SessionReferenceError('session reference preparation was cancelled', 'SESSION_REFERENCE_CANCELLED', { cause: signal.reason })
 }

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

@@ -190,6 +190,21 @@ describe('session reference discovery and preparation', () => {
     ])
     await expect(ctx.sessionReferences.listCandidates(fakeAgent(target), '', 0))
       .rejects.toThrow(expectCode('SESSION_REFERENCE_INVALID_REFERENCE'))
+
+    let releaseList: (() => void) | undefined
+    const listSessions = vi.spyOn(ctx.sessionQuery, 'listSessions').mockImplementationOnce(async () => {
+      await new Promise<void>((resolve) => { releaseList = resolve })
+      return []
+    })
+    const controller = new AbortController()
+    const pending = ctx.sessionReferences.listCandidates(fakeAgent(target), '', undefined, controller.signal)
+    await vi.waitFor(() => { expect(releaseList).toBeTypeOf('function') })
+    const cancelledList = expect(pending).rejects.toThrow(expectCode('SESSION_REFERENCE_CANCELLED'))
+    controller.abort('autocomplete superseded')
+    await cancelledList
+    releaseList?.()
+    await Promise.resolve()
+    listSessions.mockRestore()
   })
 
   it('projects only the current user/assistant surface and records snapshot metadata', async () => {
@@ -309,6 +324,9 @@ describe('session reference discovery and preparation', () => {
     readSurface.mockRejectedValueOnce('non-error read failure')
     await expect(ctx.sessionReferences.prepare(agent, content, [{ sessionId: one.id }]))
       .rejects.toThrow(/non-error read failure/)
+    readSurface.mockRejectedValueOnce('non-error signalled read failure')
+    await expect(ctx.sessionReferences.prepare(agent, content, [{ sessionId: one.id }], new AbortController().signal))
+      .rejects.toThrow(/non-error signalled read failure/)
 
     const duringRead = new AbortController()
     readSurface.mockImplementationOnce(async () => {
@@ -317,6 +335,21 @@ describe('session reference discovery and preparation', () => {
     })
     await expect(ctx.sessionReferences.prepare(agent, content, [{ sessionId: one.id }], duringRead.signal))
       .rejects.toThrow(expectCode('SESSION_REFERENCE_CANCELLED'))
+
+    const snapshot = await ctx.sessionQuery.readSurface(one.id)
+    let releaseRead: (() => void) | undefined
+    readSurface.mockImplementationOnce(async () => {
+      await new Promise<void>((resolve) => { releaseRead = resolve })
+      return snapshot
+    })
+    const hangingRead = new AbortController()
+    const pending = ctx.sessionReferences.prepare(agent, content, [{ sessionId: one.id }], hangingRead.signal)
+    await vi.waitFor(() => { expect(releaseRead).toBeTypeOf('function') })
+    const cancelledRead = expect(pending).rejects.toThrow(expectCode('SESSION_REFERENCE_CANCELLED'))
+    hangingRead.abort('cancelled while storage remained pending')
+    await cancelledRead
+    releaseRead?.()
+    await Promise.resolve()
     readSurface.mockRestore()
 
     const abort = new AbortController()

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

@@ -434,8 +434,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     summary: 'Exact-read consumer that prepares immutable cross-session message context.',
     methods: [
       {
-        signature: 'async listCandidates(agent: Agent, query = \'\', limit = this.config.candidateLimit): Promise<SessionReferenceCandidate[]>',
-        jsDoc: '/**\n * List metadata-only reference candidates, ranked by working-directory affinity.\n * @param agent - target agent; self is excluded and its cwd drives ranking.\n * @param query - optional case-insensitive session-id/cwd substring.\n * @param limit - optional positive result cap.\n * @returns candidate records in stable source creation order within each rank.\n */',
+        signature: 'async listCandidates( agent: Agent, query = \'\', limit = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>',
+        jsDoc: '/**\n * List metadata-only reference candidates, ranked by working-directory affinity.\n * @param agent - target agent; self is excluded and its cwd drives ranking.\n * @param query - optional case-insensitive session-id/cwd substring.\n * @param limit - optional positive result cap.\n * @param signal - optional cancellation boundary for host autocomplete teardown.\n * @returns candidate records in stable source creation order within each rank.\n */',
       },
       {
         signature: 'async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>',
@@ -1352,7 +1352,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InjectOptions',
-    declaration: 'export interface InjectOptions extends SendOptions {\n    meta?: JsonValue;\n}',
+    declaration: 'export interface InjectOptions extends Omit<SendOptions, \'contexts\'> {\n    meta?: JsonValue;\n}',
   },
   {
     name: 'JsonValue',

packages/core/agent/src/types.ts

@@ -40,7 +40,7 @@ export interface SendOptions {
 }
 
 /** Options specific to durable synthetic context injection. */
-export interface InjectOptions extends SendOptions {
+export interface InjectOptions extends Omit<SendOptions, 'contexts'> {
   /** Opaque JSON state retained in the session event but hidden from the model. */
   meta?: JsonValue
 }

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

@@ -23,7 +23,7 @@ import SessionPersistenceJsonl, {
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import SessionQueryService from '@deepseek-ai/dsh-session-query'
-import SessionReferenceService from '@deepseek-ai/dsh-session-reference'
+import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
 
 export const name = 'acp-demo'
 const DEFAULT_PERSISTENCE_ROOT = './.sessions'
@@ -56,6 +56,8 @@ export interface Config {
   persistenceRoot?: string
   /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
   persistenceCompression?: JsonlCompression
+  /** Cross-session reference discovery and snapshot byte budgets. */
+  sessionReferences?: SessionReferenceConfig
   /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
   workspaceContext: agentCore.Config['workspaceContext']
   /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
@@ -86,6 +88,7 @@ export const Config: z<Config> = z.object({
   dshHome: z.string(),
   persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
   persistenceCompression: JsonlCompressionSchema,
+  sessionReferences: SessionReferenceService.Config,
   workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
   skills: agentCore.SkillConfigSchema,
   toolBash: agentCore.ToolBashConfigSchema,
@@ -107,12 +110,16 @@ export function apply(ctx: Context, config: Config): void {
   ctx.plugin(CommandService)
   if (goals !== false) ctx.plugin(commandGoal)
   ctx.plugin(agentCore, { ...agentCore.pickSpineConfig(config), goals })
+  // This front door owns the same persistence/reference cluster as the TUI;
+  // extracting these few calls would introduce a shared app-composition facade.
+  /* jscpd:ignore-start */
   ctx.plugin(UserInteractionService)
   ctx.plugin(SessionPersistenceJsonl, {
     root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
     ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
   })
   ctx.plugin(SessionQueryService)
-  ctx.plugin(SessionReferenceService)
+  ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
+  /* jscpd:ignore-end */
   ctx.plugin(acp, { provider: config.provider, model: config.model })
 }

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

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import type { Message } from '@deepseek-ai/dsh-llm'
 import * as acpAgent from '../src/index.ts'
@@ -76,6 +77,7 @@ describe('dsh-acp-demo composition', () => {
       persona: 'hi',
       persistenceRoot: '/tmp/dsh-acp-demo-test',
       persistenceCompression: 'none',
+      sessionReferences: { candidateLimit: 1 },
       skills: await isolatedSkillsConfig(),
       workspaceContext: false,
     })
@@ -90,6 +92,11 @@ describe('dsh-acp-demo composition', () => {
     expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined()
     expect(ctx.get('goals')).toBeDefined()
     expect(ctx.get('tools')?.get('get_goal')).toBeDefined()
+    const target = ctx.sessions.create(SessionId('candidate-target'))
+    ctx.sessions.create(SessionId('candidate-one'))
+    ctx.sessions.create(SessionId('candidate-two'))
+    await expect(ctx.sessionReferences.listCandidates({ id: target.id, session: target } as Agent))
+      .resolves.toHaveLength(1)
     // No pre-created agents — ACP session/new creates them on demand.
     expect(ctx.get('agents')!.list()).toHaveLength(0)
     await ctx.fiber.dispose()

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

@@ -23,7 +23,7 @@ import SessionPersistenceJsonl, {
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import SessionQueryService from '@deepseek-ai/dsh-session-query'
-import SessionReferenceService from '@deepseek-ai/dsh-session-reference'
+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'
 
@@ -51,6 +51,8 @@ export interface Config {
   persistenceRoot?: string
   /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
   persistenceCompression?: JsonlCompression
+  /** Cross-session reference discovery and snapshot byte budgets. */
+  sessionReferences?: SessionReferenceConfig
   /** TUI subtitle rendered on start. Defaults to `ready.`. */
   welcome?: string
   /** Full-screen TUI presentation settings. */
@@ -83,6 +85,7 @@ export const Config: z<Config> = z.object({
   dshHome: z.string(),
   persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
   persistenceCompression: JsonlCompressionSchema,
+  sessionReferences: SessionReferenceService.Config,
   welcome: z.string().default(DEFAULT_WELCOME),
   ui: uiTui.TuiConfigSchema,
   skills: agentCore.SkillConfigSchema,
@@ -112,7 +115,7 @@ export function composeTuiApp(ctx: Context, config: Config): void {
     ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
   })
   ctx.plugin(SessionQueryService)
-  ctx.plugin(SessionReferenceService)
+  ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
   ctx.plugin(UserInteractionService)
   ctx.plugin(uiTui, {
     ...config.ui,

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

@@ -32,6 +32,12 @@ describe('dsh-tui-demo app', () => {
       dshHome: '/tmp/dsh-home',
       persistenceRoot: '/tmp/tui-sessions',
       persistenceCompression: 'none',
+      sessionReferences: {
+        maxReferences: 2,
+        candidateLimit: 7,
+        maxReferenceBytes: 1234,
+        maxTotalBytes: 2345,
+      },
       welcome: 'TUI ready',
       ui: { color: false, maxToolOutputLines: 3 },
       skills: { tool: { catalogDescriptionMaxLength: 8 } },
@@ -53,6 +59,12 @@ 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({
+      maxReferences: 2,
+      candidateLimit: 7,
+      maxReferenceBytes: 1234,
+      maxTotalBytes: 2345,
+    })
     const tuiConfig = calls[6]?.config as { sessionId: string }
     expect(tuiConfig).toMatchObject({ welcome: 'TUI ready', color: false, maxToolOutputLines: 3 })
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
@@ -90,6 +102,7 @@ describe('dsh-tui-demo app', () => {
     })
 
     expect(calls[2]?.config).toEqual({ root: './.sessions' })
+    expect(calls[4]?.config).toEqual({})
     expect(calls[6]?.config).toEqual({ welcome: 'ready.', sessionId: 'persisted-session' })
     expect((calls[7]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
       id: 'main',

packages/ui/acp/tests/bridge.spec.ts

@@ -397,25 +397,25 @@ describe('acp bridge', () => {
   it('cancels reference preparation before a turn is created', async () => {
     harness = await makeBridgeHarness({ storageDir, withSessionReferences: true, script: [] })
     const source = harness.ctx.sessions.create(SessionId('source'))
+    const snapshot = await harness.ctx.sessionQuery.readSurface(source.id)
     await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
     const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const prepare = vi.spyOn(harness.ctx.sessionReferences, 'prepare').mockImplementation(
-      (_agent, _content, _references, signal) => new Promise((_resolve, reject) => {
-        if (signal?.aborted === true) {
-          reject(new Error('already aborted'))
-          return
-        }
-        signal?.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
-      }),
-    )
+    let releaseRead: (() => void) | undefined
+    const readSurface = vi.spyOn(harness.ctx.sessionQuery, 'readSurface').mockImplementationOnce(async () => {
+      await new Promise<void>((resolve) => { releaseRead = resolve })
+      return snapshot
+    })
     const pending = harness.client.prompt({
       sessionId,
       prompt: [{ type: 'resource_link', uri: encodeSessionReferenceUri(source.id), name: 'source' }],
     })
-    await vi.waitFor(() => { expect(prepare).toHaveBeenCalledOnce() })
+    await vi.waitFor(() => { expect(releaseRead).toBeTypeOf('function') })
     await harness.client.cancel({ sessionId })
     await expect(pending).resolves.toEqual({ stopReason: 'cancelled' })
     expect(harness.ctx.agents.get(SessionId(sessionId))?.session.events).toHaveLength(0)
+    releaseRead?.()
+    await Promise.resolve()
+    readSurface.mockRestore()
   })
 
   it('rejects a prompt for an unknown session', async () => {

packages/ui/tui/src/index.ts

@@ -202,6 +202,11 @@ function displayText(text: string): string {
     `\\x${control.charCodeAt(0).toString(16).padStart(2, '0')}`)
 }
 
+/** Escape external controls for terminal fields that must remain on one line. */
+function displayInlineText(text: string): string {
+  return displayText(text).replaceAll('\n', '\\x0a')
+}
+
 /**
  * Theme-agnostic palette built from the standard 16-color ANSI set plus SGR
  * attributes, which every terminal remaps to its active color scheme. Body
@@ -827,17 +832,20 @@ class SessionAutocompleteProvider implements AutocompleteProvider {
     if (token === undefined) return basePromise
     let candidates
     try {
-      candidates = await this.sessions.listCandidates(this.agent, token.slice(1))
+      candidates = await this.sessions.listCandidates(this.agent, token.slice(1), undefined, options.signal)
     } catch {
       return basePromise
     }
     const base = await basePromise
     if (options.signal.aborted) return base
-    const items: AutocompleteItem[] = candidates.map(candidate => ({
-      value: formatSessionReferenceMention({ sessionId: candidate.sessionId, label: candidate.label }),
-      label: `Session · ${candidate.sessionId}`,
-      description: `${candidate.cwd ?? '(no cwd)'} · ${new Date(candidate.createdAt).toISOString()}`,
-    }))
+    const items: AutocompleteItem[] = candidates.map((candidate) => {
+      const mentionLabel = displayInlineText(candidate.label)
+      return {
+        value: formatSessionReferenceMention({ sessionId: candidate.sessionId, label: mentionLabel }),
+        label: `Session · ${displayInlineText(candidate.sessionId)}`,
+        description: `${candidate.cwd === undefined ? '(no cwd)' : displayInlineText(candidate.cwd)} · ${new Date(candidate.createdAt).toISOString()}`,
+      }
+    })
     if (items.length === 0) return base
     return { items: [...items, ...(base?.items ?? [])], prefix: token }
   }

packages/ui/tui/tests/tui.spec.ts

@@ -2,7 +2,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import type { Terminal } from '@earendil-works/pi-tui'
+import { CombinedAutocompleteProvider, type Terminal } from '@earendil-works/pi-tui'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import CommandService, { type CommandInvocation } from '@deepseek-ai/dsh-commands'
 import SessionStore, { SessionId, type JsonValue } from '@deepseek-ai/dsh-session'
@@ -545,6 +545,40 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await dispose(result)
   })
 
+  it('escapes session autocomplete metadata while preserving the referenced session id', async () => {
+    const unsafeId = SessionId('evil\x1b\x07\u009b\ns')
+    const unsafeCwd = '/x/\x1b\x07\u009b\nf'
+    const result = await setup({
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        await ctx.plugin(SessionQueryService)
+        await ctx.plugin(SessionReferenceService)
+        const source = ctx.sessions.create(unsafeId, { meta: { cwd: unsafeCwd, createdAt: 1 } })
+        appendUser(source, 'safe background')
+      },
+    })
+
+    result.terminal.send('@evil')
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('Session · evil\\x1b\\x07\\x9b\\x0a')
+    })
+    expect(result.terminal.output).toContain('/x/\\x1b\\x07\\x9b\\x0af')
+    expect(result.terminal.output).not.toContain('evil\x1b\x07')
+    expect(result.terminal.output).not.toContain('/x/\x1b\x07')
+
+    result.terminal.send('\t')
+    await tick()
+    result.terminal.send('\r')
+    await vi.waitFor(() => { expect(result.agent.sent).toHaveLength(1) })
+    expect(result.agent.sent).toEqual([[
+      { type: 'text', text: '@evil\\x1b\\x07\\x9b\\x0as' },
+    ]])
+    expect(result.agent.sentOptions[0]?.contexts).toMatchObject([{
+      meta: { references: [{ sessionId: unsafeId }] },
+    }])
+    await dispose(result)
+  })
+
   it('falls back cleanly for non-session, empty, failed, and superseded autocomplete requests', async () => {
     const result = await setup({
       async configureContext(ctx) {
@@ -575,19 +609,38 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await tick()
     result.terminal.send('\x03')
 
-    let releaseFirst: (() => void) | undefined
+    let releaseBase: (() => void) | undefined
+    const baseSuggestions = vi.spyOn(CombinedAutocompleteProvider.prototype, 'getSuggestions')
+      .mockImplementationOnce(async () => {
+        await new Promise<void>((resolve) => { releaseBase = resolve })
+        return null
+      })
+    listCandidates.mockResolvedValueOnce([])
+    result.terminal.send('@base-slow')
+    await vi.waitFor(() => { expect(releaseBase).toBeTypeOf('function') })
+    const baseWaitSignal = listCandidates.mock.calls.at(-1)?.[3]
+    result.terminal.send('x')
+    await vi.waitFor(() => { expect(baseWaitSignal?.aborted).toBe(true) })
+    releaseBase?.()
+    await tick()
+    baseSuggestions.mockRestore()
+
+    let delayedSignal: AbortSignal | undefined
     let delayed = true
     listCandidates.mockImplementation(async (...args) => {
       if (!delayed) return originalListCandidates(...args)
       delayed = false
-      await new Promise<void>((resolve) => { releaseFirst = resolve })
+      delayedSignal = args[3]
+      if (delayedSignal === undefined) throw new Error('expected autocomplete cancellation signal')
+      await new Promise<void>((_resolve, reject) => {
+        delayedSignal?.addEventListener('abort', () => { reject(new Error('superseded')) }, { once: true })
+      })
       return []
     })
     result.terminal.send('@slow')
-    await vi.waitFor(() => { expect(releaseFirst).toBeTypeOf('function') })
+    await vi.waitFor(() => { expect(delayedSignal).toBeDefined() })
     result.terminal.send('x')
-    releaseFirst?.()
-    await tick()
+    await vi.waitFor(() => { expect(delayedSignal?.aborted).toBe(true) })
     await dispose(result)
   })