Merge remote-tracking branch 'origin/master' into xtr/identified-immutable-messages

# Conflicts:
#	.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
#	packages/context/session-reference/README.i18n.yaml
#	packages/context/session-reference/README.md
#	packages/context/session-reference/README.zh.md
#	packages/context/session-reference/src/index.ts

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: 1cd1197ef8eedfaba3b205bfde75b3404d4fc317
-README.zh.md: 9b72fd2b69e6f40f8133849da49bc863ba25eb3d
+README.md: 66df45b18df6d859239c8d3216d6c8b9fa61ab23
+README.zh.md: 7431f1375d50f4734f3efeea9a2597b7296e38c2

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, identified `UserMessage` 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 去重，并拒绝自引用或超过已配置不同源上限的情况。它会并行读取所有源，返回与输入脱离的内容，外加零个或一个聚合且带标识的 `UserMessage` 上下文。任何无效引用、读取失败、取消或预算失败都会在宿主调用 `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

@@ -9,9 +9,9 @@ import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { SessionId, UserMessage } from '@deepseek-ai/dsh-session'
-import type { SessionSurfaceSnapshot } from '@deepseek-ai/dsh-session-query'
+import type { ContentBlock, UserMessage } from '@deepseek-ai/dsh-llm'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionSurfaceSnapshot, SessionTitleObservationResult } from '@deepseek-ai/dsh-session-query'
 import {
   DEFAULT_CANDIDATE_LIMIT,
   DEFAULT_MAX_REFERENCE_BYTES,
@@ -103,7 +103,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.
@@ -120,27 +120,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

@@ -243,7 +243,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 } })
@@ -265,6 +265,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'))
 
@@ -284,6 +287,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' } })