docs(session-title): record contracts and generated catalogs

2026-08-15 21:04:50 +00:00 · 2026-07-21 01:54:00 +08:00
parent f71f96d292
commit 77df80359a
32 changed files with 783 additions and 47 deletions
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+architecture.md: ed17122d220145edbaafe56c02b4c0e21024316f
+architecture.zh.md: a69f3119ee4122b0f855cc1551d258f538e630ca
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,10 +1,12 @@
 # DeepSeek Harness Architecture

+English | [中文](architecture.zh.md)
+
 The **DeepSeek Harness SDK** builds agent harnesses on Cordis. The principle is simple: **everything is a plugin**. The shipped loop is one plugin, not a privileged kernel.

 ## Overview

-A harness is one [Cordis](cordis-primer.md) context. Packages add services (`ctx.llm`, `ctx.tools`, `ctx.sessions`), typed events (`agent/request`, `tools/pre-execute`, `session/event`), and disposable prompt, tool, provider, adapter, and listener registrations.
+A harness is one [Cordis](cordis-primer.md) context. Packages add services (`ctx.llm`, `ctx.tools`, `ctx.sessions`, `ctx.sessionTitle`), typed events (`agent/request`, `tools/pre-execute`, `session/event`), and disposable registrations.

 `packages/core/` groups the default agent flow; surrounding capabilities are equally first-class Cordis plugins.

@@ -38,6 +40,7 @@ A harness is one [Cordis](cordis-primer.md) context. Packages add services (`ctx
 | `ctx.workflows` | [`workflow/`](../packages/workflow/README.md) | script-driven multi-agent orchestration |
 | `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable storage for session logs |
 | `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | live-preferred logical-corpus exact reads and relationship traces |
+| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | log-backed fallback titles and one optional asynchronous provider |

 ## Event

@@ -45,9 +48,9 @@ Events form the service extension API; see the exhaustive [events catalog](cordi

 ### Event Domains

- **Session events** are durable, replayable facts: boundaries, messages, tool activity, steering, compaction, and tool-owned records append to the log and flow through `session/event`.
- **Agent events** carry the live `Agent` handle for status, diagnostics, prompt admission, request shaping, result validation, and continuation policy.
- **Capability events** belong to their owning seam; `tools/*`, `llm/*`, `system-prompt/*`, `fs/*`, and `subagent/*` attach policy and adapters without importing the loop.
+- **Session events** are durable facts appended to the log and emitted through `session/event`.
+- **Agent events** carry the live `Agent` for status, prompt admission, request shaping, validation, and continuation.
+- **Capability events** let owning seams attach policy and adapters without importing the loop.

 ### Interception Semantics

@@ -57,9 +60,9 @@ Waterfall events behave like around-middleware: a listener delegates by calling

 The shipped loop drains prompt-to-checkpoint work through plugin-visible services and events.

-A **session** is an append-only log. Each ordinary **turn** claims one queued `send()` item; injection claims none. A claimed `send()` successor awaits the preceding claimed ordinary turn's checkpoint but may share its `running` interval ([decision](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)). A turn ends when model and plugins stop it. A **step** is one model request plus tools. Below ([sequence companion](agent-lifecycle.md)), quotes mark durable events; other names are extension points.
+A **session** is an append-only log. Each ordinary **turn** claims one queued `send()` item; injection claims none. Successors await the preceding claimed turn's checkpoint but may share its `running` interval ([decision](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)). A turn ends when model and plugins stop it. A **step** is one model request plus tools. Below ([sequence companion](agent-lifecycle.md)), quotes mark durable events.

-No id mints `<config-id>-session-<uuid>`; `sessionId` resumes/creates; `resumeSessionId` needs history. Resume restores lineage, seeds, and delegation depth pre-publication. Failures emit `agent-loop/config-start-failed(sessionId, error)`; front doors reject; teardown stays silent.
+No id mints `<config-id>-session-<uuid>`; `sessionId` resumes/creates and `resumeSessionId` needs history. Resume restores lineage and delegation depth before publication. Setup failures emit `agent-loop/config-start-failed`; teardown stays silent.

 ### Turn Flow

@@ -107,15 +110,15 @@ forever:
    checkpoint persistence and notify idle/running status
 ```

-Each step assembles ordered prompt sections, tool schemas, and `{{name}}` variables; unknown or valueless references fail the turn. `dsh-system-prompt` owns the harness identity and default persona, which an agent scope may shadow. The loop supplies `model` and `cwd` ([prompt ownership](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)).
+Each step assembles ordered prompt sections, tool schemas, and variables; unknown references fail the turn. `dsh-system-prompt` owns identity and persona, while the loop supplies `model` and `cwd` ([prompt ownership](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)).

-Tool-time context—including async `agent.inject()` notices and post-tool `additionalContexts`—settles, then follows recorded results. Steering drains before `agent/post-step`, which observes durable output, results, context, and steering before signal closure. Leftovers become queued input. Terminal `agent/turn-stop` runs after continuation and steering folding, stays authoritative through turn close and flush, and discards later steering but preserves queued prompts.
+Tool-time context settles after recorded results. Steering drains before `agent/post-step`; leftovers become queued input. Terminal `agent/turn-stop` runs after continuation and steering folding, stays authoritative through flush, and discards later steering while preserving queued prompts.

 Pruning precedes summaries; overflow retries require durable progress. Bounded transient retries compose on `agent/request-error`; cancellation wins ([compaction](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md), [retry](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)).

 ### Failure Boundaries

-The turn is the containment boundary. Adapter failures close the step, entering `agent/request-error` with the exact `Error`, `LlmFailure`, and retry history. Retry opens a numbered step; success clears history; exhaustion stores the failure on `turn/end`. Failed chunks commit no message or tool.
+The turn is the containment boundary. Adapter failures close the step and enter `agent/request-error` with exact failure facts. Retry opens a numbered step; exhaustion stores the failure on `turn/end`. Failed chunks commit no message or tool.

 Other failures use `agent/error`. Cancellation and disposal beat recovery; undispatched model tool calls receive synthetic `tool/call` and `ABORTED` result pairs before `turn/end`. `cancel()` clears queues and aborts active work; disposal awaits quiescence before unregistering.

@@ -123,11 +126,11 @@ Every session event is turn-enclosed. Reloading preserves an interrupted tail an

 ### Agent Handles

-`ctx.agents` owns live agents and returns `AgentHandle { agent, dispose() }`. Plugins drive `Agent` through `send()`, `steer()`, `inject()`, `cancel()`, and `whenIdle()`. The caller fiber and factory provider structurally co-own programmatic lifecycles; the consumer handle is the only other teardown capability. All owners await one disposer.
+`ctx.agents` owns live agents and returns `AgentHandle { agent, dispose() }`. Plugins use `send()`, `steer()`, `inject()`, `cancel()`, and `whenIdle()`. The caller fiber, factory provider, and consumer handle co-own teardown through one awaited disposer.

 ### Agent Scope

-Every live agent owns a scoped `agent.ctx`. Its registrations shadow globals, receive only that agent's dispatches, and unwind with it; async effects such as background-task cleanup are awaited. `CreateAgentOptions.setup(agentCtx)` composes the scope before publication. Typed resolvers derive carrier checks from merged `Events` signatures and `scopeTarget` ([semantic gates](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)). See [agent scope](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md) and [subagent composition controls](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md). `AgentLoop` runs drivers inside `ctx.agents.withInitiator()`; private orchestration derives `agent.session`; other identities stay explicit ([decision](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
+Every live agent owns a scoped `agent.ctx`. Registrations shadow globals, receive only that agent's dispatches, and unwind with it; async cleanup is awaited. `CreateAgentOptions.setup(agentCtx)` composes before publication. Typed resolvers derive carrier checks from merged `Events` signatures and `scopeTarget` ([semantic gates](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)). See [agent scope](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md) and [subagent composition](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md). `AgentLoop` propagates its initiator; private orchestration derives `agent.session`, while other identities stay explicit ([decision](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).

 ## State

@@ -139,11 +142,13 @@ The session log is the source of truth. `deriveMessages()` projects session even

 Durability is a plugin concern. Backends buffer synchronous `session/event` notifications; the loop awaits a turn-end checkpoint. `SessionPersistence` stores `SessionEvent` directly and metadata in `SessionHeader`; JSONL defaults to checksummed Zstandard, with SQLite under one contract.

+Plugin-owned log-only events may opt into `ctx.sessions.appendOutOfBand()`: they join an open turn or receive a balanced, flushed zero-step turn. `session/title` uses that path as a latest-wins fold with source-message seqs and provenance. Its first-message fallback is immediate; at most one optional provider may replace it asynchronously without delaying the agent response. Forks inherit logged titles unchanged ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
+
 ### Model Content

 Messages contain typed blocks (`text`, `reasoning`, `tool-call`, `tool-result`) derived from merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types coordinate adapters, UI bridges, compaction pricing, token metering, and persistence as one repo-wide contract; replay measurement types live in [token-meter.md](core-data-structures/token-meter.md).

-Streaming uses raw chunks and `BlockAssembler`. One `LlmAdapter.stream()` is one provider attempt; adapters report facts, while recovery policy lives on `agent/request-error`. The loop logs chunks and successful provenance/replay state. Remote adapters stop stalled transport with per-read idle watchdogs. Replay state reaches targets only when routes share an adapter instance ([contract](core-data-structures/llm-streaming.md)).
+Streaming uses raw chunks and `BlockAssembler`. One `LlmAdapter.stream()` is one provider attempt; adapters report facts, while recovery lives on `agent/request-error`. The loop logs chunks and successful provenance/replay state. Remote adapters use per-read idle watchdogs. Replay state reaches targets only when routes share an adapter instance ([contract](core-data-structures/llm-streaming.md)).

 ## Extension And Composition

@@ -151,13 +156,13 @@ Streaming uses raw chunks and `BlockAssembler`. One `LlmAdapter.stream()` is one

 A swappable capability usually splits into **interface / implementation / consumer**: the interface owns its `ctx` key and events, an implementation registers a backend, and a consumer exposes model behavior through tools or prompts. Bash is the reference; the [capability graph](capability-seams.md) shows every family.

-Some seams bend the template deliberately: LLM combines interface and consumer because adapters implement it; filesystem wraps provider primitives with policy; web keeps search/fetch provider registries behind one service; skills and subagents use named providers. Subagents spawn fresh, fork a completed-turn prefix, or use ACP children ([subagent.md](core-data-structures/subagent.md)).
+Some seams bend the template: LLM combines interface and consumer; filesystem wraps providers with policy; web, skills, and subagents own registries. Session titles pair a built-in fallback with a single-provider registry and shared LLM helper. Subagents spawn fresh, fork a completed-turn prefix, or use ACP children ([subagent.md](core-data-structures/subagent.md)).

 `dsh-workspace-context` composes baselines on `agent/session-prefix` and appends `ctx.fs`-discovered nested changes on `tools/post-execute`; its [decision](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) records isolation. `dsh-paths` owns shared paths.

 ### Bundles And Apps

-`dsh-agent-spine-demo` bundles the default spine ([README](../packages/examples/agent-spine-demo/README.md)). `dsh-tui-demo` owns the interactive full-screen terminal; `dsh-cli-demo` runs one persisted headless turn with format-pure stdout; `dsh-acp-demo` adds stdout-pure ACP over JSON-RPC ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK supplies its default only without an explicit config channel and drives `dsh-jsonrpc` over line-delimited JSON-RPC ([Python SDK](../python/README.md)). Deployments remain thin leaves with swappable backends and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
+`dsh-agent-spine-demo` bundles the default spine, including fallback-only session titles; model title providers remain opt-in ([README](../packages/examples/agent-spine-demo/README.md)). `dsh-tui-demo` owns the terminal; `dsh-cli-demo` runs one persisted headless turn; `dsh-acp-demo` adds stdout-pure ACP ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK supplies a default only without an explicit config and drives line-delimited JSON-RPC ([Python SDK](../python/README.md)). Deployments remain thin leaves with swappable backends and optional tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).

 ### Where New Behavior Goes

@@ -175,6 +180,7 @@ New behavior should attach to a documented extension point; changing the shipped
 | Add a session-stable request prefix outside history | compose it on `agent/session-prefix`, once per loop instance; logged on the request header |
 | Add UI or editor integration | drive `ctx.agents` and render from `session/event` |
 | Add durable session state | add a `SessionEventMap` member and render/replay from the log |
+| Add asynchronous session-title generation | register the sole provider on `ctx.sessionTitle` |
 | Fork a live session | use `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | Scope a tool, prompt section, or listener to ONE agent | register it through that agent's `agent.ctx` (see Agent Scope) |

--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -0,0 +1,195 @@
+# DeepSeek Harness 架构
+
+[English](architecture.md) | 中文
+
+**DeepSeek Harness SDK** 基于 Cordis 构建 agent harness（智能体框架）。设计准则很简单：**一切皆插件**。已交付的循环只是一个插件，并非拥有特权的内核。
+
+## 概览
+
+一个 harness 对应一个 [Cordis](cordis-primer.md) 上下文。各包（package）会添加服务（`ctx.llm`、`ctx.tools`、`ctx.sessions`、`ctx.sessionTitle`）、类型化事件（`agent/request`、`tools/pre-execute`、`session/event`）和可释放的注册项。
+
+`packages/core/` 汇集默认的 agent 流程；外围功能同样都是一等的 Cordis 插件。
+
+### 默认服务
+
+| ctx 键 | 包 | 职责 |
+|---|---|---|
+| — | [`dsh-scope`](../packages/core/scope/README.md) | 作用域上下文注册原语（库） |
+| `ctx.sessions` | `dsh-session` | 内存中的事件溯源会话 |
+| `ctx.systemPrompt` | `dsh-system-prompt` | 有序提示词片段、工具 schema 和提示词变量 |
+| `ctx.tools` | `dsh-tools` | 工具注册表和[执行流水线](tool-execution-pipeline.md) |
+| `ctx.agents` | `dsh-agent` | 活跃 agent、委托创建、`agent/*` 事件和进程内发起方作用域 |
+| `ctx.agentLoop` | `dsh-agent-loop` | 实体 `Agent` 驱动器 |
+
+### 功能服务
+
+| ctx 键 | 包族 | 职责 |
+|---|---|---|
+| `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
+| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力和会话表面压力 |
+| `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
+| `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | 同一执行环境内的进程限制（argv 包装、逐调用策略） |
+| `ctx.sandboxPolicy` | [`sandbox/`](../packages/sandbox/README.md) | 共享沙箱策略归属点 |
+| `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | 执行模型编写的程序 |
+| `ctx.fs` | [`fs/`](../packages/fs/README.md) | 文件系统提供方原语和策略事件 |
+| `ctx.skills` | [`skill/`](../packages/skill/README.md) | skill（技能）提供方注册表和渐进式披露 |
+| `ctx.web` | [`web/`](../packages/web/README.md) | 搜索与抓取提供方注册表 |
+| `ctx.compact`，`ctx.toolResultPrune` | [`compact/`](../packages/compact/README.md)/[`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune/README.md) | 摘要压缩（compaction）；可选的无模型结果裁剪 |
+| `ctx.subagents` | [`subagent/`](../packages/subagent/README.md) | 具名委托提供方 |
+| `ctx.tasks` | [`tasks/`](../packages/tasks/README.md) | 后台任务注册表和通用 `task_*` 控制工具 |
+| `ctx.workflows` | [`workflow/`](../packages/workflow/README.md) | 脚本驱动的多 agent 编排 |
+| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | 会话日志的持久存储 |
+| `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | 实时优先的逻辑语料精确读取和关系追踪 |
+| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | 基于日志的回退标题和单个可选异步提供方 |
+
+## 事件
+
+事件构成服务的扩展 API；完整清单见[事件目录](cordis-catalog/events.md)和[生产方与消费方映射](event-producer-consumer.md)。
+
+### 事件域
+
+- **会话事件**是追加到日志并通过 `session/event` 发出的持久事实。
+- **Agent 事件**携带活跃 `Agent`，用于状态、提示词准入、请求塑形、验证和续跑。
+- **功能事件**让所属服务边界无需导入循环即可附加策略和适配器。
+
+### 拦截语义
+
+waterfall（瀑布式事件）的行为类似环绕中间件：监听器调用 `next()` 即表示委托，直接返回而不调用它则会否决或接管。完整规则见 [Cordis waterfall 语义](cordis-primer.md#cordis-waterfall-semantics)。
+
+## 默认循环生命周期
+
+已交付的循环通过插件可见的服务和事件，持续处理从提示词到检查点的工作。
+
+**会话**是仅追加日志。每个普通**轮次**领取一项已排队的 `send()` 输入；注入不领取输入。后续轮次会等待上一项已领取轮次的检查点，但可以与其共用同一个 `running` 区间（[决策](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)）。模型和插件停止轮次时，该轮次结束。一个**步骤**包含一次模型请求及其工具。下文（[时序配套文档](agent-lifecycle.md)）用引号标记持久事件。
+
+未提供 id 时会生成 `<config-id>-session-<uuid>`；`sessionId` 用于恢复或创建会话，而 `resumeSessionId` 要求已有历史。恢复流程在发布前还原沿袭关系和委托深度。设置失败会发出 `agent-loop/config-start-failed`；拆卸过程保持静默。
+
+### 轮次流程
+
+```text
+choose declarative identity and fresh/resume path
+  -> prepare private session + agent.ctx -> await unpublished setup
+  -> enter session + agent -> session/created -> agent/created
+  -> enable driving -> agent/session-start(source) -> start driver
+forever:
+  wait for a queued message
+  emit agent/status(running)
+  TURN:
+    'turn/start'
+    claimed message -> agent/prompt-submit
+      allowed prompt -> 'user/message' plus injected context
+      blocked prompt -> 'prompt/blocked' -> 'turn/end'(rejected)
+    STEP loop:
+      drain steering
+      assemble system prompt and tool schemas
+      agent/session-prefix (first step)
+      agent/pre-step
+      snapshot the derived messages (the reconstruction boundary)
+      'step/start'
+      agent/request (config only) -> log request/header -> llm/stream (frozen)
+      on final adapter-path or terminal in-band failure:
+        'step/end'
+        agent/request-error(original error, failure facts, immutable prior failures, signal)
+        retry in the next numbered step or preserve the original error
+      otherwise:
+        'assistant/chunk'
+        agent/step-result
+        'assistant/message' (transformed content or empty success anchor after step-result rejection)
+        schedule tool calls by ctx.tools.executionMode:
+          exclusive -> one-call barrier
+          parallel -> rolling pool, <= maxParallelToolCalls in flight; reclassify before start
+          each start -> 'tool/call' -> ordered tools/pre-execute -> concurrent tools/execute
+          each model-order result -> ordered tools/post-execute -> 'tool/result'
+        append accepted tool-batch context after all recorded results, then steering
+        agent/post-step
+        'step/end'
+        agent/turn-continuation
+        agent/turn-stop (terminal policy)
+        stop unless tools or continuation policy ask for another step
+    'turn/end'
+    checkpoint persistence and notify idle/running status
+```
+
+每个步骤都会组装有序提示词片段、工具 schema 和变量；未知引用会使该轮次失败。`dsh-system-prompt` 负责身份和角色设定，循环则提供 `model` 和 `cwd`（[提示词归属](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)）。
+
+工具执行阶段的上下文会在结果记录后稳定。steering（中途引导）在 `agent/post-step` 前排空；余留内容会成为排队输入。终止型 `agent/turn-stop` 在续跑判断和 steering 折叠后执行，在整个刷写期间保持最终决定权，并丢弃后续 steering，同时保留排队提示词。
+
+裁剪先于摘要；溢出重试必须取得持久进展。有界的瞬态重试在 `agent/request-error` 上组合；取消优先（[压缩](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)、[重试](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)）。
+
+### 失败边界
+
+轮次是故障隔离边界。适配器故障会关闭步骤，并携带准确的故障事实进入 `agent/request-error`。重试会开启一个有编号的步骤；重试耗尽后，故障存入 `turn/end`。失败分片不会提交任何消息或工具。
+
+其他故障使用 `agent/error`。取消和 dispose（资源释放）优先于恢复；尚未分派的模型工具调用会收到合成的 `tool/call` 与 `ABORTED` 结果对，然后才出现 `turn/end`。`cancel()` 会清空队列并中止活跃工作；资源释放会等待系统停稳后再注销。
+
+每个会话事件都包围在轮次内。重新加载会保留中断的日志尾部，并用合成的 `interrupted` 轮次结束事件将其闭合。持久轮次关闭后的故障只通过 `agent/error` 报告，因为此时已没有安全的轮次内位置。每个轮次有一个 `TurnEndReason`；各变体由 [TurnEndReasonMap](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap) 统一定义。
+
+### Agent 句柄
+
+`ctx.agents` 拥有活跃 agent，并返回 `AgentHandle { agent, dispose() }`。插件使用 `send()`、`steer()`、`inject()`、`cancel()` 和 `whenIdle()`。调用方 fiber、工厂提供方和消费方句柄通过同一个需等待完成的 disposer 共同拥有拆卸过程。
+
+### Agent 作用域
+
+每个活跃 agent 都拥有一个作用域化的 `agent.ctx`。注册项会遮蔽全局项，只接收发往该 agent 的分派，并随 agent 一同撤销；系统会等待异步清理。`CreateAgentOptions.setup(agentCtx)` 在发布前完成组合。类型化解析器从合并后的 `Events` 签名和 `scopeTarget` 推导载体检查（[语义门禁](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)）。参见 [agent 作用域](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md)和 [subagent 组合](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)。`AgentLoop` 会传播其发起方；私有编排会派生 `agent.session`，其他身份则保持显式（[决策](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)）。
+
+## 状态
+
+### 会话日志
+
+会话日志是真源。`deriveMessages()` 将会话事件投影为发送给模型的 `Message[]`；原始 `assistant/chunk` 事件留在日志中，以保证回放和 UI 保真。回放、fork、恢复、transcript（文本记录）渲染、遥测和持久化均派生自同一个事件流。
+
+**模型可见 ⟺ 已记录**：日志可以重建每个请求，包括由请求头会话前缀置于开头的 `step/start` 时消息，以及通过折叠 `request/header` 得到的请求头；开发期不变量会断言这一点（[可重建性](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)）。
+
+持久性由插件负责。后端会缓冲同步的 `session/event` 通知；循环等待轮次结束检查点。`SessionPersistence` 直接存储 `SessionEvent`，并将元数据存入 `SessionHeader`；JSONL 默认采用带校验和的 Zstandard，SQLite 则遵循同一契约。
+
+插件所属的纯日志事件可选择使用 `ctx.sessions.appendOutOfBand()`：事件会加入开放轮次，或获得一个平衡且已刷写的零步骤轮次。`session/title` 采用该路径并以后写覆盖方式折叠，同时记录源消息 seq 和来源信息。其首消息回退标题会立即产生；至多一个可选提供方可以异步替换该标题，而不会延迟 agent 响应。fork 会原样继承已记录的标题（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
+
+### 模型内容
+
+消息包含类型化块（`text`、`reasoning`、`tool-call`、`tool-result`），这些块从可合并扩展的 `ContentBlockMap` 派生；`MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 也采用同一模式定义类型。新增块类型会将适配器、UI 桥接、压缩计价、token 计量和持久化协调成一项全仓库契约；回放计量类型见 [token-meter.md](core-data-structures/token-meter.md)。
+
+流式输出使用原始分片和 `BlockAssembler`。一次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告事实，恢复逻辑则位于 `agent/request-error`。循环会记录分片及成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。只有当路由共用同一个适配器实例时，回放状态才会到达目标（[契约](core-data-structures/llm-streaming.md)）。
+
+## 扩展与组合
+
+### 功能模式
+
+可替换功能通常拆分为**接口／实现／消费方**：接口拥有自己的 `ctx` 键和事件，实现负责注册后端，消费方通过工具或提示词暴露模型行为。Bash 是参考实现；[功能图](capability-seams.md)展示了所有包族。
+
+有些服务边界会调整这一模板：LLM（大语言模型）合并接口和消费方；文件系统以策略包装提供方；web、skill 和 subagent 拥有注册表。会话标题将内置回退方案与单提供方注册表和共享 LLM 辅助组件配对。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀，或使用 ACP（Agent Client Protocol）子 agent（[subagent.md](core-data-structures/subagent.md)）。
+
+`dsh-workspace-context` 在 `agent/session-prefix` 上组合基线，并在通过 `ctx.fs` 发现嵌套变更后，于 `tools/post-execute` 追加这些变更；其[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)记录了隔离方式。`dsh-paths` 负责共享路径。
+
+### 组合包与应用
+
+`dsh-agent-spine-demo` 组合默认主干，其中包含仅提供回退行为的会话标题；模型标题提供方保持按需启用（[README](../packages/examples/agent-spine-demo/README.md)）。`dsh-tui-demo` 负责终端；`dsh-cli-demo` 运行一个持久化的无界面轮次；`dsh-acp-demo` 添加保持 stdout 纯净的 ACP（[ui/](../packages/ui/README.md)）。`dsh-jsonrpc-agent` 启动外部 `cordis.yml`；Python SDK 仅在没有显式配置时提供默认项，并驱动按行分隔的 JSON-RPC（[Python SDK](../python/README.md)）。部署保持为轻量叶节点，使用可替换后端和可选工具（[examples/](../examples/AGENTS.md)、[可运行接线](cookbook/extension-cookbook.md#runnable-wirings)、[图谱](graph-atlas.md)）。
+
+### 新行为的归属位置
+
+新行为应附加到已有文档记录的扩展点；修改已交付的循环时，必须同步更新本架构图。
+
+| 目标 | 机制 |
+|---|---|
+| 添加模型提供方 | 在 `ctx.llm` 上注册适配器 |
+| 添加面向模型的功能 | 在 `ctx.tools` 上注册工具；schema 会进入提示词组装流程 |
+| 添加命令执行 | 实现并注册 `ctx.bash` 后端 |
+| 添加长时间运行或后台功能 | 在 `ctx.tasks` 上注册工作；通用 `task_*` 工具负责收集或停止 |
+| 添加文件系统访问或策略 | 实现 `ctx.fs` 提供方，或监听 `fs/*` 策略事件 |
+| 限制生成的进程 | 使用 `ctx.sandbox` 后端；消费方在生成进程前包装 argv |
+| 拦截提示词、请求、模型完成或失败、工具使用或续跑 | 监听相应的 `agent/*` 或 `tools/*` 事件；使用串行 `agent/turn-stop` 实现单调终止 |
+| 添加历史记录之外的会话稳定请求前缀 | 在 `agent/session-prefix` 上组合，每个循环实例一次；记录在请求头中 |
+| 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染 |
+| 添加持久会话状态 | 添加一个 `SessionEventMap` 成员，并从日志渲染和回放 |
+| 添加异步会话标题生成 | 在 `ctx.sessionTitle` 上注册唯一提供方 |
+| fork 活跃会话 | 使用 `ctx.sessions.fork(source, boundary?, childSessionId?)` |
+| 将工具、提示词片段或监听器限定到单个 agent | 通过该 agent 的 `agent.ctx` 注册（参见 Agent 作用域） |
+
+[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)提供插件骨架和功能到服务边界的映射；分步指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
+
+## 快速参考
+- [术语表](glossary.md)中的领域术语
+- [core-data-structures/](core-data-structures/core.md) 中的类型定义
+- [事件](cordis-catalog/events.md)中的准确事件与服务签名
+- [服务](cordis-catalog/services.md)目录
+- [包索引](../packages/README.md)中的包契约
+- [Agent Note（agent 决策记录）](../.agents/notes/README.md)
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -34,6 +34,10 @@ flowchart LR
  pkg_hooks_codex["hooks-codex"]
  pkg_acp["acp"]
  svc_sessionQuery["ctx.sessionQuery<br/>Exact session-history reads and traces"]
+  pkg_session_title["session-title"]
+  svc_sessionTitle["ctx.sessionTitle<br/>Log-backed session titles"]
+  pkg_session_title_first_message_llm["session-title-first-message-llm"]
+  pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
  pkg_system_prompt["system-prompt"]
  svc_systemPrompt["ctx.systemPrompt<br/>System prompt assembly registry"]
  pkg_tools["tools"]
@@ -130,6 +134,9 @@ flowchart LR
  pkg_session_persistence_jsonl --> svc_sessionPersistence
  pkg_session_persistence_sqlite --> svc_sessionPersistence
  pkg_session_query --> svc_sessionQuery
+  pkg_session_title --> svc_sessionTitle
+  pkg_session_title_all_messages_llm --> svc_sessionTitle
+  pkg_session_title_first_message_llm --> svc_sessionTitle
  pkg_skill --> svc_skills
  pkg_skill_local --> svc_skills
  pkg_spill --> svc_spillStore
@@ -224,6 +231,7 @@ flowchart LR
 | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`acp`](../packages/ui/acp), [`session-query`](../packages/session-query/session-query) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | - | - | - | Resolves live and optional persisted logs into one logical corpus for exact reads and relationship traces. |
+| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session-title/session-title) | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -27,7 +27,7 @@ export interface AcpConfig {

 Depends on: `Stream` (`@agentclientprotocol/sdk`)

-Source: [`packages/ui/acp/src/index.ts:207`](../packages/ui/acp/src/index.ts)
+Source: [`packages/ui/acp/src/index.ts:209`](../packages/ui/acp/src/index.ts)

 ## `@deepseek-ai/dsh-acp-demo`

@@ -165,7 +165,7 @@ export interface SkillConfig {

 Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`llmRetry`](../packages/llm/llm-retry/src/index.ts) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/bash/tool-bash/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`toolTasks`](../packages/tasks/tool-tasks/src/index.ts) · [`workspaceContext`](../packages/context/workspace-context/src/index.ts)

-Source: [`packages/examples/agent-spine-demo/src/index.ts:60`](../packages/examples/agent-spine-demo/src/index.ts)
+Source: [`packages/examples/agent-spine-demo/src/index.ts:61`](../packages/examples/agent-spine-demo/src/index.ts)

 ## `@deepseek-ai/dsh-bash-local`

@@ -833,6 +833,50 @@ export interface Config {

 Source: [`packages/session-query/session-query/src/config.ts:9`](../packages/session-query/session-query/src/config.ts)

+## `@deepseek-ai/dsh-session-title`
+
+Requires: `sessions`
+
+```ts config-catalog
+/** Required deterministic fallback and accepted-title limits. */
+export interface Config {
+  /** Maximum whitespace-delimited words in the built-in fallback. */
+  readonly fallbackMaxWords: number
+  /** Maximum UTF-8 bytes in the built-in fallback. */
+  readonly fallbackMaxBytes: number
+  /** Maximum UTF-8 bytes in any accepted title. */
+  readonly maxTitleBytes: number
+}
+```
+
+Source: [`packages/session-title/session-title/src/index.ts:63`](../packages/session-title/session-title/src/index.ts)
+
+## `@deepseek-ai/dsh-session-title-all-messages-llm`
+
+Requires: `sessionTitle` · `llm`
+
+```ts config-catalog
+/** Required LLM policy; this plugin adds no defaults. */
+export type Config = SessionTitleLlmConfig
+```
+
+Depends on: [`SessionTitleLlmConfig`](../packages/session-title/session-title-llm/src/index.ts)
+
+Source: [`packages/session-title/session-title-all-messages-llm/src/index.ts:15`](../packages/session-title/session-title-all-messages-llm/src/index.ts)
+
+## `@deepseek-ai/dsh-session-title-first-message-llm`
+
+Requires: `sessionTitle` · `llm`
+
+```ts config-catalog
+/** Required LLM policy; this plugin adds no defaults. */
+export type Config = SessionTitleLlmConfig
+```
+
+Depends on: [`SessionTitleLlmConfig`](../packages/session-title/session-title-llm/src/index.ts)
+
+Source: [`packages/session-title/session-title-first-message-llm/src/index.ts:15`](../packages/session-title/session-title-first-message-llm/src/index.ts)
+
 ## `@deepseek-ai/dsh-skill`

 ```ts config-catalog
@@ -1277,7 +1321,7 @@ export interface TuiConfig {
 }
 ```

-Source: [`packages/ui/tui/src/index.ts:102`](../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/index.ts:103`](../packages/ui/tui/src/index.ts)

 ## `@deepseek-ai/dsh-tui-demo`

@@ -1560,6 +1604,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-retention` ([`packages/util/retention/src/index.ts`](../packages/util/retention/src/index.ts))
 - `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
 - `@deepseek-ai/dsh-scripts` ([`packages/sdk/scripts/src/index.ts`](../packages/sdk/scripts/src/index.ts))
+- `@deepseek-ai/dsh-session-title-llm` ([`packages/session-title/session-title-llm/src/index.ts`](../packages/session-title/session-title-llm/src/index.ts))
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
 - `@deepseek-ai/dsh-subagent-subprocess` ([`packages/subagent/subagent-subprocess/src/index.ts`](../packages/subagent/subagent-subprocess/src/index.ts))
 - `@deepseek-ai/dsh-telemetry` ([`packages/sdk/telemetry/src/index.ts`](../packages/sdk/telemetry/src/index.ts))
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -672,6 +672,13 @@ Live-preferred logical-corpus exact-read and relationship-tracing service.
 */
 listSessions(): Promise<SessionRecord[]>

+/**
+ * Fold the latest log-backed title from one live-preferred logical session.
+ * @param sessionId - live or persisted session id to read.
+ * @returns latest title snapshot, or `undefined` when the log has no title event.
+ */
+async readTitle(sessionId: SessionId): Promise<SessionTitleSnapshot | undefined>
+
 /**
 * List lightweight raw-log event records for one logical session.
 * @param sessionId - live-preferred session id to read.
@@ -703,9 +710,9 @@ async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>
 async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>
 ```

-Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventTrace](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md)
+Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventTrace](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)

-Source: [`packages/session-query/session-query/src/index.ts:38`](../../packages/session-query/session-query/src/index.ts)
+Source: [`packages/session-query/session-query/src/index.ts:40`](../../packages/session-query/session-query/src/index.ts)

 ## `ctx.sessions` — `SessionStore`

@@ -801,6 +808,28 @@ announce(session: Session): void
 */
 async flush(session: Session): Promise<void>

+/**
+ * Append one plugin-declared log-only event without borrowing the agent
+ * loop's lifecycle. An open turn receives the event directly and remains
+ * responsible for its ordinary checkpoint. A closed log receives one
+ * zero-step turn around the event, followed by an awaited flush.
+ *
+ * Once the synthetic `turn/start` commits, this method always attempts its
+ * matching `turn/end` and flush, including when the target append fails.
+ * Detachment requested by an event or flush listener is deferred until that
+ * sequence settles, so publication cannot switch from a live scoped session
+ * to an unobserved bare `Session` halfway through the update.
+ *
+ * @param session - exact live session that owns the target log.
+ * @param type - event type opted into {@link OutOfBandSessionEventMap} by its owner.
+ * @param data - typed JSON payload for the target event.
+ * @param trigger - plugin-owned turn trigger used only when the log is closed.
+ * @returns the accepted target event with its assigned sequence and timestamp.
+ * @throws when the session is detached, another out-of-band append is active,
+ *   event acceptance fails, the synthetic turn cannot close, or flushing fails.
+ */
+async appendOutOfBand<T extends OutOfBandSessionEventType>( session: Session, type: T, data: SessionEventMap[T], trigger: TurnTrigger, ): Promise<SessionEvent<T>>
+
 /**
 * Look up a live session.
 * @param id - the session id to look up.
@@ -830,9 +859,43 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```

-Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
+Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [OutOfBandSessionEventType](../core-data-structures/session.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md) · [SessionEventMap](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md) · [TurnTrigger](../core-data-structures/session.md)

-Source: [`packages/core/session/src/index.ts:553`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:554`](../../packages/core/session/src/index.ts)
+
+## `ctx.sessionTitle` — `SessionTitleService`
+
+Log-backed title fold plus asynchronous fallback generation.
+
+```ts cordis-catalog
+/**
+ * Read the latest folded title from one live or replayed session.
+ * @param session - session whose log is the title source of truth.
+ * @returns latest title snapshot, or `undefined` before eligible input.
+ */
+get(session: Session): SessionTitleSnapshot | undefined
+
+/**
+ * Explicitly retry the registered provider, or materialize the built-in
+ * fallback when no provider is registered.
+ * @param session - exact live session to refresh.
+ * @param signal - optional caller cancellation.
+ * @returns latest accepted title, or `undefined` when no eligible text exists.
+ */
+async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Register the sole optional title provider. Disposal aborts its pending and
+ * active work before another provider may register.
+ * @param provider - provider identity, cadence, and generation function.
+ * @returns exact Cordis effect disposer for HMR-safe unregistration.
+ */
+register(provider: SessionTitleProvider): () => void
+```
+
+Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](../core-data-structures/session-title.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
+
+Source: [`packages/session-title/session-title/src/index.ts:233`](../../packages/session-title/session-title/src/index.ts)

 ## `ctx.skills` — `SkillService`

--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -21,6 +21,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, the turn-enclosure invariant |
 | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
 | [session-query.md](session-query.md) | logical records, bounded exact-event reads, and relationship traces |
+| [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
 | [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
 | [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
--- a/docs/core-data-structures/session-title.md
+++ b/docs/core-data-structures/session-title.md
@@ -0,0 +1,118 @@
+# Session Titles
+
+Durable latest-wins title state and the optional asynchronous provider vocabulary owned by [`@deepseek-ai/dsh-session-title`](../../packages/session-title/session-title). The package README owns timing, fallback, failure, and fork behavior; the generated [persistence catalog](../persistence-catalog.md) owns the complete `session/title` event declaration.
+
+Source: [`packages/session-title/session-title/src/index.ts`](../../packages/session-title/session-title/src/index.ts)
+
+## Durable title state
+
+`SessionTitleProviderId` is recorded for provider-produced revisions. `SessionTitleEventData` carries exact human-message provenance, while `SessionTitleSnapshot` adds the durable event envelope facts selected by `foldSessionTitle()`.
+
+```ts type-equiv
+/** Identifies one session-title provider registration. */
+type SessionTitleProviderId = Branded<'SessionTitleProviderId'>
+```
+
+```ts type-equiv
+/** Exact auxiliary model route that produced a title. */
+interface SessionTitleModelProvenance {
+  /** Registered LLM provider route. */
+  readonly provider: string
+  /** Provider model id. */
+  readonly model: string
+}
+```
+
+```ts type-equiv
+/** Durable ownership record for an accepted session title. */
+type SessionTitleSource =
+  | { readonly kind: 'fallback' }
+  | {
+    readonly kind: 'provider'
+    readonly provider: SessionTitleProviderId
+    readonly model?: SessionTitleModelProvenance
+  }
+```
+
+```ts type-equiv
+/** Payload of the log-only `session/title` event. */
+interface SessionTitleEventData {
+  /** Normalized non-empty title text. */
+  readonly title: string
+  /** Exact human `user/message` seqs used to derive this title. */
+  readonly messageSeqs: number[]
+  /** Built-in fallback or registered-provider provenance. */
+  readonly source: SessionTitleSource
+}
+```
+
+```ts type-equiv
+/** Latest folded title plus the title event's durable envelope facts. */
+interface SessionTitleSnapshot extends SessionTitleEventData {
+  /** Seq of the latest `session/title` event. */
+  readonly eventSeq: number
+  /** Timestamp of the latest `session/title` event. */
+  readonly updatedAt: number
+}
+```
+
+## Provider input and output
+
+The service snapshots eligible messages through one revision. A provider returns only seqs from that request; service-owned acceptance verifies ordering, normalizes the title, enforces the byte limit, and appends provenance.
+
+```ts type-equiv
+/** One eligible human text message exposed to title providers. */
+interface SessionTitleUserMessage {
+  /** Source `user/message` event seq. */
+  readonly seq: number
+  /** Exact concatenated text-block content. */
+  readonly text: string
+}
+```
+
+```ts type-equiv
+/** Automatic generation cadence owned by a registered provider. */
+type SessionTitleAutomaticMode = 'first-message' | 'all-user-messages'
+```
+
+```ts type-equiv
+/** Immutable input supplied to one title-provider call. */
+interface SessionTitleProviderRequest {
+  /** Live session being titled. */
+  readonly session: Session
+  /** All eligible human messages through this generation revision. */
+  readonly messages: readonly SessionTitleUserMessage[]
+  /** Exact current logged main-request route, when one has been recorded. */
+  readonly route?: SessionTitleModelProvenance
+  /** Cancellation for supersession, disposal, timeout composition, or the explicit caller. */
+  readonly signal: AbortSignal
+}
+```
+
+```ts type-equiv
+/** Provider output before service-owned normalization and durable acceptance. */
+interface SessionTitleProviderResult {
+  /** Proposed title text. */
+  readonly title: string
+  /** Exact seqs from `request.messages` used by this result. */
+  readonly messageSeqs: readonly number[]
+  /** Auxiliary LLM route, when generation used a model. */
+  readonly model?: SessionTitleModelProvenance
+}
+```
+
+```ts type-equiv
+/** One optional asynchronous title implementation registered with the service. */
+interface SessionTitleProvider {
+  /** Stable provider identity recorded in title provenance. */
+  readonly id: SessionTitleProviderId
+  /** When new human prompts start automatic generation. */
+  readonly automatic: SessionTitleAutomaticMode
+  /**
+   * Produce one title revision.
+   * @param request - message snapshot, current route, session, and cancellation.
+   * @returns proposed title plus exact input seqs and optional model provenance.
+   */
+  generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
+}
+```
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -94,6 +94,20 @@ interface SessionEventMap {
 }
 ```

+### `OutOfBandSessionEventMap` — narrow late-append opt-in
+
+`SessionEventMap` membership alone does not authorize an event outside the agent loop's ordinary lifecycle. An event owner declaration-merges the same key into this empty marker map before `ctx.sessions.appendOutOfBand()` accepts it; the derived type additionally excludes every surface event. An accepted update joins an open turn or receives a balanced, flushed zero-step turn.
+
+```ts type-equiv
+/**
+ * Marker map for plugin-owned log-only events accepted by
+ * `SessionStore.appendOutOfBand()`. A plugin extends this map with the same key
+ * it adds to {@link SessionEventMap}; surface and lifecycle events stay
+ * ineligible unless their owner explicitly opts them into this narrow seam.
+ */
+interface OutOfBandSessionEventMap {}
+```
+
 ### `TodoItem` — one todo-list entry

 The unit of the `todo/write` event's whole-list snapshot. Deliberately minimal — a `content` line and a three-state `status` (no id, priority, or `activeForm`): the list is replaced wholesale on every write, so entries need no stable identity, and the status triple is exactly the ACP `PlanEntryStatus`, so a UI bridge can map a todo list onto an ACP `plan` 1:1 (synthesizing the priority ACP additionally requires). See the [todo_write Agent Note](../../.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md).
@@ -501,7 +515,7 @@ interface TurnEndReasonMap {

 ## The turn-enclosure invariant

-Every session event lives **inside** a turn (between a `turn/start` and its `turn/end`). The loop appends queued `user/message` events *after* `turn/start`, and an idle `agent.inject()` wraps its `context/message` in a one-shot `injection` turn. This makes the turn the single durability/replay boundary: a backend can treat anything after the last `turn/end` as an interrupted-crash tail without risking the loss of legitimately-recorded between-turn context. The `dsh-invariants` plugin enforces it in dev (a message event outside an open turn throws). See [the turn-enclosure invariant Agent Note](../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md).
+Every session event lives **inside** a turn (between a `turn/start` and its `turn/end`). The loop appends queued `user/message` events *after* `turn/start`, an idle `agent.inject()` wraps its `context/message` in a one-shot `injection` turn, and `appendOutOfBand()` similarly wraps an eligible log-only event when no turn is open. This makes the turn the single durability/replay boundary: a backend can treat anything after the last `turn/end` as an interrupted-crash tail without risking the loss of legitimately-recorded between-turn context. The `dsh-invariants` plugin enforces it in dev (a message event outside an open turn throws). See [the turn-enclosure invariant Agent Note](../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md).

 ## Plugin-contributed log-only events

--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -29,8 +29,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:44`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`invariants`](../packages/support/invariants), [`llm-replay`](../packages/support/llm-replay) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`workspace-context`](../packages/context/workspace-context) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`workspace-context`](../packages/context/workspace-context) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:79`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:139`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:113`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -97,6 +97,12 @@ flowchart TD
  subgraph group_session_query["packages/session-query"]
    pkg_session_query["session-query"]
  end
+  subgraph group_session_title["packages/session-title"]
+    pkg_session_title["session-title"]
+    pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
+    pkg_session_title_first_message_llm["session-title-first-message-llm"]
+    pkg_session_title_llm["session-title-llm"]
+  end
  subgraph group_support["packages/support"]
    pkg_acp_snapshot["acp-snapshot"]
    pkg_agent_loop_testkit["agent-loop-testkit"]
@@ -194,6 +200,9 @@ flowchart TD
  pkg_spill --> pkg_llm
  pkg_spill --> pkg_session
  pkg_session_persistence --> pkg_session
+  pkg_session_title --> pkg_brand
+  pkg_session_title --> pkg_llm
+  pkg_session_title --> pkg_session
  pkg_llm_replay --> pkg_llm
  pkg_llm_replay --> pkg_session
  pkg_sandbox_local --> pkg_llm
@@ -227,6 +236,10 @@ flowchart TD
  pkg_session_query --> pkg_llm
  pkg_session_query --> pkg_session
  pkg_session_query --> pkg_session_persistence
+  pkg_session_query --> pkg_session_title
+  pkg_session_title_llm --> pkg_llm
+  pkg_session_title_llm --> pkg_session_title
+  pkg_session_title_llm --> pkg_timeout
  pkg_invariants --> pkg_agent
  pkg_invariants --> pkg_llm
  pkg_invariants --> pkg_scope
@@ -263,6 +276,12 @@ flowchart TD
  pkg_fs_sandbox --> pkg_fs_local
  pkg_fs_sandbox --> pkg_sandbox
  pkg_fs_sandbox --> pkg_sandbox_policy
+  pkg_session_title_all_messages_llm --> pkg_llm
+  pkg_session_title_all_messages_llm --> pkg_session_title
+  pkg_session_title_all_messages_llm --> pkg_session_title_llm
+  pkg_session_title_first_message_llm --> pkg_llm
+  pkg_session_title_first_message_llm --> pkg_session_title
+  pkg_session_title_first_message_llm --> pkg_session_title_llm
  pkg_permission --> pkg_bash
  pkg_permission --> pkg_sandbox
  pkg_permission --> pkg_sandbox_policy
@@ -347,6 +366,7 @@ flowchart TD
  pkg_acp --> pkg_sandbox
  pkg_acp --> pkg_session
  pkg_acp --> pkg_session_persistence
+  pkg_acp --> pkg_session_title
  pkg_acp --> pkg_system_prompt
  pkg_acp --> pkg_tools
  pkg_acp --> pkg_user_approval
@@ -407,6 +427,7 @@ flowchart TD
  pkg_tui --> pkg_llm
  pkg_tui --> pkg_llm_retry
  pkg_tui --> pkg_session
+  pkg_tui --> pkg_session_title
  pkg_tui --> pkg_tools
  pkg_tui --> pkg_user_interaction
  pkg_agent_spine_demo --> pkg_agent
@@ -416,6 +437,7 @@ flowchart TD
  pkg_agent_spine_demo --> pkg_llm
  pkg_agent_spine_demo --> pkg_llm_retry
  pkg_agent_spine_demo --> pkg_session
+  pkg_agent_spine_demo --> pkg_session_title
  pkg_agent_spine_demo --> pkg_skill
  pkg_agent_spine_demo --> pkg_skill_local
  pkg_agent_spine_demo --> pkg_system_prompt
@@ -505,6 +527,7 @@ flowchart TD
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`session`](../packages/core/session) |
+| [`session-title`](../packages/session-title/session-title) | `session-title` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
@@ -518,7 +541,8 @@ flowchart TD
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`session`](../packages/core/session) |
 | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| [`session-query`](../packages/session-query/session-query) | `session-query` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| [`session-query`](../packages/session-query/session-query) | `session-query` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) |
+| [`session-title-llm`](../packages/session-title/session-title-llm) | `session-title` | [`llm`](../packages/llm/llm), [`session-title`](../packages/session-title/session-title), [`timeout`](../packages/util/timeout) |
 | [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
 | [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) |
@@ -528,6 +552,8 @@ flowchart TD
 | [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
+| [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | `session-title` | [`llm`](../packages/llm/llm), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
+| [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm) | `session-title` | [`llm`](../packages/llm/llm), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
 | [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`home`](../packages/util/home), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
@@ -542,7 +568,7 @@ flowchart TD
 | [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
 | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`user-interaction`](../packages/ui/user-interaction) |
+| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`user-interaction`](../packages/ui/user-interaction) |
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) |
@@ -554,8 +580,8 @@ flowchart TD
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -79,7 +79,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```

-Sources: [`packages/core/session/src/types.ts:267`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:274`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:304`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:336`](../packages/core/session/src/types.ts)
+Sources: [`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:288`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:318`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:350`](../packages/core/session/src/types.ts)

 ## Events

@@ -376,6 +376,22 @@ Source: [`packages/core/session/src/types.ts:263`](../packages/core/session/src/

 Source: [`packages/sandbox/sandbox-policy/src/session-mode.ts:34`](../packages/sandbox/sandbox-policy/src/session-mode.ts)

+### `session/*`
+
+#### `session/title` — log-only
+
+```ts persistence-catalog
+/**
+ * Latest-wins session title snapshot. Log-only: it never enters the model
+ * surface or derived history.
+ */
+'session/title': SessionTitleEventData
+```
+
+Types: [SessionTitleEventData](core-data-structures/session-title.md)
+
+Source: [`packages/session-title/session-title/src/index.ts:89`](../packages/session-title/session-title/src/index.ts)
+
 ### `steering/*`

 #### `steering/message` — surface