@@ -1,199 +0,0 @@
# Agent Note: subagent 列表经投影单元读取身份
Status: proposed
[English ](2026-08-06-subagent-list-identity-projection.md ) | 中文
## 问题
`SubagentService.listChildren` （ list-children.ts ](../../../../packages/subagent/subagent/src/list-children.ts )）对每个 `header.origin === 'subagent'` 的直接 child， `listEvents` 加 `readEvent` 两次整日志物化，且每次物化都伴随整日志 structuredClone， ， × × `list_agents` 以 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 整体拒绝，尽管枚举所需只是 header 事实。
同一根因还有第二个症状： `hasSubagentDescriptor()` （ api-proxy.ts ](../../../../packages/host/apiproxy/src/api-proxy.ts )）在每次 Agent 绑定 RPC 的属主判定上扫描目标会话的 own suffix， `SessionHeader.origin` 已经回答了同一个问题的绝大部分。
根因在于 [durable-subagent-catalog 决策 ](../../implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md )把描述符事件（`subagent/descriptor` ）定为目录的唯一持久权威，却没有为描述符读取配任何缓存层，并把逐 child 双读明确接受为"无索引的正确性基线"。[web subagent conversations ](../../implemented/feature/2026-07-27-web-subagent-conversations.md )（ #1569 ）已把"是不是 subagent"放进了 header（ `SessionHeader.origin` ） ， ；
## 提案
mode 与 label 由新的 `subagent` projection unit（ ） ， `listChildren` 摘除 session-query 依赖——枚举由 subagent 自管的 live-preferred 合并完成，取值走 live/cold 两级"算完即止"阶梯： （ ） ， `persistence.inspect` 整读加 `registry.restore` 折叠。无索引、无缓存、无回写。
消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（ ） ； （ ， ） ； （ ， ， ： ， ，
方案要点：
- **subagent 列表不再依赖 session-query**：枚举由 subagent 自管的 live-preferred 合并完成， `ctx.sessionProjections` 取值；没有 query backend 的部署照常列表。
- **取值两级"算完即止"阶梯**： `sessionProjections.snapshot()` （ ， ） ； `persistence.inspect` 整读加 `registry.restore({}, events, 0)` 折叠；再没有就没有——无缓存、无回写、无索引。
- **`subagent` projection unit 是折叠规则唯一权威**：
- **session-query 的净变化只剩读路径去 clone 加浅 readonly 借用视图**（ ；
- **header、描述符（ ） `inspect` 现算获得精确值，无 unknown 降级态、无迁移。
与既有记录的关系：
- 本记录取代 [durable-subagent-catalog ](../../implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md ) 中列表读路径的两项设计：经 `sessionQuery.traceSession` 枚举，与逐 child 读取描述符事件（`listEvents` 加精确 `readEvent` 双读、就地诊断分类）
- [session-projection RFC ](2026-07-27-session-projection-and-command-log.md ) 的 registry 契约（`ProjectionDefinition` 、`snapshot` 、`restore` ）零改动，本记录只为其新增 `subagent` 身份 unit 一个注册项，并成为 snapshot（ ） （ ）
### `subagent` projection unit
挂在现有 `subagentTiming` 旁（[projection.ts ](../../../../packages/subagent/subagent/src/projection.ts )、[projection-types.ts ](../../../../packages/subagent/subagent/src/projection-types.ts )） ， `subagent` ：
```ts ignore-check
export type SubagentIdentityProjection =
| { mode: 'one-shot'; label?: string }
| { mode: 'continuable'; label: string }
declare module '@deepseek-ai/dsh-session-projection/types' {
interface SessionProjectionMap {
subagent: SubagentIdentityProjection
}
}
` ``
- 投影是纯身份，**projection 体系不做失败通道**： listChildren` 四态映射）。
- label 强度由描述符 schema 决定： ，
- 折叠规则：` subagent/descriptor` last-wins， subagentTiming` 同一条 descriptor-reset 纪律——fork 前缀里的祖先描述符被自身描述符覆盖。
### 枚举：
` listChildren` 的枚举不再经任何查询服务：` ctx.sessions.list()` 与 ` ctx.get('sessionPersistence')?.list()` 两个来源按 id 合并，
- 过滤：` header.origin === 'subagent' && header.parentSession === parentSessionId`。
- ` hasChildren`：同一份合并材料向下看一层——存在 ` origin === 'subagent'` 且 ` parentSession` 为该 child 的直接后代。
- ` activity`： running`，仅存在于持久化的为 ` inactive`。
- 排序：` createdAt` 升序、再按 child id 升序（与旧契约一致）。
- **persistence 缺席退为 live-only 枚举，不报错**：没有 persistence 的部署， ，
### 取值：两级"算完即止"阶梯
对每个枚举出的 child， session.history` 的冷读同款——算完即止，无缓存、无回写：
| 级 | 读法 | 成本 |
| --- | --- | --- |
| live child | ` ctx.sessionProjections.snapshot(session).values.subagent` | 零日志读——注册表既有水位缓存，同步取值 |
| cold child | ` persistence.inspect(id)` 整读 + ` registry.restore({}, events, 0).snapshot.values.subagent` | 每次列表一次整读现算 |
- 错误契约：` ctx.sessionProjections` 未挂载是配置错误，` listChildren` 在枚举前无条件检查并以 ` SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败——零 children 的部署同样确定失败，不因列表恰好为空而掩盖配置问题。` SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 随 session-query 依赖一并删除。
- per-child 隔离：单 child 的 cold 整读失败只使该行成为 ` unavailable` diagnostic， （ ）
- 冷读成本如实记录： inspect()` 走 [Session 准备阶段](../../implemented/architecture/2026-08-05-session-preparation.md)的冷读，同 id 短期重复读取可命中其 LRU 复用，
### 权威模型
- session log 是唯一权威；本方案不新增任何派生持久化——没有索引值、没有 checkpoint、没有进程 memo， ，
- Session 与 persistence 写路完全不感知列表与投影消费：没有事件监听回写，没有写时折叠。
- 枚举与取值不构成第二个鉴权来源，也不让尚未发布的 child 可见——两个来源只见已发布的 live 记录与已落盘的持久化记录，与 durable-subagent-catalog 记录对派生读面立下的规则一致。
### ` listChildren` 行形状与消费面
` SubagentListEntry` **数据结构与今天完全一致**——child 与 diagnostic 两臂、` kind` 判别、reason 三值、child 臂的 mode/label 强契约全部保留； ： ，
` ``ts ignore-check
export type SubagentListEntry =
| ({
readonly kind: 'child'
readonly id: SessionId
readonly activity: 'running' | 'inactive'
readonly hasChildren: boolean
} & (
| { readonly mode: 'one-shot'; readonly label?: string }
| { readonly mode: 'continuable'; readonly label: string }
))
| {
readonly kind: 'diagnostic'
readonly id: SessionId
readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
}
` ``
实现形态：` listChildren` = 自管枚举（ origin` 过滤，全部来自 header 事实）+ 投影阶梯（ ） listEvents`、精确 ` readEvent`、描述符定位与就地分类机器整体删除。
对每个枚举出的 child， ：
| 阶梯取值结果 | 行 |
| --- | --- |
| 快照含 ` subagent` 值 | child 行 |
| 快照在、值缺席，且 child **inactive** | diagnostic 行， corrupt`（定局残骸：无、损坏或版本不认识的描述符，不再细分） |
| 快照在、值缺席，且 child **running** | 行不出现（创建窗口：描述符尚未追加，与旧实现同窗口 omit）
| cold 整读失败 | diagnostic 行， unavailable` |
- ` unsupported` 不再被产出：类型与 wire 枚举按"数据结构保持现状"留存该成员，本记录留档其为不再产出。
- descriptor-less 定局残骸从旧实现的 omit 归入 ` corrupt` diagnostic——库里的坏、死子会话可见， ，
已知边界偏差（有意接受，随本记录留档）：
- 死于发布窗口的 fork child， ， NOT_RESUMABLE`）。旧实现靠 ` seedLength` 过滤将其 omit； ， （ subagentTiming` 有同类既有暴露）。
- own suffix 出现多个描述符，旧实现判 corrupt， （
- live/persisted header 冲突，旧实现是 per-child corrupt；
- 损坏存储的源读失败（如坏 surface 被冷读整读拒收），旧实现映射 per-child ` corrupt`，现统一成 ` unavailable` 行（读侧无从区分成因）。
消费面： （ list_agents` 的 description 与 output schema 亦不动； sessionQuery`）。唯一动行为的是 apiproxy 路由段：删 ` hasSubagentDescriptor()` 扫描，` hasSubagentOwner` 只看 ` header.origin`——pre-#1569 的无 ` origin` 存量不再被认作 subagent 属主， ，
### 附带工作项：
- ` SessionCorpus.load()`、` snapshotLive`、` listSessions` 等移除 structuredClone： （ deepFreeze` 加 ` Object.freeze`），持久化读出的对象图为独占新建，克隆纯属浪费。
- 公开查询输出标注**浅 readonly**（顶层属性与数组位）；深只读化被实证否决（见替代方案），深层不可变由 core/session 的运行时深冻结事实保证，类型层面不再表达，` DeepReadonly` 不进任何公共包。
- 契约措辞与 ` projectMany` 的借用契约（"borrowed only for that call"）对齐：整个 corpus 面向消费方统一为"只读视图，不得留存可变引用"的不可变借用视图；需要留存的自行克隆。
### 改动面清单
| 区域 | 文件 | 改动 |
| --- | --- | --- |
| subagent | projection.ts、projection-types.ts、index.ts | 新 ` subagent` unit 与注册 |
| subagent | list-children.ts 及类型 | 重写为自管枚举 + 投影阶梯四态映射；删 session-query 依赖、逐 child 事件读取与就地分类机器；错误码 ` SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 换 ` SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` |
| session-query | index.ts、corpus.ts | 读路径去 clone，
| host/apiproxy | api-proxy.ts | 删 ` hasSubagentDescriptor`，属主判定只看 ` header.origin` |
| tool | tool-subagent-control/list-agents.ts | 加载要求收窄（ sessionQuery`） ；
| wire/client | api/subagents.ts、runtime sessions/service.ts、GUI | **零改动**——行形状与 diagnostic 处理不变 |
| core/session、session-persistence、session-projection(-cache)、session-query-sqlite | — | **零改动** |
| 测试/快照 | 相关 spec 与 snapshot | 随行为更新，提 PR 前统一处理 |
### 推进节奏
1. ` subagent` projection unit 与注册（纯增量）。
2. session-query：
3. ` listChildren` 重写（自管枚举 + 投影阶梯） ； ； hasSubagentDescriptor` 删除。
4. 测试与快照统一更新，整体 diff 评审后再拆 commit。
配套文档随实现 PR 处理：[session-projection RFC](2026-07-27-session-projection-and-command-log.md) 增补一节，记录 ` subagent` 身份 unit 与 snapshot/restore 两处既有读法的消费实例（
## 考虑过的替代方案
**mode/label 进 SessionHeader。** 零读保证最强——列表只看 header 就能成行。但 header 形状变更传导两个 persistence backend 与 header 兼容检查； ， inspect` 现算"，不碰持久格式。
**projection-cache 阶梯（ cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但它给 subagent 域在 ` sessionProjections` 之外再引入 ` sessionProjectionCache` 依赖，且 checkpoint 是一套新增的派生数据持久化与失效编排（ ） ；
**给 persistence 加有界读原语抢救存量。** 为一次性问题新开 seam 原语；被读时 ` inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
**list 行 mode/label 可选化（
**彻底删除 diagnostic 行（ ，
**registry 计算失败通道（ failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，曾考虑让 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否： ， ， ： emit`（ session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
**值随 query 索引 preparation 落库（ projectionsFor` 批量读面、行值随 ` (key → stateVersion)` 注册集存储的失效对账与 SCHEMA bump 均已施工过。整体退役：方向反了——查询基础设施被迫认识领域词汇（投影列、注册集对账），而唯一消费方 subagent 列表读时现算即可满足；消费方归零后，这套派生持久化没有存在理由。` SESSION_QUERY_PROJECTIONS_UNAVAILABLE` 随读面一并删除。
**subagent 手工 parse 加进程 memo 加创建播种（ ： sessionProjections` 水位缓存、cold 走 ` registry.restore`，复用 registry 这一份折叠权威，不再出现第二份描述符解释逻辑，也不引入进程态缓存与播种时序。
**session-query 输出面 DeepReadonly（ ， ： （ ） ，
## 验收标准
- 稳态列表读代价： （ ） ； listChildren` 恰一次 ` persistence.inspect` 整读；由 subagent 测试断言。
- 行为等价： ， （ ） ， corrupt` 行、` unsupported` 归并入 ` corrupt`、四条边界偏差（ corrupt` 转 ` unavailable`）——且每处变化有测试钉住新行为。
- 四态映射成立：快照有值成 child 行； corrupt` 行（含 descriptor-less 定局残骸） ； （ ） ； unavailable`； unsupported` 不再产出。
- 错误契约：` ctx.sessionProjections` 未挂载时 ` listChildren` 于枚举前以 ` SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 失败（零 children 部署同样确定失败）；` SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 从代码与文档中消失。
- persistence 缺席退为 live-only 枚举， ，
- per-child 隔离：单 child 整读失败只产生该行 ` unavailable`，
- ` hasSubagentDescriptor` 删除后属主判定只认 ` header.origin`； list_agents` 的 description、output schema 与既有无密钥快照零变化，钉住 wire/tool/GUI 零改动。
- corpus 去 clone 后公开输出为浅 readonly 借用视图，既有 session-query 行为测试全数通过。
## 风险
- **折叠规则分叉。** "折叠只在 registry 一份"是本设计的承诺；若未来某消费面绕开 registry 手写折叠，各读面的值可能漂移。缓解：列表两级阶梯与 GUI history 冷读走的都是 registry 的同两处读法（ ） ，
- **cold child 的每次列表整读成本。** cold child 每次 ` listChildren` 都做一次 ` inspect` 整读现算，成本与其 transcript 大小成正比、随列表频率重复；定案"算完即止"，不建缓存、不回写。同 id 短期重复整读可命中持久化协调器准备阶段的 LRU 复用， ；
- **诊断语义的四处边界偏差。** stillborn fork 的祖先身份误现为 child 行、多描述符改取末者、header 冲突不再被察觉、损坏源读失败由 ` corrupt` 转 ` unavailable`——完整语义与接受理由见提案的已知边界偏差清单。均为残骸级数据的展示或分类偏差，恢复鉴权不受影响。
- **pre-#1569 存量属主判定收窄。** 无 ` origin` 的旧 child 不再被认作 subagent 属主。其本就不进目录，
## 相关
- [durable-subagent-catalog 与 list_agents](../../implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)——被本记录部分取代：描述符仍是 mode/label 的持久权威与折叠输入，列表的枚举与取值改为自管合并加投影阶梯。
- [session projections 与命令生命周期日志](2026-07-27-session-projection-and-command-log.md)——registry 契约的权威；本记录为其新增 ` subagent` 身份 unit，
- [web subagent conversations](../../implemented/feature/2026-07-27-web-subagent-conversations.md)——` SessionHeader.origin` 的出处（#1569） ， ； （
- [发布前可复用的 Session 准备阶段](../../implemented/architecture/2026-08-05-session-preparation.md)——` inspect()` 冷读与 LRU 复用；
imccyu