Merge pull request #797 from deepseek-harness/worktree/tui-session-title-search

fix(tui): search session references by title

.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 .agents/notes/implemented/feature/2026-07-21-cross-session-references.md
-2026-07-21-cross-session-references.md: 18dab5fb85f2201258e2f15c3c069d2668ae80d3
-2026-07-21-cross-session-references.zh.md: 44e33ab1ed762b08b6be30d66b82396a5b519c02
+2026-07-21-cross-session-references.md: a6c7c3b3e89e032d6d807a25a7661a875f9f7bec
+2026-07-21-cross-session-references.zh.md: ef78cd7ecee3e2625b446139d7f22e16d0bf1dfa

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

@@ -14,7 +14,7 @@ TUI users need to bring relevant work from another conversation into one new mes
 
 `dsh-session:<base64url(JSON.stringify(sessionId))>` is the canonical host-independent identifier. JSON string encoding precedes base64url so quotes, slashes, backslashes, Unicode, newlines, and every other JavaScript string value round-trip without delimiter ambiguity. TUI renders that URI inside `@[label](uri)`; text-only clients may use the same inline mention. Explicit Markdown mentions reject malformed URIs. Bare text becomes a reference only for a non-empty base64url-shaped payload, whose decode must still be canonical; empty or punctuation-only uses remain ordinary discussion text.
 
-The service uses `ctx.sessionQuery.readSurface(sessionId)`, which loads one live-preferred corpus observation, folds it with the session package's canonical surface algorithm, and returns a detached header, capture seq, and current nodes. FTS is not a dependency: v1 discovery filters only id and cwd, and future title/body search can replace the candidate layer without changing reference identity or preparation.
+The service uses `ctx.sessionQuery.readSurface(sessionId)`, which loads one live-preferred corpus observation, folds it with the session package's canonical surface algorithm, and returns a detached header, capture seq, and current nodes. FTS is not a dependency: discovery matches id, cwd, or the latest folded title, while message bodies remain outside the candidate layer. Non-empty queries batch title observations across the visible corpus with bounded persisted-log concurrency and cancellation; a dedicated title index can replace that discovery path without changing reference identity or preparation.
 
 ## Snapshot and projection
 
@@ -32,7 +32,7 @@ Reference preparation is not a new steering protocol and does not create a turn
 
 ## Host adapters
 
-TUI combines session candidates with the existing `@` file provider. Each candidate displays the latest folded session title and falls back to the session id; 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, renders the readable direct content as the user message, and renders session-reference source metadata 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 matches case-insensitive substrings of the session id, cwd, or latest folded title, displays that title, and falls back to the session id when a title observation is absent or fails. 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, renders the readable direct content as the user message, and renders session-reference source metadata as a compact source list instead of exposing the complete JSON in the terminal.
 
 The [automation-only ACP transport](../simplification/2026-07-23-acp-automation-only-protocol.md) deliberately does not mount session-query or session-reference services.
 
@@ -53,7 +53,7 @@ Each of at most three references is independently capped at 65,536 UTF-8 bytes b
 
 ## Verification
 
-Unit and integration coverage pins URI round-trips and text-boundary punctuation, explicit malformed references, title-aware candidate ranking, terminal-control escaping, projection exclusions, non-recursive snapshot projection, backend-independent compact checkpoints, tag-safe framing, deduplication, self-reference, count limits, all-or-nothing reads, prompt cancellation against a non-settling storage read, independent per-source byte retention, prompt blocking, admission-time staging, send/steer placement, title isolation, missing capability, and compact TUI replay. 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 a sourced snapshot message followed by the readable current prompt, without either shadowed string.
+Unit and integration coverage pins URI round-trips and text-boundary punctuation, explicit malformed references, id/cwd/title candidate matching and ranking, failed title-observation fallback, candidate cancellation, terminal-control escaping, projection exclusions, non-recursive snapshot projection, backend-independent compact checkpoints, tag-safe framing, deduplication, self-reference, count limits, all-or-nothing reads, prompt cancellation against a non-settling storage read, independent per-source byte retention, prompt blocking, admission-time staging, send/steer placement, title isolation, missing capability, and compact TUI replay. One keyless terminal snapshot types a title-only substring against an opaque session id and pins the rendered candidate. Another 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 a sourced snapshot message followed by the readable current prompt, without either shadowed string.
 
 ## Consequences
 

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

@@ -14,7 +14,7 @@ TUI 用户需要把另一场对话中的相关工作带入一条新消息，但
 
 `dsh-session:<base64url(JSON.stringify(sessionId))>` 是与宿主无关的规范标识符。系统先执行 JSON 字符串编码，再执行 base64url 编码，因此引号、正斜杠、反斜杠、Unicode、换行符以及其他任意 JavaScript 字符串值都能无损往返，不会因分隔符产生歧义。TUI 把该 URI 渲染到 `@[label](uri)` 中；纯文本客户端可以使用同一种行内提及标记。显式 Markdown 提及标记会拒绝格式错误的 URI。裸文本只有在负载非空且形状符合 base64url 时才会成为引用，而且解码过程仍须通过规范性校验；空负载或只含标点符号的用法仍按普通讨论文本处理。
 
-该服务使用 `ctx.sessionQuery.readSurface(sessionId)`：它优先从实时会话加载一次语料观察结果，使用会话包的规范表层算法执行折叠，并返回与源数据分离的会话头、捕获序号和当前节点。FTS 不是功能依赖：v1 的候选发现只按 id 和 cwd 过滤；未来的标题或正文搜索可以替换候选层，而无需改变引用标识或准备过程。
+该服务使用 `ctx.sessionQuery.readSurface(sessionId)`：它优先从实时会话加载一次语料观察结果，使用会话包的规范表层算法执行折叠，并返回与源数据分离的会话头、捕获序号和当前节点。FTS 不是功能依赖：候选发现会匹配 id、cwd 或最新折叠后的标题，而消息主体不进入候选层。非空查询会对可见语料中的标题观察结果执行批处理，以有界并发读取持久化日志，并支持取消；专用标题索引可以替换这条发现路径，而无需改变引用标识或准备过程。
 
 ## 快照与投影
 
@@ -32,7 +32,7 @@ TUI 负责快照／直接消息事务，不扩展通用收件箱记录。在 nex
 
 ## 宿主适配器
 
-TUI 把会话候选与现有 `@` 文件提供方组合在一起。每个候选项显示最新折叠后的会话标题，没有标题时回退到 session id。候选查询遵循编辑器的取消信号；session id、cwd 和提及标签中的外部终端控制字符会被转义，但规范 URI 仍保留原始 id。TUI 只准备包含结构化提及标记的提交；等待快照时禁用重复提交；失败时恢复输入；它把可读的直接内容渲染为用户消息，并把会话引用来源元数据渲染为精简的来源列表，不在终端中暴露完整 JSON。
+TUI 把会话候选与现有 `@` 文件提供方组合在一起。候选查询会对 session id、cwd 或最新折叠后的标题执行不区分大小写的子串匹配，显示该标题，并在没有标题观察结果或标题观察失败时回退到 session id。候选查询遵循编辑器的取消信号；session id、cwd 和提及标签中的外部终端控制字符会被转义，但规范 URI 仍保留原始 id。TUI 只准备包含结构化提及标记的提交；等待快照时禁用重复提交；失败时恢复输入；它把可读的直接内容渲染为用户消息，并把会话引用来源元数据渲染为精简的来源列表，不在终端中暴露完整 JSON。
 
 [仅面向自动化的 ACP（Agent Client Protocol）传输层](../simplification/2026-07-23-acp-automation-only-protocol.md)有意不挂载会话查询或会话引用服务。
 
@@ -53,7 +53,7 @@ TUI 把会话候选与现有 `@` 文件提供方组合在一起。每个候选
 
 ## 验证
 
-单元与集成测试覆盖 URI 无损往返与文本边界标点、显式格式错误的引用、会考虑标题的候选排序、终端控制字符转义、投影排除规则、快照的非递归投影、与后端无关的压缩检查点、标签安全封套、去重、自引用、数量限制、读取的全有或全无、存储读取不结束时取消提示词、逐源独立字节保留、提示词阻止、准入期间的暂存、send／steer 放置方式、标题隔离、功能缺失和精简的 TUI 回放。无密钥 TUI 快照会运行真实的 agent loop（智能体循环）：源表层用一个压缩检查点替换旧的用户／assistant 历史，目标会话提交一个提及标记，捕获到的模型请求包含一条带来源的快照消息，后面跟随可读的当前提示词，并且不包含任一被遮蔽的字符串。
+单元与集成测试覆盖 URI 无损往返与文本边界标点、显式格式错误的引用、按 id／cwd／标题进行候选匹配与排序、标题观察失败时的回退、候选查询取消、终端控制字符转义、投影排除规则、快照的非递归投影、与后端无关的压缩检查点、标签安全封套、去重、自引用、数量限制、读取的全有或全无、存储读取不结束时取消提示词、逐源独立字节保留、提示词阻止、准入期间的暂存、send／steer 放置方式、标题隔离、功能缺失和精简的 TUI 回放。一个无密钥终端快照会在会话 id 不透明的情况下输入一个只与标题匹配的子串，并固定渲染出的候选项。另一个无密钥 TUI 快照会运行真实的 agent loop（智能体循环）：源表层用一个压缩检查点替换旧的用户／assistant 历史，目标会话提交一个提及标记，捕获到的模型请求包含一条带来源的快照消息，后面跟随可读的当前提示词，并且不包含任一被遮蔽的字符串。
 
 ## 后果
 

docs/cordis-catalog/services.md

@@ -1204,7 +1204,7 @@ Exact-read consumer that prepares immutable cross-session message context.
 /**
  * List reference candidates, ranked by working-directory affinity.
  * @param agent - target agent; self is excluded and its cwd drives ranking.
- * @param query - optional case-insensitive session-id/cwd substring.
+ * @param query - optional case-insensitive session-id/cwd/title substring.
  * @param limit - optional positive result cap.
  * @param signal - optional cancellation boundary for host autocomplete teardown.
  * @returns candidates labeled by latest title or, when absent, session id.

packages/context/session-reference/README.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 packages/context/session-reference/README.md
-README.md: 2ca461f88b266b4dec1ffa4132c8cb17455f4b8e
-README.zh.md: 9f8fd0bace9b37b2f7885eded7686ecac8c625ba
+README.md: 6def2923cf3bc0021b0db578279a1b0571106d41
+README.zh.md: 9d7abfa78e6d35b2149c9436d5b397e4a30404d7

packages/context/session-reference/README.md

@@ -6,7 +6,7 @@ English | [中文](README.zh.md)
 
 ## Public API
 
-- `listCandidates(agent, query?, limit?)` lists sessions other than `agent.id`, filters case-insensitively by id or cwd, and ranks same-cwd, cwd-less, then other-cwd records while preserving `listSessions()` creation order within each group. Each selected candidate uses its latest log-backed title as the mention label and falls back to the session id; titles and message bodies are not searched.
+- `listCandidates(agent, query?, limit?)` lists sessions other than `agent.id`, filters case-insensitively by id, cwd, or the latest log-backed title, and ranks same-cwd, cwd-less, then other-cwd records while preserving `listSessions()` creation order within each group. Each selected candidate uses that title as the mention label and falls back to the session id when the title is absent or unreadable; message bodies are not searched.
 - `prepare(agent, content, references, signal?)` preserves first-mention order, deduplicates ids, rejects self-reference and more than the configured distinct-source limit, reads every source in parallel, and returns detached content plus zero or one aggregated `UserMessageData` context. Any invalid reference, failed read, cancellation, or budget failure rejects before the host calls `followup()` or `steer()`.
 - `encodeSessionReferenceUri()` and `decodeSessionReferenceUri()` implement `dsh-session:<base64url(JSON.stringify(sessionId))>` so every JavaScript string id round-trips exactly. `formatSessionReferenceMention()` emits `@[label](uri)`, and `parseSessionReferenceText()` replaces Markdown mentions or bare canonical URIs with readable `@label` text while returning structured references. Explicit Markdown mentions reject every malformed URI; bare text is considered a reference only when a non-empty base64url-shaped payload follows the scheme, and a matching noncanonical candidate still fails. Empty or punctuation-only scheme mentions remain ordinary discussion text.
 
@@ -21,7 +21,7 @@ The context source is `{ kind: 'session-reference', version: 1, references }`; e
 | Key | Default | Contract |
 |---|---:|---|
 | `maxReferences` | `3` | Maximum distinct source sessions in one prepared message; must be at most `3`. |
-| `candidateLimit` | `50` | Default metadata candidate count returned to a host. |
+| `candidateLimit` | `50` | Default candidate count returned to a host. |
 | `maxReferenceBytes` | `65536` | Maximum serialized JSON bytes for one reference object. |
 
 Retention applies `maxReferenceBytes` independently to each source, keeps compact checkpoints and the newest message before dropping older non-checkpoint units, and uses `dsh-retention` head/tail truncation with an exact UTF-8 omission notice. If one source's fixed serialized fields cannot fit, preparation fails with `SESSION_REFERENCE_BUDGET_EXCEEDED` instead of returning a partial context.
@@ -44,7 +44,7 @@ The snapshot and request are consecutive append-only target messages and preserv
 
 ## Known Limitations and Deferred Work
 
-- **No title or full-text discovery** — candidates filter by session id and cwd only, although selected rows display the latest title. SQLite FTS may replace discovery later without changing URI, snapshot, or persistence contracts.
+- **No body discovery** — candidate queries inspect folded titles but do not search message bodies. A non-empty query may inspect every visible persisted session log through the session-query service's bounded, cancellable batch; a dedicated title index may replace that discovery path without changing URI, snapshot, or persistence contracts.
 - **Trusted caller boundary** — the service assumes its host is authorized to read every session exposed by `ctx.sessionQuery`; it is not a model-facing search tool.
 - **Text projection only** — non-text user and assistant blocks are not propagated across sessions.
 - **No live link** — references are snapshots, not forks, resumes, subscriptions, or source-session mutations.

packages/context/session-reference/README.zh.md

@@ -6,7 +6,7 @@
 
 ## 公开 API
 
-- `listCandidates(agent, query?, limit?)` 会列出 `agent.id` 之外的会话，按 id 或 cwd 进行不区分大小写的筛选，再按同 cwd、无 cwd、其他 cwd 记录排序，同时保持每组内的 `listSessions()` 创建顺序。每个已选候选会话都使用最新的日志支持标题作为 mention label，并回退到会话 id；不搜索标题与消息主体。
+- `listCandidates(agent, query?, limit?)` 会列出 `agent.id` 之外的会话，按 id、cwd 或日志中最新的标题进行不区分大小写的筛选，再按同 cwd、无 cwd、其他 cwd 记录排序，同时保持每组内的 `listSessions()` 创建顺序。每个已选候选会话都使用该标题作为 mention label；标题不存在或无法读取时回退到会话 id。不搜索消息主体。
 - `prepare(agent, content, references, signal?)` 会保留首次 mention 顺序、对 id 去重，并拒绝自引用或超过已配置不同源上限的情况。它会并行读取所有源，返回与输入脱离的内容，外加零个或一个聚合 `UserMessageData` 上下文。任何无效引用、读取失败、取消或预算失败都会在宿主调用 `followup()` 或 `steer()` 之前被拒绝。
 - `encodeSessionReferenceUri()` 与 `decodeSessionReferenceUri()` 实现 `dsh-session:<base64url(JSON.stringify(sessionId))>`，因此每个 JavaScript 字符串 id 都能精确往返。`formatSessionReferenceMention()` 发出 `@[label](uri)`，`parseSessionReferenceText()` 将 Markdown mention 或裸规范 URI 替换为可读的 `@label` 文本，并返回结构化引用。显式 Markdown mention 会拒绝每个格式错误的 URI；只当 scheme 后跟非空、符合 base64url 形状的 payload 时，裸文本才被视为引用，匹配但非规范的候选项仍会失败。空 scheme mention 或只含标点符号的 scheme mention 仍是普通讨论文本。
 
@@ -21,7 +21,7 @@
 | Key | 默认值 | 契约 |
 |---|---:|---|
 | `maxReferences` | `3` | 一条已准备消息中不同源会话的最大数量；必须不大于 `3`。 |
-| `candidateLimit` | `50` | 返回给宿主的默认元数据候选数量。 |
+| `candidateLimit` | `50` | 返回给宿主的默认候选数量。 |
 | `maxReferenceBytes` | `65536` | 一个引用对象的最大序列化 JSON 字节数。 |
 
 保留会对每个源独立应用 `maxReferenceBytes`，保留 compact 检查点与最新消息，再丢弃较旧的非检查点单元，并使用 `dsh-retention` 头部／尾部截断和精确 UTF-8 省略通知。如果某个源的固定序列化字段无法容纳，准备会以 `SESSION_REFERENCE_BUDGET_EXCEEDED` 失败，而不返回部分上下文。
@@ -44,7 +44,7 @@
 
 ## 已知限制与暂缓事项
 
-- **没有标题或全文发现**：候选会话只按会话 id 与 cwd 筛选，但已选行会显示最新标题。SQLite FTS 未来可以替换发现机制，而不改变 URI、快照或持久化契约。
+- **不支持正文发现**：候选查询会检查折叠后的标题，但不搜索消息主体。非空查询可能通过 session-query 服务有界、可取消的批处理检查每个可见的持久化会话日志；专用标题索引未来可以替换这条发现路径，而不改变 URI、快照或持久化契约。
 - **受信任调用方边界**：该服务假设宿主有权读取 `ctx.sessionQuery` 公开的每个会话；它不是面向模型的搜索工具。
 - **只投影文本**：不会在会话间传播非文本 user 与 assistant 块。
 - **没有实时链接**：引用是快照，不是 fork、恢复、订阅或源会话变更。

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

@@ -10,7 +10,7 @@ import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionId, UserMessageData } from '@deepseek-ai/dsh-session'
-import type { SessionSurfaceSnapshot } from '@deepseek-ai/dsh-session-query'
+import type { SessionSurfaceSnapshot, SessionTitleObservationResult } from '@deepseek-ai/dsh-session-query'
 import {
   DEFAULT_CANDIDATE_LIMIT,
   DEFAULT_MAX_REFERENCE_BYTES,
@@ -102,7 +102,7 @@ export class SessionReferenceService extends Service {
   /**
    * List reference candidates, ranked by working-directory affinity.
    * @param agent - target agent; self is excluded and its cwd drives ranking.
-   * @param query - optional case-insensitive session-id/cwd substring.
+   * @param query - optional case-insensitive session-id/cwd/title substring.
    * @param limit - optional positive result cap.
    * @param signal - optional cancellation boundary for host autocomplete teardown.
    * @returns candidates labeled by latest title or, when absent, session id.
@@ -119,27 +119,42 @@ export class SessionReferenceService extends Service {
     const needle = query.toLocaleLowerCase()
     const targetCwd = agent.session.header.cwd
     assertNotCancelled(signal)
-    const records = (await settleWithCancellation(this.ctx.sessionQuery.listSessions(), signal))
+    const records = (await settleWithCancellation(this.ctx.sessionQuery.listSessions(signal), signal))
       .filter(record => record.header.id !== agent.id)
-      .filter((record) => {
-        if (needle === '') return true
-        return record.header.id.toLocaleLowerCase().includes(needle)
-          || record.header.cwd?.toLocaleLowerCase().includes(needle) === true
-      })
       .map((record, index) => ({ record, index }))
-      .sort((a, b) => candidateRank(a.record.header.cwd, targetCwd) - candidateRank(b.record.header.cwd, targetCwd)
-        || a.index - b.index)
-      .slice(0, limit)
-    const titles = await settleWithCancellation(
-      Promise.all(records.map(({ record }) => this.ctx.sessionQuery.readTitle(record.header.id))),
+    const inspected = needle === ''
+      ? records
+        .sort((a, b) => candidateRank(a.record.header.cwd, targetCwd) - candidateRank(b.record.header.cwd, targetCwd)
+          || a.index - b.index)
+        .slice(0, limit)
+      : records
+    const observations = await settleWithCancellation(
+      this.ctx.sessionQuery.readTitleSnapshots(inspected.map(({ record }) => record.header.id), signal),
       signal,
     )
-    return records.map(({ record }, index) => ({
-      sessionId: record.header.id,
-      label: titles[index]?.title ?? record.header.id,
-      ...record.header.cwd === undefined ? {} : { cwd: record.header.cwd },
-      createdAt: record.header.createdAt,
-    }))
+    return inspected.map(({ record, index }, observationIndex) => {
+      const observation = observations[observationIndex] as SessionTitleObservationResult
+      return {
+        record,
+        index,
+        label: observation.status === 'fulfilled'
+          ? observation.value.title?.title ?? record.header.id
+          : record.header.id,
+      }
+    }).filter(({ record, label }) => {
+      if (needle === '') return true
+      return record.header.id.toLocaleLowerCase().includes(needle)
+        || record.header.cwd?.toLocaleLowerCase().includes(needle) === true
+        || label.toLocaleLowerCase().includes(needle)
+    }).sort((a, b) => candidateRank(a.record.header.cwd, targetCwd) - candidateRank(b.record.header.cwd, targetCwd)
+      || a.index - b.index)
+      .slice(0, limit)
+      .map(({ record, label }) => ({
+        sessionId: record.header.id,
+        label,
+        ...record.header.cwd === undefined ? {} : { cwd: record.header.cwd },
+        createdAt: record.header.createdAt,
+      }))
   }
 
   /**

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

@@ -188,7 +188,7 @@ describe('session reference URI and inline mentions', () => {
 })
 
 describe('session reference discovery and preparation', () => {
-  it('ranks metadata candidates by cwd without depending on full-text search', async () => {
+  it('matches candidate metadata and titles before ranking by cwd', async () => {
     const ctx = await harness()
     const target = ctx.sessions.create(SessionId('target'), { meta: { cwd: '/same', createdAt: 10 } })
     ctx.sessions.create(SessionId('other'), { meta: { cwd: '/else', createdAt: 40 } })
@@ -210,6 +210,9 @@ describe('session reference discovery and preparation', () => {
     await expect(ctx.sessionReferences.listCandidates(fakeAgent(target), 'els', 1)).resolves.toEqual([
       { sessionId: SessionId('other'), label: 'other', cwd: '/else', createdAt: 40 },
     ])
+    await expect(ctx.sessionReferences.listCandidates(fakeAgent(target), 'LATEST', 1)).resolves.toEqual([
+      { sessionId: SessionId('same-later'), label: 'Latest title', cwd: '/same', createdAt: 25 },
+    ])
     await expect(ctx.sessionReferences.listCandidates(fakeAgent(target), '', 0))
       .rejects.toThrow(expectCode('SESSION_REFERENCE_INVALID_REFERENCE'))
 
@@ -229,6 +232,40 @@ describe('session reference discovery and preparation', () => {
     listSessions.mockRestore()
   })
 
+  it('keeps metadata matches when one title observation fails and cancels a stalled title batch', async () => {
+    const ctx = await harness()
+    const target = ctx.sessions.create(SessionId('target'))
+    const source = ctx.sessions.create(SessionId('source'))
+    const readTitles = vi.spyOn(ctx.sessionQuery, 'readTitleSnapshots')
+    readTitles.mockResolvedValueOnce([{
+      sessionId: source.id,
+      status: 'rejected',
+      reason: new Error('broken title log'),
+    }])
+
+    await expect(ctx.sessionReferences.listCandidates(fakeAgent(target), 'source')).resolves.toEqual([
+      { sessionId: source.id, label: source.id, createdAt: source.header.createdAt },
+    ])
+
+    let releaseTitles: (() => void) | undefined
+    let titleSignal: AbortSignal | undefined
+    readTitles.mockImplementationOnce(async (_ids, signal) => {
+      titleSignal = signal
+      await new Promise<void>((resolve) => { releaseTitles = resolve })
+      return []
+    })
+    const controller = new AbortController()
+    const pending = ctx.sessionReferences.listCandidates(fakeAgent(target), 'source', undefined, controller.signal)
+    await vi.waitFor(() => { expect(releaseTitles).toBeTypeOf('function') })
+    expect(titleSignal).toBe(controller.signal)
+    const cancelledTitles = expect(pending).rejects.toThrow(expectCode('SESSION_REFERENCE_CANCELLED'))
+    controller.abort('autocomplete superseded')
+    await cancelledTitles
+    releaseTitles?.()
+    await Promise.resolve()
+    readTitles.mockRestore()
+  })
+
   it('projects only the current user/assistant surface and records snapshot metadata', async () => {
     const ctx = await harness()
     const target = ctx.sessions.create(SessionId('target'), { meta: { cwd: '/target' } })

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

@@ -602,7 +602,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'async listCandidates( agent: Agent, query = \'\', limit = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>',
-        jsDoc: '/**\n * List 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 candidates labeled by latest title or, when absent, session id.\n */',
+        jsDoc: '/**\n * List 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/title substring.\n * @param limit - optional positive result cap.\n * @param signal - optional cancellation boundary for host autocomplete teardown.\n * @returns candidates labeled by latest title or, when absent, session id.\n */',
       },
       {
         signature: 'async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>',

packages/ui/tui/tests/snapshots/session-title-autocomplete.expected.txt

@@ -0,0 +1,31 @@
+terminal 96x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=14 viewportRow=8 bufferRow=8
+viewport
+0| " DEEPSEEK HARNESS"
+  style 1-8 fg=bright-blue bold
+  style 10-16 bold
+1| " Snapshot agent ready."
+  style 1-21 fg=bright-black
+2| " main-session"
+  style 1-12 dim
+3| <blank>
+4| "Assistant                                                                                       "
+  style 0-8 fg=bright-magenta bold underline
+5| "Model wait 0.0s                                                                                 "
+  style 0-14 dim
+6| <blank>
+7| "/workspace/project (tui-staging)  deepseek-v4-flash  ↑0 ↓0  0% context"
+  style 0-17 fg=bright-blue bold
+  style 18-31 fg=bright-black
+  style 34-50 fg=bright-black
+  style 53-57 fg=bright-black
+  style 60-69 fg=bright-black
+8| " dsh > @design                                                                                  "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 14-14 inverse
+9| "       → Session · Searchable design re  opaque-source-id · /workspace/project · 1970-01-01T0   "
+  style 7-38 fg=bright-blue
+10-35| <blank>

packages/ui/tui/tests/tui.snapshot.ts

@@ -8,6 +8,7 @@ import { agentEvents } from '@deepseek-ai/dsh-agent'
 import { CallId, type ContentBlock } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-llm-retry'
 import { SessionId, type JsonValue, type Session } from '@deepseek-ai/dsh-session'
+import SessionReferenceService from '@deepseek-ai/dsh-session-reference'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { type ToolDefinition, type ToolResultView } from '@deepseek-ai/dsh-tools'
 import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
@@ -21,6 +22,7 @@ import {
   type TuiHarnessOptions,
 } from './harness.ts'
 import { HeadlessTerminal, type TerminalSnapshotOptions } from './headless-terminal.ts'
+import { TestSessionQueryService } from './session-query.ts'
 
 const SNAPSHOTS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
 const REFRESHING = process.env.DSH_SNAPSHOT === 'refresh'
@@ -35,6 +37,7 @@ const CHECKPOINTS = [
   'retry-exhausted',
   'banner-gradient',
   'file-autocomplete',
+  'session-title-autocomplete',
   'code-mode-pending',
   'dynamic-workflow-pending',
   'cordis-tools-pending',
@@ -399,6 +402,30 @@ describe('TUI terminal-state snapshots', () => {
     }
   })
 
+  it('pins session autocomplete discovered through a log-backed title', async () => {
+    const harness = await setupSnapshot({
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        await ctx.plugin(TestSessionQueryService)
+        await ctx.plugin(SessionReferenceService)
+        const source = ctx.sessions.create(SessionId('opaque-source-id'), {
+          meta: { cwd: '/workspace/project', createdAt: 1 },
+        })
+        source.append('session/title', {
+          title: 'Searchable design review',
+          messageSeqs: [],
+          source: { kind: 'fallback' },
+        })
+      },
+    })
+    harness.terminal.send('@design')
+    await vi.waitFor(async () => {
+      expect(await harness.terminal.snapshot()).toContain('Session · Searchable design re')
+    })
+    await checkpoint('session-title-autocomplete', harness.terminal)
+    await disposeSnapshot(harness)
+  })
+
   it('pins Code Mode run_code with its production presenter', async () => {
     const harness = await setupSnapshot({ configureContext: configureAdvancedTools })
     const call = {

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

@@ -2271,21 +2271,50 @@ describe('pi-tui chat lifecycle and transcript', () => {
   })
 
   it('combines session autocomplete with files and prepares send/steer references asynchronously', async () => {
-    let sourceId = SessionId('uninitialized')
+    const sourceId = SessionId('source-session')
+    const sourceHeader: SessionHeader = {
+      version: 0,
+      id: sourceId,
+      cwd: '/workspace',
+      createdAt: 1,
+    }
+    const noCwdHeader: SessionHeader = {
+      version: 0,
+      id: SessionId('no-cwd'),
+      createdAt: 2,
+    }
+    const sourceEvents: SessionEvent[] = [
+      {
+        type: 'user/message',
+        seq: 0,
+        time: 1,
+        data: { content: [{ type: 'text', text: 'source background' }], source: { kind: 'user' } },
+        surfaceOp: 'append',
+      },
+      {
+        type: 'session/title',
+        seq: 1,
+        time: 2,
+        data: {
+          title: 'Source chat',
+          messageSeqs: [0],
+          source: { kind: 'fallback' },
+        },
+      },
+    ]
     const result = await setup({
+      sessionPersistence: {
+        list: async () => [noCwdHeader, sourceHeader],
+        load: async (id) => {
+          if (id === sourceId) return { meta: sourceHeader, events: sourceEvents }
+          if (id === noCwdHeader.id) return { meta: noCwdHeader, events: [] }
+          throw new Error(`unexpected persisted session ${id}`)
+        },
+      },
       async configureContext(ctx) {
         ctx.provide('tools', { get: () => undefined } as never)
         await ctx.plugin(TestSessionQueryService)
         await ctx.plugin(SessionReferenceService)
-        const source = ctx.sessions.create(SessionId('source-session'), { meta: { cwd: process.cwd(), createdAt: 1 } })
-        sourceId = source.id
-        appendUser(source, 'source background')
-        source.append('session/title', {
-          title: 'Source chat',
-          messageSeqs: [0],
-          source: { kind: 'fallback' },
-        })
-        ctx.sessions.create(SessionId('no-cwd'), { meta: { createdAt: 2 } })
       },
     })
 
@@ -2294,7 +2323,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     expect(result.terminal.output).toContain('(no cwd)')
     result.terminal.send('\x03')
 
-    result.terminal.send('@source-session')
+    result.terminal.send('@chat')
     await vi.waitFor(() => { expect(result.terminal.output).toContain('Session · Source chat') })
     expect(result.terminal.output).toContain('source-session')
     result.terminal.send('\t')