Merge master and resolve integration conflicts for #5557

2026-10-08 11:45:32 +08:00
commit 9a5e9485d7
@@ -2,36 +2,33 @@
 # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants:
-  en: 052aa271e87074c0
-  zh: 3ccffc50fc1a28d4
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/problem:
-  en: 6ea85a4531d5e59f
-  zh: b4b568eb347f016a
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/decision:
-  en: 6e701ec64c3bbfae
-  zh: b8ed0f1cb7a0477a
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/decision/session-owns-immutable-history:
-  en: ff47e58c377a8dc0
-  zh: 5edbe4f3642a3fe6
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/decision/derived-requests-remain-detached:
+/agent-note-source-owned-session-immutability:
+  en: cf33ffdd07df7257
+  zh: 3d6895c9c80b0b1f
+/agent-note-source-owned-session-immutability/problem:
+  en: e5d87f6c5aef2dad
+  zh: 9f7f1459d99c523c
+/agent-note-source-owned-session-immutability/decision:
+  en: 821a886d365a2271
+  zh: 4ba5d74a7772150d
+/agent-note-source-owned-session-immutability/decision/session-owns-immutable-history:
+  en: 76fc0d8548d192c1
+  zh: 34c610fff5beb455
+/agent-note-source-owned-session-immutability/decision/derived-requests-remain-detached:
  en: 975df574ee6e6df8
  zh: 96d765058482835a
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/decision/package-owned-invariant-companions-check-relationships:
-  en: bf2e4cbfafc87dcf
-  zh: dc2ab42ea9ded856
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/alternatives-considered:
+/agent-note-source-owned-session-immutability/alternatives-considered:
  en: 6119e2aff3b6be5a
  zh: 76136ef5249c23eb
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/alternatives-considered/pervasive-deep-readonly-types:
+/agent-note-source-owned-session-immutability/alternatives-considered/pervasive-deep-readonly-types:
  en: ec54af2931616616
  zh: 5fd9bc469a6fd3a5
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/alternatives-considered/development-only-freezing:
-  en: 85591197bb62eabf
-  zh: ba69b9ccf596a6d7
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/alternatives-considered/clone-only-when-deriving-messages:
+/agent-note-source-owned-session-immutability/alternatives-considered/development-only-freezing:
+  en: 1857fb245ec3f086
+  zh: 6d3324c872627bf6
+/agent-note-source-owned-session-immutability/alternatives-considered/clone-only-when-deriving-messages:
  en: a9848dec50664b92
  zh: 7c558550b054627b
-/agent-note-source-owned-session-immutability-and-dev-mode-invariants/consequences:
-  en: bcccf7d464a070db
-  zh: eccd442a21e2c99e
+/agent-note-source-owned-session-immutability/consequences:
+  en: d26609b76b9eea01
+  zh: cf046d5c7173b738
@@ -1,4 +1,4 @@
-# Agent Note: Source-owned session immutability and dev-mode invariants
+# Agent Note: Source-owned session immutability

 Status: implemented

@@ -6,17 +6,17 @@ English | [中文](2026-06-11-dev-invariants-over-deep-readonly.zh.md)

 ## Problem

-The session log needs two different protections: immutable ownership of each stored fact, and checks for relationships among facts across time and service contracts. Conflating them in an optional development plugin would leave production history vulnerable; trying to express both through TypeScript readonly types would not create a runtime boundary or describe relational rules.
+The session log needs immutable ownership of each stored fact. Making that protection an optional development plugin would leave production history vulnerable; expressing it through TypeScript readonly types would not create a runtime boundary.

 The session log is the durable source of truth for replay, request reconstruction, persistence, and user-visible history. Code outside the session package must be able to inspect that history without retaining a reference that can rewrite it later, and inputs accepted from callers must not remain connected to caller-owned mutable objects.

-Immutability of individual values is only half of the contract. A log can contain perfectly immutable records whose sequence, turn/step nesting, tool-call pairing, scoped delivery, or reconstructed model request is wrong. Those rules relate multiple records or services and cannot be established by freezing one object.
+Immutability of individual values does not establish relationships among records. A log can contain perfectly immutable records whose sequence, turn/step nesting, tool-call pairing, scoped delivery, or reconstructed model request is wrong. Those rules relate multiple records or services, cannot be established by freezing one object, and are outside this decision.

 TypeScript readonly types are not a sufficient runtime boundary. They disappear when the program runs, a cast can bypass them, and a recursive `DeepReadonly<T>` would spread through every log and message consumer even though some downstream request-processing APIs intentionally work with mutable values.

 ## Decision

-Responsibility is split between an always-on storage boundary and optional development assertions.
+`Session` owns an always-on storage boundary.

 ### Session owns immutable history

@@ -24,18 +24,12 @@ Responsibility is split between an always-on storage boundary and optional devel

 The accepted event and all of its descendants are deep-frozen before publication. `append()` returns that owned frozen event, and `session/event` observers and `eventAt(seq)` receive the same record. `snapshotEvents(fromSeq?, toSeqExclusive?)` returns a frozen array snapshot; a previously returned array does not grow after a later append. `seq` reads the current length without materializing an array. Synchronous historical readers are deprecated under the [event-read policy](2026-09-09-deprecate-synchronous-session-event-reads.md). Seed records pass through the same validation, snapshot, and freeze boundary before construction succeeds.

-This guarantee belongs in `Session`, not in an optional listener, because every composition relies on trustworthy history. A production deployment, a focused test, or a custom embedding receives the same storage semantics whether or not development support plugins are registered.
+This guarantee belongs in `Session`, not in an optional listener, because every composition relies on trustworthy history. A production deployment, a focused test, or a custom embedding receives the same storage semantics regardless of which plugins are registered.

 ### Derived requests remain detached

 `deriveMessages()` projects logged surface events into detached, deep-frozen `Message` objects and returns a fresh array snapshot. Request assembly can therefore combine derived history with other inputs without exposing a path back into the log. The cache reuses safe immutable projections rather than recloning the complete history for each model call.

-### Package-owned invariant companions check relationships
-
-`dsh-invariants` registers the configurable `ctx.invariants` service and contains no product checks. A package publishes a `./invariant` ownership companion only for an independently observable runtime relationship; packages without one omit the companion and record the reason in their README. `dsh-session`, `dsh-agent`, `dsh-scope`, and `dsh-agent-loop` provide the initial rules that require trace state or observation of another seam: monotonic sequence numbers, turn and step nesting, tool-call/result pairing, legal agent-status transitions, subject-correct scoped dispatch, and equality between a loop-built request and the request reconstructed from its session-log prefix. Global enablement and package-name regex filters belong to the service ([package-owned invariant service](../../archived/architecture/2026-07-19-package-owned-invariant-service.md); [omission reference](../../../../packages/AGENTS.md)).
-
-When the session companion attaches to an existing or seeded session, it replays the immutable log to rebuild trace state. The service gives each contribution a disposable child fiber, so hot reload is safe in the middle of a turn without giving diagnostics ownership of session storage.
-
 ## Alternatives considered

 ### Pervasive deep-readonly types
@@ -44,7 +38,7 @@ A rejected companion proposal would apply a recursive `DeepReadonly<T>` type acr

 ### Development-only freezing

-Freezing history only when an invariants plugin is installed would make the core guarantee composition-dependent. Code could pass development tests and still corrupt history in production or in a focused composition that omits the plugin. Storage immutability is therefore always on, while the more expensive relational checks remain opt-in development support.
+Freezing history only when a development plugin is installed would make the core guarantee composition-dependent. Code could pass development tests and still corrupt history in production or in a focused composition that omits the plugin. Storage immutability is therefore always on.

 ### Clone only when deriving messages

@@ -55,6 +49,4 @@ Detaching `deriveMessages()` would protect the most common request path but leav
 - Every accepted live or seeded session event is detached from caller-owned inputs and deeply immutable before any observer can receive it.
 - Existing `snapshotEvents()` and `eventAt()` callers retain immutable read results while their migration is deferred; `seq` reads the log length without copying the array.
 - Request-side mutation cannot reach stored history through derived messages.
- Development builds can enable relational assertions without changing storage behavior, and disposing or filtering a companion does not weaken log immutability.
- `dsh-invariants` configures global enablement plus package allow/block regex lists; each check remains owned and tested by its product package.
 - The runtime boundary carries a recursive snapshot-and-freeze cost once per accepted event; later readers and cached projections reuse the owned immutable records.
@@ -1,4 +1,4 @@
-# Agent Note: 源端拥有的会话不可变性与开发模式不变式
+# Agent Note: 源端拥有的会话不可变性

 Status: implemented

@@ -6,17 +6,17 @@ Status: implemented

 ## 问题

-会话日志需要两种不同的保护：对每条已存储事实的不可变所有权，以及对跨时间和服务约定的事实之间关系的检查。如果将二者混为一个可选的开发插件，生产环境的历史记录将失去保护；如果试图通过 TypeScript readonly 类型同时表达两者，既无法建立运行时边界，也无法描述关系规则。
+会话日志需要对每条已存储事实的不可变所有权。如果将这项保护做成可选的开发插件，生产环境的历史记录将失去保护；如果通过 TypeScript readonly 类型表达它，则无法建立运行时边界。

 会话日志是回放、请求重建、持久化与用户可见历史的持久真源。会话包外部的代码必须能检视历史，但不能保留一个可在之后改写历史的引用；从调用方接受的输入也不能继续连接到调用方拥有的可变对象。

-单个值的不可变性只是约定的一半。一份日志可以包含完全不可变的记录，但其序列、轮次/步骤嵌套、工具调用配对、作用域分发或重建的模型请求是错误的。这些规则涉及多条记录或多个服务，无法通过冻结单个对象来建立。
+单个值的不可变性不能建立记录之间的关系。一份日志可以包含完全不可变的记录，但其序列、轮次/步骤嵌套、工具调用配对、作用域分发或重建的模型请求是错误的。这些规则涉及多条记录或多个服务，无法通过冻结单个对象来建立，也不属于本决策。

 TypeScript readonly 类型不是充分的运行时边界。它们在程序运行时消失，类型转换可以绕过它们，而递归的 `DeepReadonly<T>` 会扩散到每个日志和消息消费方，尽管某些下游请求处理 API 有意使用可变值。

 ## 决策

-职责划分给始终启用的存储边界和可选的开发断言。
+`Session` 拥有始终启用的存储边界。

 ### Session 拥有不可变历史

@@ -24,18 +24,12 @@ TypeScript readonly 类型不是充分的运行时边界。它们在程序运行

 被接受的事件及其所有后代在发布前被深度冻结。`append()` 返回由 Session 拥有的冻结事件，`session/event` 观察者和 `eventAt(seq)` 接收同一记录。`snapshotEvents(fromSeq?, toSeqExclusive?)` 返回冻结的数组快照；先前返回的数组不会因后续 append 而增长。`seq` 无需物化数组即可读取当前长度。同步历史读取方法按[事件读取策略](2026-09-09-deprecate-synchronous-session-event-reads.zh.md)弃用。种子记录在构造成功前经过相同的验证、快照与冻结边界。

-此保证属于 `Session` 而非可选监听器，因为每种组合都依赖可信的历史。无论是否注册了开发支持插件，生产部署、聚焦测试或自定义嵌入都获得相同的存储语义。
+此保证属于 `Session` 而非可选监听器，因为每种组合都依赖可信的历史。无论注册了哪些插件，生产部署、聚焦测试或自定义嵌入都获得相同的存储语义。

 ### 派生请求保持分离

 `deriveMessages()` 将已记录的表面事件投影为分离的、深度冻结的 `Message` 对象，并返回一份新的数组快照。因此请求组装可以将派生历史与其他输入组合，而不会暴露一条回到日志的路径。缓存复用安全的不可变投影，而非为每次模型调用重新克隆完整历史。

-### 包拥有的不变式配套插件检查关系
-
-`dsh-invariants` 注册可配置的 `ctx.invariants` 服务，本身不包含产品检查。只有拥有可独立观察的运行时关系时，包才发布 `./invariant` 所有权配套插件；没有该关系的包会省略 companion 并在 README 中记录原因。`dsh-session`、`dsh-agent`、`dsh-scope` 和 `dsh-agent-loop` 提供首批需要跟踪状态或观察另一个 seam 的规则：单调递增的序列号、轮次与步骤嵌套、工具调用/结果配对、合法的 agent（智能体）状态转换、主体正确的作用域分发，以及循环构建的请求与从其会话日志前缀重建的请求之间的相等性。全局启用和包名 regex 过滤器归该服务所有（见[包拥有的不变式服务](../../archived/architecture/2026-07-19-package-owned-invariant-service.md)与[省略说明](../../../../packages/AGENTS.md)）。
-
-当会话配套插件附加到已有会话或以种子记录初始化的会话时，它回放不可变日志以重建跟踪状态。服务为每项贡献提供一个可 dispose（资源释放）的子 fiber，因此轮次中途热重载是安全的，同时不赋予诊断逻辑对会话存储的所有权。
-
 ## 曾考虑的替代方案

 ### 全面的 deep-readonly 类型
@@ -44,7 +38,7 @@ TypeScript readonly 类型不是充分的运行时边界。它们在程序运行

 ### 仅在开发模式冻结

-仅当不变式插件安装时才冻结历史，会使核心保证依赖于组合方式。代码可能通过开发测试，却在生产环境或省略了该插件的聚焦组合中破坏历史。因此存储不可变性始终启用，而开销更大的关系检查则保持为可选的开发支持。
+仅当开发插件安装时才冻结历史，会使核心保证依赖于组合方式。代码可能通过开发测试，却在生产环境或省略了该插件的聚焦组合中破坏历史。因此存储不可变性始终启用。

 ### 仅在派生消息时克隆

@@ -55,6 +49,4 @@ TypeScript readonly 类型不是充分的运行时边界。它们在程序运行
 - 每个被接受的实时或种子会话事件在任何观察者接收之前，都已从调用方拥有的输入中分离并深度不可变。
 - 现有 `snapshotEvents()` 和 `eventAt()` 调用方在暂缓迁移期间仍获得不可变的读取结果；`seq` 无需复制数组即可读取日志长度。
 - 请求侧的修改无法通过派生消息触及已存储的历史。
- 开发构建可以启用关系断言而不改变存储行为；dispose 或过滤一个配套插件不会削弱日志不可变性。
- `dsh-invariants` 配置全局启用状态以及包名允许/阻止 regex 列表；每项检查仍由其产品包拥有并测试。
 - 运行时边界对每个被接受的事件产生一次递归快照与冻结的开销；后续读取者和缓存投影复用已拥有的不可变记录。
@@ -27,8 +27,8 @@
  en: ee71f9c0f12b6a0e
  zh: 403b1723f808391d
 /agent-note-session-surface-an-ordered-projection-over-the-event-log/decision/invariants:
-  en: 24b1342fb3b5be29
-  zh: a62692b0250c072a
+  en: 98f39e77083d67b7
+  zh: 634a9227fc2a7ec9
 /agent-note-session-surface-an-ordered-projection-over-the-event-log/alternatives-considered:
  en: 193157129e65e487
  zh: a0a73b8a9cbd78e6
@@ -45,7 +45,7 @@ The `repair.ts` module synthesizes `tool/result` closers for orphaned tool calls

 ### Invariants

-`Session` validates `sourceEventSeqs` and `surfaceOp` at the always-on seed/append boundary: source lists are non-empty, unique, earlier, and known; `assistant/message` carries no source list; replacement endpoints exist in surface order; and `sourceEventSeqs` covers every shadowed node. These are single-record acceptance and storage-projection rules, not optional invariant-service contributions.
+`Session` validates `sourceEventSeqs` and `surfaceOp` at the always-on seed/append boundary: source lists are non-empty, unique, earlier, and known; `assistant/message` carries no source list; replacement endpoints exist in surface order; and `sourceEventSeqs` covers every shadowed node. These are single-record acceptance and storage-projection rules.

 Every surface-eligible event must carry `surfaceOp` or it would disappear from derived history. Typed `append` overloads enforce this for literal event types; runtime checks in `append` and the seed constructor cover widened unions and current loaded logs. Released validation and conversion belong to their versioned migration edges rather than generic Session code; see the [V2-to-V3 placement rules](../../../../packages/session/session-format-v2-to-v3/README.md#canonical-envelopes).

@@ -45,7 +45,7 @@ surface 元数据仅属于四种 surface 事件类型（`system/message`、`user

 ### 不变式

-`Session` 在始终启用的 seed/append 边界校验 `sourceEventSeqs` 与 `surfaceOp`：source list 必须非空、唯一、更早且已知；`assistant/message` 不携带 source list；replacement endpoint 必须存在于 surface 顺序中；`sourceEventSeqs` 必须覆盖每个被遮蔽的节点。这些是单记录接纳与存储投影规则，不是由可选 invariant service 提供的规则。
+`Session` 在始终启用的 seed/append 边界校验 `sourceEventSeqs` 与 `surfaceOp`：source list 必须非空、唯一、更早且已知；`assistant/message` 不携带 source list；replacement endpoint 必须存在于 surface 顺序中；`sourceEventSeqs` 必须覆盖每个被遮蔽的节点。这些是单记录接纳与存储投影规则。

 每个可进入 surface 的事件都必须携带 `surfaceOp`，否则它将从派生历史中消失。类型化的 `append` 重载对字面事件类型强制执行此规则；`append` 和种子构造函数中的运行时检查覆盖宽化联合类型和当前已加载日志。已发布格式的校验与转换属于各自版本化迁移边，而不属于通用 Session 代码；参见 [V2 到 V3 位置规则](../../../../packages/session/session-format-v2-to-v3/README.zh.md#canonical-envelopes)。

@@ -21,8 +21,8 @@
  en: 57dbdd385f48bb3e
  zh: 5e15463fae4be582
 /agent-note-bounded-recovery-for-transient-llm-request-failures/decision/bound-stalled-streams-where-they-can-be-stopped:
-  en: f7369086e87192b9
-  zh: e2839ed8cc5c23b8
+  en: 6a55107caa329eea
+  zh: 13a76e482739141e
 /agent-note-bounded-recovery-for-transient-llm-request-failures/decision/keep-attempts-separate-in-the-existing-log:
  en: 8f57db4bfd6e1c22
  zh: 67ac62217bb68570
@@ -33,8 +33,8 @@
  en: a6d0306740d470ee
  zh: 700bd4b0aa58f3e8
 /agent-note-bounded-recovery-for-transient-llm-request-failures/verification:
-  en: db343f335a9d7cad
-  zh: 49b8300de55dcfeb
+  en: 7412edfd162c4a28
+  zh: 64108a11e6194e35
 /agent-note-bounded-recovery-for-transient-llm-request-failures/consequences:
  en: 08659e8606455ada
  zh: 862080f8df5f28ec
@@ -78,7 +78,7 @@ Each adapter exposes a validated `streamIdleTimeoutMs` configuration field with

 `@deepseek-ai/dsh-timeout` exposes a rearmable idle-watchdog primitive. One stable local `AbortController` is fused with the caller signal and passed to the transport for the whole adapter call; each outstanding `next()` arms the watchdog, resolution disarms it, and the next demand rearms it. Out-of-band transport activity calls `pulse()` to rearm an outstanding demand without yielding a value. Timeout aborts that stable controller with a capability-owned `TimeoutReason`, and `finally` clears the timer. The adapter classifies its watchdog as `TIMEOUT` and an earlier upstream abort as `ABORTED`. The existing one-shot `deadline()` is not presented as a sliding timer.

-Boundary tests prove termination at both actual transports. The hand-written adapter aborts its fetch/reader, and the pi-ai adapter maps the stable signal through the SDK and proves the SDK closes the response. A timer that merely rejects a consumer promise while leaving the request running does not satisfy the contract.
+Boundary tests prove termination at both actual transports. The hand-written adapter aborts its fetch/reader, and the pi-ai adapter maps the stable signal through the SDK and proves the SDK closes the response. A timer that merely rejects a consumer promise while leaving the request running does not satisfy the contract, so the watchdog does both: the signal aborts the request, and the deadline settles the outstanding demand even when the transport never observes that abort.

 ### Keep attempts separate in the existing log

@@ -117,7 +117,7 @@ If recovery is exhausted, the final failure is stored once on `turn/end.reason`
 - Real agent-loop tests cover failure before chunks, partial chunks then failure, thrown and in-band failures, retry to success inside the same turn, exhaustion to structured `turn/end.reason`, and composition with `dsh-compaction-basic` context-overflow recovery.
 - The partial-chunk integration test proves failed chunks remain attributed to the failed step, no assistant message or tool side effect is committed for that step, and the successful retry records its own chunk seqs and provider/model route.
 - The plugin-owned `llm/retry` event is non-surface, survives a JSONL round trip, is ignored by message derivation, and drives TUI and Web retraction plus scheduled-retry rendering. Client tests cover complete wire validation, clock-independent countdown, cancellation versus completed retry labels, and trajectory attribution; keyless UI snapshots cover Web scheduling and success, real Web composition tests cover partial transport failure through recovery and exhausted recovery's terminal error row beside the settled retry chain, and ACP automation snapshots confirm that a discarded attempt stays off the wire while the recovered reply is emitted.
- Idle-watchdog tests prove the stable signal is rearmed only while `next()` is outstanding, disarmed during consumer think time and in `finally`, and classified separately from a total-call deadline and an earlier caller abort; adapter tests prove the signal stops the underlying request rather than merely detaching it.
+- Idle-watchdog tests prove the stable signal is rearmed only while `next()` is outstanding, disarmed during consumer think time and in `finally`, and classified separately from a total-call deadline and an earlier caller abort; adapter tests prove the signal stops the underlying request rather than merely detaching it, and that the idle deadline settles a demand the transport abandoned.
 - Direct `ctx.llm.stream()` callers remain single-attempt and receive the same structured failure facts.

 ## Consequences
@@ -78,7 +78,7 @@ agent loop（智能体循环）会将终止 finish 的 `LlmFailure` 传给 `agen

 `@deepseek-ai/dsh-timeout` 公开一个可重新布防的空闲看门狗原语。一个稳定的局部 `AbortController` 会与调用方信号融合，并在整个适配器调用期间传给传输层；每个尚未完成的 `next()` 都会布防看门狗，该调用完成时解除布防，下一次请求数据时再重新布防。带外传输活动会调用 `pulse()`，在不产生值的情况下为尚未完成的需求重新布防。超时会使用能力自身拥有的 `TimeoutReason` 中止这个稳定控制器，`finally` 则会清除定时器。适配器将自身看门狗归类为 `TIMEOUT`，将更早发生的上游中止归类为 `ABORTED`。现有的一次性 `deadline()` 不会被描述为滑动计时器。

-边界测试证明两个实际传输层都能终止。手写适配器会中止其 fetch／reader，pi-ai 适配器会把稳定信号映射到 SDK，并证明 SDK 会关闭响应。如果定时器只拒绝消费方 promise，却让请求继续运行，就不满足此约定。
+边界测试证明两个实际传输层都能终止。手写适配器会中止其 fetch／reader，pi-ai 适配器会把稳定信号映射到 SDK，并证明 SDK 会关闭响应。如果定时器只拒绝消费方 promise，却让请求继续运行，就不满足此约定；因此 watchdog 两者都做：信号中止请求，截止时间则在传输层始终不观察该中止时结算尚未完成的 demand。

 ### 在现有日志中分隔尝试

@@ -117,7 +117,7 @@ agent loop（智能体循环）会将终止 finish 的 `LlmFailure` 传给 `agen
 - 真实 agent-loop 测试覆盖分片前失败、部分分片后失败、抛出及带内失败、在同一轮次内重试至成功、耗尽后写入结构化 `turn/end.reason`，以及与 `dsh-compaction-basic` 上下文溢出恢复的组合。
 - 部分分片集成测试证明：失败分片仍归属于失败步骤，该步骤不会提交 assistant 消息或工具副作用，成功的重试会记录自己的分片 seq 和提供方／模型路由。
 - 插件拥有的不进入表层的 `llm/retry` 事件可在 JSONL 往返后保留，被消息派生忽略，并驱动 TUI 和 Web 撤回及计划重试渲染。客户端测试覆盖完整的 wire 验证、独立于时钟的倒计时、已取消与已完成重试标签的区别以及轨迹归属；无密钥 UI 快照覆盖 Web 的调度与成功，真实 Web 组合测试覆盖部分传输失败直至恢复，以及耗尽后终态错误行与定格重试链并列的画面，ACP 自动化快照确认，被丢弃的尝试不会通过协议发出，而恢复后的回复会正常发出。
- 空闲看门狗测试证明：只有 `next()` 尚未完成时才会重新布防稳定信号；在消费方思考期间及 `finally` 中会解除布防；它与总调用 deadline 以及更早发生的调用方中止分开分类。适配器测试证明该信号会终止底层请求，而不只是与其脱离。
+- 空闲看门狗测试证明：只有 `next()` 尚未完成时才会重新布防稳定信号；在消费方思考期间及 `finally` 中会解除布防；它与总调用 deadline 以及更早发生的调用方中止分开分类。适配器测试证明该信号会终止底层请求，而不只是与其脱离，并证明空闲截止时间会结算传输层放弃的 demand。
 - `ctx.llm.stream()` 的直接调用方仍只尝试一次，并收到相同的结构化失败事实。

 ## 后果
@@ -9,14 +9,14 @@
  en: 8ccef8fbd9260dfe
  zh: 106b2bafe969c676
 /agent-note-prompt-variables-and-tool-guidance-ownership/decision:
-  en: c551d888282d9c73
-  zh: 889b5ca3cdf25aff
+  en: 8d3c456a97365869
+  zh: 983421e09cc90d5e
 /agent-note-prompt-variables-and-tool-guidance-ownership/decision/assemble-context:
  en: 46e67248692e333a
  zh: 51c5f2c6152c94d7
 /agent-note-prompt-variables-and-tool-guidance-ownership/decision/prompt-variables:
-  en: 04b623ed2879fdf1
-  zh: c111be62834fda93
+  en: dc41d226f111d574
+  zh: c6242bf30b2ed61c
 /agent-note-prompt-variables-and-tool-guidance-ownership/decision/persona-as-the-order-0-section:
  en: c2d32c0ac5d28759
  zh: 59cd252ba6da6e59
@@ -30,11 +30,11 @@
  en: 9a114359d2e8988b
  zh: ce39453408b2af7f
 /agent-note-prompt-variables-and-tool-guidance-ownership/out-of-scope:
-  en: bbfecc70d0b457fe
-  zh: 7f207a37a86484f4
+  en: 06169acd6e002300
+  zh: 605cf02f81df48bc
 /agent-note-prompt-variables-and-tool-guidance-ownership/shipped-invariants:
  en: 31ba63101fca5790
  zh: af4ceefab2033142
 /agent-note-prompt-variables-and-tool-guidance-ownership/consequences:
-  en: 993f17bf35f6a2e0
-  zh: acb429176f0eebcc
+  en: 94c38eb61a2dcd4a
+  zh: 8a047857b6d3a4a3
@@ -18,7 +18,7 @@ The assembled system prompt had four defects, all of one family: facts the harne

 ## Decision

-**One principle: every fact in the prompt has exactly one owner.** The model name and workspace are config/session facts → the harness exposes them as variables and the persona references them. Per-tool semantics and when-to-use → the tool's `description`. Cross-call habits a description cannot carry → the tool package's prompt section. The product name and SDK identity line → the static `harness:identity` section. Deployment role and behavior → the deployment's persona.
+**One principle: every prompt fact has exactly one owner.** The loop exposes route facts as variables referenced by the persona. The working-directory service supplies the current directory as user context. Per-tool semantics and when-to-use belong to the tool description; cross-call habits belong to its package prompt section. The product name and SDK identity line belong to the static `harness:identity` section. Deployment role and behavior belong to the deployment persona.

 ### Assemble context

@@ -28,7 +28,7 @@ The assembled system prompt had four defects, all of one family: facts the harne

 Plugins register `{{name}}` values through `ctx.systemPrompt.variable(name, provider)`. Assembly resolves them into the waterfall-visible variable map. Rendering rejects unknown own-property references, registered providers that return `undefined`, malformed complete references, and unbalanced references that still contain a closing `}}`; a lone unmatched `{{` remains prose, and substituted values are not rescanned. Registration rejects invalid or duplicate variable names, and section names are unique. Sections may set `interpolate: false` to preserve generated documents literally; `tools:sdk` does so because tool descriptions and schemas may document their own `{{…}}` syntax.

-`dsh-agent-loop` registers the two built-ins, both pure projections of the context agent: `model` (= `options.model`) and `cwd` (= `session.header.cwd`). The example personas write `powered by the {{model}} model` — the model name is stated once, in the `model:` config key. `{{cwd}}` is demonstrated in the ACP example only: every ACP session carries the client's cwd, while config-pre-created stdio agents have none (a persona claiming `{{cwd}}` there fails the turn — by design). The variables stay on the loop plugin (unlike the sections below): they are runtime facts of the agents THIS loop drives, and a replacement loop supplies its own.
+`dsh-agent-loop` registers `provider` (= `options.provider`) and `model` (= `options.model`) as pure projections of the context agent. Example personas reference `{{model}}` so the route owns the model name. These variables remain on the loop plugin because they describe the agents it drives; a replacement loop supplies its own. The [Session working-directory decision](2026-09-13-session-working-directory.md) owns directory state and its literal user-context placement; the loop does not register `cwd`.

 ### Persona as the order-0 section

@@ -54,7 +54,6 @@ Per-tool semantics and selection guidance live in tool descriptions. Prompt sect
 ## Out of scope

 - Further variables (`date`, platform, git state) — the registry makes each a one-line contribution by whichever plugin owns the fact; none is claimed here.
- A config `cwd` for pre-created stdio agents (would let the stdio persona use `{{cwd}}` and partition persistence by real path) — deferred until the session-cwd story is revisited.

 ## Shipped invariants

@@ -68,5 +67,5 @@ Per-tool semantics and selection guidance live in tool descriptions. Prompt sect
 - Every fact in the assembled prompt now has exactly one owner, and the hand-maintained tool prose in leaf YAML is gone: loading or dropping a tool plugin no longer means editing any deployment's persona.
 - `{{model}}` reflects `AgentOptions.model` at assembly time. A plugin that switches models in the `agent/request` waterfall makes the prompt's claim stale for that step, and one that SUPPLIES the model there (options.model unset — the loop's documented fallback) leaves the variable valueless at render, failing a `{{model}}` persona before the waterfall runs. Both have the same remedy, and it is the ownership rule itself: the plugin that owns the late-bound model fact states it early on the `system-prompt/assemble` waterfall (`assembly.variables['model'] = …`) — one owner, both statements; a loop test pins the supply path end-to-end. Accepted.
 - While a bound provider is absent (not yet activated, unloaded, mid-HMR-reload), the subagent tool does not exist and a model request in that window simply lacks it. That is the honest state — the alternative was a registered tool whose description or execution could not be trusted.
- Strictness means a persona can fail a turn at render (e.g. `{{cwd}}` on a cwd-less session). The failure is contained — the turn ends `error`, the loop survives — and it is an authoring error we WANT loud.
+- Strict interpolation rejects missing or valueless variables before a model request. The turn ends with `error` while the loop remains available for later turns; a persona referencing `{{model}}` requires its composing runtime to supply that value.
 - Inline escapes remain unsupported in interpolated text; literal sections need no escaping. PTC unit tests cover both modes and runtime languages, and the recorded `ptc-turn` scenario preserves tool-template examples in the model-visible prompt.
@@ -18,7 +18,7 @@ Status: implemented

 ## 决策

-**一条原则：提示词中的每个事实恰好有一个归属方。** 模型名称和工作区是配置/会话事实 → harness 将它们暴露为变量，persona 引用它们。每个工具的语义和何时使用 → 工具的 `description`。description 无法承载的跨调用习惯 → 包的提示词 section。产品名称和 SDK 身份说明 → 静态的 `harness:identity` section。部署角色与行为 → 部署的 persona。
+**一条原则：提示词中的每个事实恰好有一个归属方。** 循环将路由事实暴露为 persona 引用的变量。工作目录服务通过用户上下文提供当前目录。每个工具的语义和选择指导属于工具描述；跨调用习惯属于其包的提示词 section。产品名称和 SDK 身份说明属于静态的 `harness:identity` section。部署角色与行为属于部署的 persona。

 ### 组装上下文

@@ -28,7 +28,7 @@ Status: implemented

 插件通过 `ctx.systemPrompt.variable(name, provider)` 注册 `{{name}}` 值。组装过程将它们解析到 waterfall 可见的变量映射中。渲染阶段拒绝以下情况：引用未知的自有属性、已注册的提供方返回 `undefined`、格式错误的完整引用、以及仍包含闭合 `}}` 的不平衡引用；孤立的未匹配 `{{` 保留为行文，替换后的值不会被重新扫描。注册阶段拒绝无效或重复的变量名，section 名称也必须唯一。段可设置 `interpolate: false` 来原样保留生成的文档；`tools:sdk` 使用此设置，因为工具描述和 schema 可能会介绍自身的 `{{…}}` 语法。

-`dsh-agent-loop` 注册两个内置变量，均为上下文 agent 的纯投影：`model`（= `options.model`）和 `cwd`（= `session.header.cwd`）。示例 persona 写 `powered by the {{model}} model`——模型名称只在 `model:` 配置键中声明一次。`{{cwd}}` 仅在 ACP 示例中演示：每个 ACP 会话携带客户端的 cwd，而配置预创建的 stdio agent 没有 cwd（在那里声称 `{{cwd}}` 的 persona 会导致该轮次失败——这是有意为之）。变量留在 loop 插件上（不同于下面的 section）：它们是本循环驱动的 agent 的运行时事实，替换循环自行提供自己的变量。
+`dsh-agent-loop` 注册 `provider`（= `options.provider`）和 `model`（= `options.model`），它们都是上下文 agent 的纯投影。示例 persona 引用 `{{model}}`，由路由拥有模型名称。这些变量保留在 loop 插件上，因为它们描述该循环驱动的 agent；替换循环自行提供自己的变量。[Session 工作目录决策](2026-09-13-session-working-directory.zh.md) 拥有目录状态及其字面用户上下文位置；循环不注册 `cwd`。

 ### Persona 作为 order-0 section

@@ -54,7 +54,6 @@ Status: implemented
 ## 不在范围内

 - 更多变量（`date`、platform、git 状态）：注册表使每个变量成为拥有该事实的插件的一行贡献；本 Agent Note 不认领任何一个。
- 为预创建的 stdio agent 提供配置 `cwd`（可让 stdio persona 使用 `{{cwd}}` 并按真实路径分区持久化）：推迟到会话 cwd 方案重新讨论时。

 ## 交付的不变式

@@ -68,5 +67,5 @@ Status: implemented
 - 组装后的提示词中每个事实现在恰好有一个归属方，leaf YAML 中手工维护的工具行文已消除：加载或卸载一个工具插件不再需要编辑任何部署的 persona。
 - `{{model}}` 在组装时反映 `AgentOptions.model`。如果一个插件在 `agent/request` waterfall 中切换模型，提示词对该步骤的声明就会过时；如果一个插件在那里提供模型（options.model 未设置——循环文档中记载的回退路径），变量在渲染时无值，包含 `{{model}}` 的 persona 会在 waterfall 运行前失败。两者的补救方式相同，就是归属规则本身：拥有延迟绑定模型事实的插件在 `system-prompt/assemble` waterfall 上提前声明它（`assembly.variables['model'] = …`）——一个归属方，两处声明；一个循环测试端到端固定了 supply 路径。已接受。
 - 当一个已绑定的提供方不存在时（尚未激活、已卸载、HMR（热模块替换）重载中），subagent 工具不存在，该窗口内的模型请求中不会包含它。这是诚实的状态——替代方案是注册一个 description 或执行都不可信的工具。
- 严格性意味着 persona 可能在渲染时导致轮次失败（例如在无 cwd 的会话上使用 `{{cwd}}`）。失败是受控的——该轮次以 `error` 结束，循环存活——且这是一个我们希望明确暴露的撰写错误。
+- 严格插值在模型请求之前拒绝缺失或无值的变量。该轮次以 `error` 结束，循环仍可服务后续轮次；引用 `{{model}}` 的 persona 要求组合它的运行时提供该值。
 - 插值文本仍不支持行内转义；字面文本段无需转义。PTC 单元测试覆盖两种模式和运行时语言，录制的 `ptc-turn` 场景在模型可见的提示词中保留工具模板示例。
@@ -15,8 +15,8 @@
  en: 6da15cf986d59a91
  zh: 40282908b54295f9
 /agent-note-every-llm-request-is-reconstructable-from-the-session-log/decision/the-mechanism:
-  en: 1fbb8ed69c9a5dec
-  zh: 18ee4c172b45efe5
+  en: 1c0ca7de364e4f8b
+  zh: 906be723ab39e3ae
 /agent-note-every-llm-request-is-reconstructable-from-the-session-log/decision/the-minicode-shape-adopted-with-the-event-log-as-the-source:
  en: e5f2ffaa3d7de0cc
  zh: 5ba6b36787a0e189
@@ -28,7 +28,7 @@ Each proposed step first claims its inbox batch, assembles the system prompt and

 **The open step is the reconstruction boundary.** Its entered `user/message` batch and any newly written `request/header` precede request dispatch. Injection after the atomic claim joins a later request, while a listener that must affect this request returns messages through `agent/pre-step`. Header reconstruction selects the step's `request/header`, or carries the prior snapshot when no new header is written.

-**Enforcement.** The `dsh-agent-loop/invariant` companion registers with `ctx.invariants` and, when selected, independently rebuilds each loop request through a fresh `Session`, so the live cache cannot vouch for itself, then compares messages and folded header fields at `llm/stream`. The loop records the exact frozen request through `markAgentLoopRequest()` in `dsh-llm`; the process-local identity lets the companion and other request observers recognize conversation work, while direct one-shots remain excluded regardless of their frozen shape or session id. Correctness depends on sequence-bounded reconstruction rather than listener order. A with-key e2e requires positive cache-read tokens after the first request; per-step usage is the production signal, and a header change or compaction appears as a cache-read drop on the next step.
+**Enforcement.** The loop records the exact frozen request through `markAgentLoopRequest()` in `dsh-llm`; the process-local identity lets request observers recognize conversation work, while direct one-shots remain excluded regardless of their frozen shape or session id. A with-key e2e requires positive cache-read tokens after the first request; per-step usage is the production signal, and a header change or compaction appears as a cache-read drop on the next step.

 ### The MiniCode shape: adopted, with the event log as the source

@@ -28,7 +28,7 @@ Status: implemented

 **已打开步骤是重建边界。** 进入步骤的 `user/message` 批次与任何新写入的 `request/header` 都位于请求分派之前。原子领取后发生的注入加入后续请求；必须影响本次请求的监听器则通过 `agent/pre-step` 返回消息。header 重建选择该步骤的 `request/header`，或在无新 header 写入时沿用前一个快照。

-**强制执行。** `dsh-agent-loop/invariant` 配套插件向 `ctx.invariants` 注册，并在被选用时通过一个全新的 `Session` 独立重建每个循环请求，使活跃缓存无法为自身背书，然后在 `llm/stream` 处比较消息和折叠后的 header 字段。循环通过 `dsh-llm` 的 `markAgentLoopRequest()` 记录精确的冻结请求；这一进程内标识让配套插件和其他请求观察者识别对话工作，而直接的一次性调用无论其冻结形状或会话 id 如何都保持排除。正确性依赖于序列有界的重建，而非监听器顺序。带密钥的 e2e 要求首次请求之后有正值的 cache-read token；逐步骤用量是生产信号，header 变更或压缩表现为下一步骤的 cache-read 下降。
+**强制执行。** 循环通过 `dsh-llm` 的 `markAgentLoopRequest()` 记录精确的冻结请求；这一进程内标识让请求观察者识别对话工作，而直接的一次性调用无论其冻结形状或会话 id 如何都保持排除。带密钥的 e2e 要求首次请求之后有正值的 cache-read token；逐步骤用量是生产信号，header 变更或压缩表现为下一步骤的 cache-read 下降。

 ### MiniCode 形态：采纳，以事件日志为真源

@@ -21,8 +21,8 @@
  en: 333eab4967d753ec
  zh: dd7537bb82cc717f
 /agent-note-a-shared-timeout-deadline-primitive-with-hard-kill-left-to-each-capability/consequences:
-  en: 832f4dbd93a47f94
-  zh: 65ada43f9f23a39b
+  en: 0f723f16456c343d
+  zh: 52b7aab9a6c4f7be
 /agent-note-a-shared-timeout-deadline-primitive-with-hard-kill-left-to-each-capability/alternatives-considered:
-  en: 7b3445622becbd36
-  zh: bb358acf2ff28e26
+  en: 0f3e3ecfa399c81a
+  zh: 951c2ee71047b11a
@@ -101,7 +101,7 @@ The signal only *notifies*; termination is always the listener's job, and the li
 - `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. An always-0 field read by nothing is dead weight under the per-file coverage gate.
 - web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`.
 - `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met).
- Model streams now share one rearmable timer contract without turning a sliding idle interval into a total-call deadline or charging consumer think time. Adapters that can observe out-of-band transport activity may pulse an outstanding demand; suppressed activity remains invisible to the watchdog. The primitive still only notifies; adapter tests prove their transports observe its stable signal and terminate.
+- Model streams now share one rearmable timer contract without turning a sliding idle interval into a total-call deadline or charging consumer think time. Adapters that can observe out-of-band transport activity may pulse an outstanding demand; suppressed activity remains invisible to the watchdog. The one-shot `deadline()` still only notifies; adapter tests prove their transports observe the rearmable watchdog's stable signal and terminate. The watchdog additionally settles the one demand it drives when its idle interval elapses, because a transport that drops the error of an aborted in-flight read would otherwise hold the caller past that interval.

 Out of scope, named to mark the boundary: `web_search` can gain an optional model-facing `timeout_ms` once its tool-schema/snapshot coverage is planned; the ripgrep-backed fs discovery tools ([packaged ripgrep search](../../archived/architecture/2026-08-01-packaged-ripgrep-search.md)) consume the same provider-owned deadline shape through `dsh-tool-call-timeout-policy` and `exec.signal`; a `tools/execute` waterfall middleware could arm a default deadline for every tool call by driving `exec.signal` — that would be a plugin that *consumes* this library and still only notifies, the hard kill remaining each capability's job.

@@ -111,6 +111,6 @@ Out of scope, named to mark the boundary: `web_search` can gain an optional mode

 **Per-tool ad-hoc timeout, no shared code (the prior status quo, and Claude Code's choice).** Rejected because it was already producing divergence and duplicated correctness burden: web_fetch hand-rolled the exact controller/reason logic that future network/process-backed tools would each have to re-derive, and the fusion + `signal.reason` recovery are the error-prone parts. Claude Code tolerates full duplication; this repo has a single shared abort channel (`exec.signal` on every `execute`) that makes a small shared primitive strictly cleaner, so the cost/benefit differs.

-**A `withTimeout(promise, ms)` wrapper instead of a signal factory.** Rejected because racing a promise against a timer resolves the *tool-call* promise on deadline without stopping the underlying work — the child process or fetch socket leaks on. Handing out a signal and requiring the capability to listen is what forces a real termination path to exist. This mirrors the "dispose must reach quiescence, not just request it" defensive rule.
+**A `withTimeout(promise, ms)` wrapper instead of a signal factory.** Rejected because racing a promise against a timer resolves the *tool-call* promise on deadline without stopping the underlying work — the child process or fetch socket leaks on. Handing out a signal and requiring the capability to listen is what forces a real termination path to exist. This mirrors the "dispose must reach quiescence, not just request it" defensive rule. `idleWatchdog` is the deliberate exception, and only for the single iterator demand it drives: the signal it hands the transport still owns releasing that read (an abort destroys the socket), while the deadline ends the demand when the transport never settles it.

 **Keep separate bash timeout and cancellation triggers.** Rejected because one deadline signal removes the bespoke timer and standardizes classification. Racing causes report whichever abort arrived first, while the provider-owned termination path is independent of which cause won.
@@ -101,7 +101,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 - `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
- 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。能够观察到带外传输活动的适配器可以对尚未结算的 demand 调用 `pulse()`；被屏蔽的活动对 watchdog 仍不可见。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
+- 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。能够观察到带外传输活动的适配器可以对尚未结算的 demand 调用 `pulse()`；被屏蔽的活动对 watchdog 仍不可见。一次性的 `deadline()` 仍然只做通知；适配器测试证明其传输观察到可重启 watchdog 的稳定信号并终止。此外，watchdog 会在空闲间隔走完时结算它所驱动的那个 demand：否则丢弃已中止读取错误的传输层会让调用方一直等到间隔之外。

 以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；基于 ripgrep 的文件系统发现工具（[打包的 ripgrep 搜索](../../archived/architecture/2026-08-01-packaged-ripgrep-search.md)）通过 `dsh-tool-call-timeout-policy` 和 `exec.signal` 消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。

@@ -111,6 +111,6 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):

 **每个工具各自实现超时，不共享代码（先前的现状，也是 Claude Code 的选择）。** 否决，因为它已经在产生分化和重复的正确性负担：web_fetch 手写了与未来网络/进程类工具各自需要重新推导的完全相同的 controller/reason 逻辑，而融合 + `signal.reason` 恢复正是容易出错的部分。Claude Code 容忍完全重复；本仓库有一个统一的共享 abort 通道（每次 `execute` 上的 `exec.signal`），使得采用一个小型共享原语明显更简洁，因此成本/收益不同。

-**用 `withTimeout(promise, ms)` 包装器代替信号工厂。** 否决，因为让 promise 与定时器竞争只是在截止时间到达时 resolve *工具调用*的 promise，而不会停止底层工作——子进程或 fetch socket 会泄漏。分发信号并要求能力监听，才能强制一条真实的终止路径存在。这与「dispose 必须达到完全停稳，而非仅仅请求它」的防御性规则一致。
+**用 `withTimeout(promise, ms)` 包装器代替信号工厂。** 否决，因为让 promise 与定时器竞争只是在截止时间到达时 resolve *工具调用*的 promise，而不会停止底层工作——子进程或 fetch socket 会泄漏。分发信号并要求能力监听，才能强制一条真实的终止路径存在。这与「dispose 必须达到完全停稳，而非仅仅请求它」的防御性规则一致。`idleWatchdog` 是有意保留的例外，且仅针对它所驱动的单个迭代器 demand：交给传输层的信号仍负责释放该读取（中止会销毁 socket），而当传输层永不结算时由截止时间结束该 demand。

 **保留 bash 独立的超时和取消触发器。** 否决，因为一个 deadline 信号移除了定制定时器并标准化了分类。发生竞争时，报告先到达的那个 abort 作为原因，由提供方管理的终止路径不受哪个原因先胜出的影响。
@@ -21,8 +21,8 @@
  en: c35ea4b858448b49
  zh: 1f8ff0a9f82ca881
 /agent-note-single-file-executable-sdk-runtime-distribution-single-exe/decision/build-pipeline-and-artifacts:
-  en: 6356c325e36dc2a8
-  zh: 63da32299cb356c9
+  en: d3bbd24ead02af4f
+  zh: 64623d88bee4314b
 /agent-note-single-file-executable-sdk-runtime-distribution-single-exe/decision/python-sdk-distribution-two-carriers-exe-for-production-node-for-development:
  en: 9bd60549d4a52ec0
  zh: e2343b7210212ee0
@@ -48,7 +48,7 @@ The [Office kit](2026-09-14-independent-libreoffice-kit.md) and its installed de

 ### Build pipeline and artifacts

-[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`, including [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) as the carrier-root `runtime-bootstrap.mjs` → restore direct workspace packages omitted by legacy deploy and reject any remaining manifest gap → replace staged dependency symlinks with their target bytes, remove package-manager `.bin` links, and fail if any symlink remains → verify the deployed bootstrap and inject pkg configuration with that bin plus assets covering dynamic profile, bundle, frontend, preset, native-library, and configuration reads → stage the target `node-pty` addon → invoke `pkg --sea` once per target → write `deepseek-harness-sdk-runtime-<platform>-<arch>` under `dist-exe/` and copy it with its target-specific Office directory into the runtime directory. The Python runtime owns that bootstrap. It calls the public CLI export for ordinary launches and dispatches a provider-private selection to the same `@deepseek-ai/dsh-subprocess-local/runner` core without changing CLI grammar or adding another executable; the [native-containment reference](../../../../packages/subprocess/subprocess-local/README.md) owns that private path. Linux CI rebuilds `pty.node` inside the matching manylinux 2.28 container because legacy deploy omits that install side effect. Every target copies its native `@vscode/ripgrep` binary beside the executable as the required `-rg` sidecar; pkg runtimes select that sidecar through `process.pkg`, while ordinary Node execution uses `@vscode/ripgrep` directly. macOS uses its target prebuild and also emits the required `-spawn-helper`. The deploy flags preserve the measured runtime layout: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted gives pkg a stable single-instance layout that the explicit materialization pass makes symlink-free; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry. Production deployment permits unused workspace patches because development-only tools can be absent from its closure; included-package patch failures still fail deployment. Workspace installs retain strict unused-patch validation.
+[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true --config.hoist-workspace-packages=false` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`, including [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) as the carrier-root `runtime-bootstrap.mjs` → restore direct workspace packages omitted by legacy deploy and reject any remaining manifest gap → replace staged dependency symlinks with their target bytes, remove package-manager `.bin` links, and fail if any symlink remains → verify the deployed bootstrap and inject pkg configuration with that bin plus assets covering dynamic profile, bundle, frontend, preset, native-library, and configuration reads → stage the target `node-pty` addon → invoke `pkg --sea` once per target → write `deepseek-harness-sdk-runtime-<platform>-<arch>` under `dist-exe/` and copy it with its target-specific Office directory into the runtime directory. The Python runtime owns that bootstrap. It calls the public CLI export for ordinary launches and dispatches a provider-private selection to the same `@deepseek-ai/dsh-subprocess-local/runner` core without changing CLI grammar or adding another executable; the [native-containment reference](../../../../packages/subprocess/subprocess-local/README.md) owns that private path. Linux CI rebuilds `pty.node` inside the matching manylinux 2.28 container because legacy deploy omits that install side effect. Every target copies its native `@vscode/ripgrep` binary beside the executable as the required `-rg` sidecar; pkg runtimes select that sidecar through `process.pkg`, while ordinary Node execution uses `@vscode/ripgrep` directly. macOS uses its target prebuild and also emits the required `-spawn-helper`. The deploy flags preserve the measured runtime layout: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted supplies package directories that staging makes symlink-free; staging removes nested workspace copies only when pnpm records the same dependency identity at the payload root, preserving singleton services; disabling workspace hoisting excludes unrelated workspace source packages; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry. Production deployment permits unused workspace patches because development-only tools can be absent from its closure; included-package patch failures still fail deployment. Workspace installs retain strict unused-patch validation.

 CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml) runs [installed-wheel validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md) on Linux/Windows x64 for pull requests and Linux ARM64 plus both macOS architectures for master pushes. The [public publication workflow](../../archived/process/2026-08-11-python-publication-workflow.md) calls it for all five targets; `workflow_dispatch` can still select a subset. Native builds run on linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64 / macos-x64 (`macos-15-intel`) / win-x64 (`windows-2025`), with `~/.pkg-cache` cached where applicable, and pkg handles macOS ad-hoc signing. Each leg installs the release-shaped SDK and runtime wheels into a clean venv outside the checkout, verifies their package and executable origin, then drives the complete keyless scenario set through the public SDK and direct NDJSON JSON-RPC. Trusted pull requests and master pushes additionally run a real DeepSeek two-turn tool smoke on their selected targets; fork and Dependabot heads receive no key. Linux inspects the executable and native addon's GLIBC requirements and runs an additional manylinux 2.28 smoke, while macOS checks the runtime, ripgrep, and PTY helper architectures and verifies that all three deployment targets fit the wheel tag. A full five-target run retains six artifacts, each containing one release file: the platform-independent SDK wheel and five native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts `python-v<repository-version>` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and five native runtime wheels, then a single serialized job checks and publishes all six to the project PyPI registry. The [`python/sdk-runtime` README](../../../../python/sdk-runtime/README.md) owns the Windows target and the explicit exclusion of Windows arm64.

@@ -48,7 +48,7 @@ exe 的 VFS 内是**构建产物形态的真实包树**（各包的 `lib/` + 真

 ### 构建流水线与产物

-[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`，其中包含作为载体根目录 `runtime-bootstrap.mjs` 的 [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) → 恢复 legacy deploy 遗漏的直接工作区包，并拒绝剩余的 manifest 缺口 → 将暂存依赖中的符号链接替换为目标文件内容，删除包管理器的 `.bin` 链接，并在仍有任何符号链接时失败 → 验证已部署的 bootstrap，并注入以该文件为 bin 的 pkg 配置及覆盖动态读取 profile、bundle、前端、preset、原生库与配置文件的 assets → 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea` → 将 `deepseek-harness-sdk-runtime-<platform>-<arch>` 写入 `dist-exe/`，并将它与对应目标的 Office 目录一同拷回运行时目录。该 bootstrap 由 Python runtime 拥有；普通启动时它调用公开 CLI export，而提供方私有选择会分派到同一个 `@deepseek-ai/dsh-subprocess-local/runner` 核心，不改变 CLI 语法，也不增加另一个可执行文件；[原生 containment 参考](../../../../packages/subprocess/subprocess-local/README.zh.md)负责这条私有路径。Linux CI 会在匹配的 manylinux 2.28 容器中重新构建 `pty.node`，因为 legacy deploy 会遗漏这一安装副作用。每个目标都会把对应的原生 `@vscode/ripgrep` 二进制复制到可执行文件旁，作为必需的 `-rg` 伴随文件；pkg 运行时通过 `process.pkg` 选择该伴随文件，普通 Node 执行则直接使用 `@vscode/ripgrep`。macOS 使用对应目标的预构建产物，并额外生成所需的 `-spawn-helper`。部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 为 pkg 提供稳定的单实例布局，再由显式物化步骤消除符号链接；关闭对等依赖自动安装可防止未声明的对等依赖扩大闭包；`link-workspace-packages` 选择直接工作区依赖。[`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) 将传递的 `@deepseek-ai/cosmokit` 与 `@deepseek-ai/schemastery` semver 请求覆盖到固定的 vendor 源码，使 legacy deploy 不会从注册表解析这些未发布名称。 生产部署允许未使用的工作区补丁，因为开发工具可能不属于运行时闭包；闭包内包的补丁应用失败仍会中止部署。工作区安装继续严格校验未使用的补丁。
+[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true --config.hoist-workspace-packages=false` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`，其中包含作为载体根目录 `runtime-bootstrap.mjs` 的 [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) → 恢复 legacy deploy 遗漏的直接工作区包，并拒绝剩余的 manifest 缺口 → 将暂存依赖中的符号链接替换为目标文件内容，删除包管理器的 `.bin` 链接，并在仍有任何符号链接时失败 → 验证已部署的 bootstrap，并注入以该文件为 bin 的 pkg 配置及覆盖动态读取 profile、bundle、前端、preset、原生库与配置文件的 assets → 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea` → 将 `deepseek-harness-sdk-runtime-<platform>-<arch>` 写入 `dist-exe/`，并将它与对应目标的 Office 目录一同拷回运行时目录。该 bootstrap 由 Python runtime 拥有；普通启动时它调用公开 CLI export，而提供方私有选择会分派到同一个 `@deepseek-ai/dsh-subprocess-local/runner` 核心，不改变 CLI 语法，也不增加另一个可执行文件；[原生 containment 参考](../../../../packages/subprocess/subprocess-local/README.zh.md)负责这条私有路径。Linux CI 会在匹配的 manylinux 2.28 容器中重新构建 `pty.node`，因为 legacy deploy 会遗漏这一安装副作用。每个目标都会把对应的原生 `@vscode/ripgrep` 二进制复制到可执行文件旁，作为必需的 `-rg` 伴随文件；pkg 运行时通过 `process.pkg` 选择该伴随文件，普通 Node 执行则直接使用 `@vscode/ripgrep`。macOS 使用对应目标的预构建产物，并额外生成所需的 `-spawn-helper`。部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 提供包目录，再由暂存步骤消除符号链接；只有 pnpm 在载荷根目录记录了相同依赖标识时，暂存步骤才删除对应的嵌套工作区副本，以保留服务单例；关闭工作区提升可排除无关的工作区源码包；关闭对等依赖自动安装可防止未声明的对等依赖扩大闭包；`link-workspace-packages` 选择直接工作区依赖。[`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) 将传递的 `@deepseek-ai/cosmokit` 与 `@deepseek-ai/schemastery` semver 请求覆盖到固定的 vendor 源码，使 legacy deploy 不会从注册表解析这些未发布名称。 生产部署允许未使用的工作区补丁，因为开发工具可能不属于运行时闭包；闭包内包的补丁应用失败仍会中止部署。工作区安装继续严格校验未使用的补丁。

 CI 使用 [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)：[安装后 wheel 包验证](../testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md)在拉取请求上运行 Linux/Windows x64，在 master 推送上运行 Linux ARM64 与两种 macOS 架构。[公开发布工作流](../../archived/process/2026-08-11-python-publication-workflow.md)调用它构建全部五个目标；`workflow_dispatch` 仍可选择部分目标。linux-x64、linux-arm64（`ubuntu-24.04-arm`）、macos-arm64、macos-x64（`macos-15-intel`）与 win-x64（`windows-2025`）分别进行原生构建，并在适用平台缓存 `~/.pkg-cache`；macOS 的 ad-hoc 签名由 pkg 处理。每个平台都把发布形态的 SDK wheel 包与运行时 wheel 包安装到 checkout 外的干净 venv，证明包与可执行文件来源，再通过公开 SDK 与直接 NDJSON JSON-RPC 运行完整 keyless 场景。可信拉取请求与 master 推送还会在各自选定的目标上运行真实 DeepSeek 双轮工具冒烟测试；fork 与 Dependabot head 不会获得密钥。Linux 会检查可执行文件和原生 addon 各自的 GLIBC 依赖，并额外运行 manylinux 2.28 冒烟测试；macOS 则检查 runtime、ripgrep 与 PTY helper 的架构，并验证三个载荷的部署目标都符合 wheel 包标签。完整构建五个目标时保留 6 个产物，每个产物只含一个发布文件：平台无关的 SDK wheel 包与 5 个原生运行时 wheel 包；手动选择部分目标时保留 SDK wheel 与所选运行时 wheel。裸 exe 与源码包只作为测试中间输入。[`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) 只接受版本与根目录 `package.json` 匹配的 `python-v<repository-version>` 标签流水线，构建一个 SDK wheel 包和 5 个原生运行时 wheel 包，再由单个串行任务校验并将这 6 个文件发布到项目的 PyPI 注册表。[`python/sdk-runtime` README](../../../../python/sdk-runtime/README.zh.md)负责 Windows 目标及对 Windows arm64 的明确排除。

@@ -21,8 +21,8 @@
  en: 0efad389c38dfe95
  zh: 13dd73de20226540
 /agent-note-separate-context-injection-from-turn-execution/verification:
-  en: 3f3db450a3fc5848
-  zh: b2027393d570339d
+  en: 56fe8195ed669f6d
+  zh: 503ca0ce723c69b1
 /agent-note-separate-context-injection-from-turn-execution/consequences:
  en: 71079e4dede5e12f
  zh: deb46b5a4f151678
@@ -64,7 +64,7 @@ This decision preserves the caller-owned framing decision from [unwrapped inject
 - Idle `inject()` immediately appends one durable inbox insertion but no model-visible `user/message`; a later waking delivery may start pre-step processing.
 - Active-turn injection is claimed at the nearest later pre-step boundary, after complete tool-result batches and before the request that consumes it.
 - Rejected or failed pre-step drops its claimed batch; input inserted after the claim remains pending.
- Unit, persistence/resume, invariant, and TUI coverage pin event order, claim ownership, and durable replay.
+- Unit, persistence/resume, and TUI coverage pin event order, claim ownership, and durable replay.

 ## Consequences

@@ -64,7 +64,7 @@ enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。wate
 - idle 状态下的 `inject()` 会立即追加一条持久 inbox 插入记录，但不会追加模型可见的 `user/message`；后续可唤醒投递可能开始 pre-step 处理。
 - 活跃轮次中的注入会在最近的后续 pre-step 边界领取，并位于完整工具结果批次之后、消费它的请求之前。
 - pre-step reject 或失败会丢弃其已领取批次；领取后插入的输入继续保持待处理。
- 单元测试、持久化与 resume 测试、不变量测试和 TUI 覆盖会固定事件顺序、领取归属和持久回放。
+- 单元测试、持久化与 resume 测试和 TUI 覆盖会固定事件顺序、领取归属和持久回放。

 ## 后果

@@ -9,8 +9,8 @@
  en: fa4d3622fb18dd58
  zh: 2b98640594c8344b
 /agent-note-one-harness-home-resolver/decision:
-  en: bbab99c7a1aae2fc
-  zh: 87453b98ca265699
+  en: 816e5109718bc4ae
+  zh: af3f08f07c3cb761
 /agent-note-one-harness-home-resolver/alternatives-considered:
  en: b1c9535540171d47
  zh: 7df816d42945db94
@@ -21,7 +21,7 @@ One resolver owns the harness home, in `@deepseek-ai/dsh-home-paths`, single-roo
 explicit configured path  >  $DSH_HOME  >  ~/.dsh
 ```

-An empty or whitespace-only `$DSH_HOME` is treated as unset; otherwise `resolve('')` would silently place the home at the current working directory. The harness keeps all user data under one root; there is no XDG config/data/cache split. `dshHomePath(...segments)` joins deployment-owned children onto that root, and `dsh-app-boot` exposes it to Loader `!!js` config expressions before mounting entries, so shipped compositions derive `sessions` and `storages` without copying the resolver. `dshHomeDisplay()` names a resolved root symbolically for user-facing paths — `~/.dsh` for the default home, `$DSH_HOME` for any configured home — so the user-global `AGENTS.md` label never leaks an absolute machine path. It replaces agent-instructions's bespoke default-vs-`$DSH_HOME` check.
+An empty or whitespace-only `$DSH_HOME` is treated as unset; otherwise `resolve('')` would silently place the home at the current working directory. The harness keeps all user data under one root; there is no XDG config/data/cache split. `dshHomePath(...segments)` joins deployment-owned children onto that root, and `dsh-app-boot` exposes it to Loader `!!js` config expressions before mounting entries, so shipped compositions derive `sessions` and `storages` without copying the resolver. `dshHomeDisplay()` names a resolved root symbolically for user-facing paths — `~/.dsh` for the default home, `$DSH_HOME` for any configured home — so the user-global `AGENTS.md` label never leaks an absolute machine path. It replaces agent-instructions's bespoke default-vs-`$DSH_HOME` check. Home is process policy rather than row configuration: `dsh-agent-instructions` accepts no home override, so a composition cannot point instruction loading at a root that sessions, skills, and storage would not read. `resolveAgentsHome()` and `agentsHomeDisplay()` apply the same precedence, tilde expansion, and symbolic labelling to the shared agent configuration root (`$DSH_AGENTS_HOME` or `~/.agents`), which stays outside the harness home because other agent tools share it ([shared agents root](2026-10-05-shared-agents-root-instructions.md)); `dsh-skill-filesystem` still accepts its own `dshHome` and `agentsHome` fields, which select its own skill roots and resolve through the shared resolver in the instruction-loading change.

 `dshCachePath(...segments)` derives paths below the resolved home's `cache` directory. An initial `{ dshHome }` option preserves a provider's explicit home override. It resolves paths without creating directories; callers own directory creation. `attachment-local` uses this helper for regenerable request-image variants while retaining durable attachment objects in their versioned storage tree, so clearing the cache cannot remove Session attachments. Existing request-image cache entries are left in place and are not read or copied; a cache miss regenerates the variant from its durable attachment.

@@ -21,7 +21,7 @@ Status: implemented
 explicit configured path  >  $DSH_HOME  >  ~/.dsh
 ```

-空或仅含空白的 `$DSH_HOME` 被当作未设置处理；否则，`resolve('')` 会悄悄把 home 落在当前工作目录。harness 把所有用户数据都放在同一个根目录下；不存在 XDG 的 config/data/cache 拆分。`dshHomePath(...segments)` 将部署负责的子路径拼接到该根目录下，`dsh-app-boot` 在挂载条目前向 Loader `!!js` 配置表达式暴露它，因此出厂组合无需复制解析器即可派生 `sessions` 和 `storages`。`dshHomeDisplay()` 为面向用户的路径以符号形式命名已解析的根目录——默认 home 显示为 `~/.dsh`，任何已配置的 home 显示为 `$DSH_HOME`——这样用户全局的 `AGENTS.md` 标签就绝不会泄露机器上的绝对路径。它取代了 agent-instructions 中自定义的「默认值 vs `$DSH_HOME`」判断。
+空或仅含空白的 `$DSH_HOME` 被当作未设置处理；否则，`resolve('')` 会悄悄把 home 落在当前工作目录。harness 把所有用户数据都放在同一个根目录下；不存在 XDG 的 config/data/cache 拆分。`dshHomePath(...segments)` 将部署负责的子路径拼接到该根目录下，`dsh-app-boot` 在挂载条目前向 Loader `!!js` 配置表达式暴露它，因此出厂组合无需复制解析器即可派生 `sessions` 和 `storages`。`dshHomeDisplay()` 为面向用户的路径以符号形式命名已解析的根目录——默认 home 显示为 `~/.dsh`，任何已配置的 home 显示为 `$DSH_HOME`——这样用户全局的 `AGENTS.md` 标签就绝不会泄露机器上的绝对路径。它取代了 agent-instructions 中自定义的「默认值 vs `$DSH_HOME`」判断。home 属于进程策略而非配置行：`dsh-agent-instructions` 不接受 home 覆盖，因此组合无法把指令加载指向会话、skill 与存储不会读取的根目录。`resolveAgentsHome()` 与 `agentsHomeDisplay()` 对共享 agent 配置根目录（`$DSH_AGENTS_HOME` 或 `~/.agents`）采用相同的优先级、波浪号展开与符号化标签；该根目录位于 harness home 之外，因为其他 agent 工具会共享它（[共享 agents 根目录](2026-10-05-shared-agents-root-instructions.zh.md)）；`dsh-skill-filesystem` 仍接受自己的 `dshHome` 与 `agentsHome` 字段，用于选择它自己的 skill 根目录，并在指令加载改动中改用共享解析器。

 `dshCachePath(...segments)` 在解析出的主目录下的 `cache` 目录中派生路径。首个 `{ dshHome }` 选项保留提供方显式配置的主目录覆盖值。它只解析路径，不创建目录；目录创建由调用方负责。`attachment-local` 将此函数用于可重新生成的请求图片版本，持久附件对象仍保留在其带版本的存储树中，因此清空缓存不会删除 Session 附件。已有请求图片缓存条目保留在原处，不再读取或复制；缓存未命中时从持久附件重新生成请求版本。

@@ -9,8 +9,8 @@
  en: 41363fca57ae20e6
  zh: 1d05eeeecaafa7f3
 /agent-note-terminal-llm-stream-failures/decision:
-  en: c3bfde5f736f8b27
-  zh: f51ebb4089df6406
+  en: dd1dd01dda70bfb7
+  zh: 8715075a5be2f7b7
 /agent-note-terminal-llm-stream-failures/alternatives-considered:
  en: 46153a92b2135aae
  zh: 0b8fdaf1f7edeb77
@@ -16,7 +16,7 @@ Retry policy had the same indirect ownership. It was discovered through the stre

 `LlmRuntime` is the normalization boundary for one adapter attempt. It catches only final-adapter selection, synchronous dispatch, iterator construction, and `next()` failures, converts the thrown value to immutable `LlmFailure`, and emits one terminal `finish`. Caller cancellation or an `ABORTED` failure selects the aborted reason; every other adapter failure selects error. An adapter may also emit either terminal reason directly.

-The adapter-owned catch ends before each yielded chunk. Errors from `llm/stream` middleware, nested calls, adapter cleanup, chunk consumers, logging, signal checks, and assembly remain thrown as defects or lifecycle failures; they never enter model-request recovery. A transport failure after partial deltas may leave blocks open, so the stream invariant permits open blocks only for terminal error or aborted finishes. No assistant message or tool call is assembled from that incomplete output.
+The adapter-owned catch ends before each yielded chunk. Errors from `llm/stream` middleware, nested calls, adapter cleanup, chunk consumers, logging, signal checks, and assembly remain thrown as defects or lifecycle failures; they never enter model-request recovery. A transport failure after partial deltas may leave blocks open before a terminal error or aborted finish. No assistant message or tool call is assembled from that incomplete output.

 `PreparedLlmCall` exposes the immutable retry policy captured with its config and registration. One-shot reuse and config mismatch remain synchronous `INVALID_PREPARED_CALL` misuse errors. A route served entirely by `llm/stream` middleware has no prepared registration and therefore no serving policy.

@@ -16,7 +16,7 @@ Status: implemented

 `LlmRuntime` 是一次适配器尝试的规范化边界。它只捕获最终适配器选择、同步分发、iterator 构造与 `next()` 失败，将抛出值转换为不可变 `LlmFailure`，并发出一个终止 `finish`。调用方取消或 `ABORTED` 失败选择 aborted 结束原因；其他适配器失败选择 error 结束原因。适配器也可以直接发出任一终止原因。

-适配器所属的 catch 会在每个分片被 yield 前结束。来自 `llm/stream` middleware、嵌套调用、适配器清理、分片消费方、日志记录、signal 检查与组装的错误仍作为缺陷或生命周期失败抛出；它们绝不进入模型请求恢复。部分 delta 之后的传输失败可能留下未关闭块，因此流 invariant 只允许在终止 finish 的结束原因为 error 或 aborted 时存在未关闭块。不会从这些不完整输出组装 assistant 消息或工具调用。
+适配器所属的 catch 会在每个分片被 yield 前结束。来自 `llm/stream` middleware、嵌套调用、适配器清理、分片消费方、日志记录、signal 检查与组装的错误仍作为缺陷或生命周期失败抛出；它们绝不进入模型请求恢复。部分 delta 之后的传输失败可能在结束原因为 error 或 aborted 的终止 finish 之前留下未关闭块。不会从这些不完整输出组装 assistant 消息或工具调用。

 `PreparedLlmCall` 公开随其配置和注册捕获的不可变重试策略。一次性句柄复用与配置不匹配仍是同步的 `INVALID_PREPARED_CALL` 误用错误。完全由 `llm/stream` middleware 提供服务的路由没有准备完成的注册，因此也没有服务策略。

@@ -9,8 +9,8 @@
  en: 6228c81e4965b688
  zh: 04b702be0cfbf195
 /agent-note-credential-boundaries-whole-snapshot-requests-and-atomic-route-registration/decision:
-  en: d2aa88cf1e9ec97b
-  zh: da9422723fc9ac93
+  en: 052787311a4e6edc
+  zh: 963eed632ea198de
 /agent-note-credential-boundaries-whole-snapshot-requests-and-atomic-route-registration/alternatives-considered:
  en: 90c5883b247f7301
  zh: 6d2a660d8653f805
@@ -22,7 +22,7 @@ Two request-path defects sat beside them. DeepSeek resolved connection and crede

 **Route replacement is a registry operation, not a caller sequence.** `registerAdapter` returns a handle carrying `replace(providers)`: the candidate set is validated in full first (conflicts, names, provider metadata), then swapped in one synchronous section. A refused replacement leaves the previous routes registered and serving, and the caller's facts cache only advances after the registry actually holds the new set, so reverting to a working configuration re-applies. pi-ai's registration facts are sorted by provider, so a settings document that merely reorders its keys is no longer a route change.

-**Contained publication for committed credential writes.** `CredentialProvider.notifyUpdated` fans `credentials/reference-updated` out one listener at a time; sync throws and async rejections are logged without changing the committed operation's outcome, and `INVARIANT`-coded failures rethrow after every listener ran — the same shape the settings seam uses for `settings/updated`. `SettingsProvider.installSection()` cleanup distinguishes its two triggers: a provider detaching still falls back to the composition entry and re-derives, while the consumer's own unload returns immediately instead of re-registering routes during teardown.
+**Contained publication for committed credential writes.** `CredentialProvider.notifyUpdated` fans `credentials/reference-updated` out one listener at a time; sync throws and async rejections are logged without changing the committed operation's outcome. `SettingsProvider.installSection()` cleanup distinguishes its two triggers: a provider detaching still falls back to the composition entry and re-derives, while the consumer's own unload returns immediately instead of re-registering routes during teardown.

 ## Alternatives considered

@@ -26,7 +26,7 @@ Status: implemented

 **路由替换是注册表的操作，不是调用方的一串步骤。**`registerAdapter` 返回一个携带 `replace(providers)` 的句柄：候选集合先被完整校验（冲突、名称、提供方元数据），再在一个同步区段内完成替换。被拒绝的替换会让先前的路由保持注册并继续服务，而调用方的事实缓存只有在注册表确实持有新集合之后才会推进，因此改回可用配置时会重新生效。pi-ai 的注册事实按提供方排序，因此仅仅调换键顺序的设置文档不再算作路由变更。

-**已提交的凭据写入采用收容式发布。**`CredentialProvider.notifyUpdated` 逐个监听器扇出 `credentials/reference-updated`；同步抛错与异步 rejection 都只记日志，不改变已提交操作的结果，而带 `INVARIANT` 代码的失败会在每个监听器都运行完之后重抛——与 settings seam 处理 `settings/updated` 的形状相同。`SettingsProvider.installSection()` 的清理会区分它的两个触发来源：提供方脱离时仍回退到组合的 entry 配置并重新推导，而消费方自身卸载时立即返回，不在拆卸过程中重新注册路由。
+**已提交的凭据写入采用收容式发布。**`CredentialProvider.notifyUpdated` 逐个监听器扇出 `credentials/reference-updated`；同步抛错与异步 rejection 都只记日志，不改变已提交操作的结果。`SettingsProvider.installSection()` 的清理会区分它的两个触发来源：提供方脱离时仍回退到组合的 entry 配置并重新推导，而消费方自身卸载时立即返回，不在拆卸过程中重新注册路由。

 ## 曾考虑的替代方案

@@ -15,5 +15,5 @@
  en: 7d79dfa834d9168f
  zh: 0b3e82a7d0ef71b9
 /agent-note-goal-owned-durable-events/consequences:
-  en: 0e4513ea5e3e1e2e
-  zh: 69d81ba52ee2f4b6
+  en: b2a2f902f126f318
+  zh: 8a38fe8acb0a2241
@@ -28,6 +28,6 @@ The domain does not automatically project each mutation into model input. Goal t

 ## Consequences

-Goal state is independent of inbox placement and admission. Replay has one mutation path, projections advance directly on `goal/change`, and continuation messages carry only round attribution. The model does not receive a mutation-only `<goal_state>` message; model-visible state appears through goal tools and scheduled continuation prompts. Direct session writers remain trusted and can append malformed changes, which the strict fold and invariant companion reject.
+Goal state is independent of inbox placement and admission. Replay has one mutation path, projections advance directly on `goal/change`, and continuation messages carry only round attribution. The model does not receive a mutation-only `<goal_state>` message; model-visible state appears through goal tools and scheduled continuation prompts. Direct session writers remain trusted and can append malformed changes, which the strict fold rejects.

 Focused goal, goal-round-driver, command, TUI, and Client RemoteMock tests pin durable replay, positive-round accounting, inbox independence, projection updates, and restored-session behavior. The keyless process test inspects the persisted `goal/change` event and verifies that creation alone starts no continuation round.
@@ -28,6 +28,6 @@ Goal 领域需要持久状态，但不需要拥有待处理的模型输入。继

 ## 后果

-Goal 状态不依赖 inbox 放置与准入。回放只有一条变更路径，投影直接由 `goal/change` 推进，继续执行消息只携带 Round 归属。模型不会收到仅用于变更的 `<goal_state>` 消息；模型可见状态来自 goal 工具与已调度的继续执行提示词。直接写入会话的写入方仍受信任，并且可以追加畸形变更；严格折叠与 invariant 配套模块会拒绝这些变更。
+Goal 状态不依赖 inbox 放置与准入。回放只有一条变更路径，投影直接由 `goal/change` 推进，继续执行消息只携带 Round 归属。模型不会收到仅用于变更的 `<goal_state>` 消息；模型可见状态来自 goal 工具与已调度的继续执行提示词。直接写入会话的写入方仍受信任，并且可以追加畸形变更；严格折叠会拒绝这些变更。

 聚焦的 goal、goal-round-driver、command、TUI 与 Client RemoteMock 测试固定持久回放、正数 Round 计数、inbox 独立性、投影更新和恢复会话行为。无密钥进程测试检查持久的 `goal/change` 事件，并验证仅创建 goal 不会启动继续执行 Round。
@@ -9,17 +9,17 @@
  en: 2c36946bbff637b7
  zh: f290de0866ba7caa
 /agent-note-the-ptc-runtime-python-fd-3-frame-protocol/decision:
-  en: 1f93159850fc7f48
-  zh: dcc2a4788e3254f7
+  en: f0d0d5ba5a9066ad
+  zh: fbdab3731c33eb26
 /agent-note-the-ptc-runtime-python-fd-3-frame-protocol/wire-contract:
-  en: 913f9465320dc191
-  zh: f8e0338645d6c204
+  en: 1225a32af91fcf84
+  zh: 1dab4ecbd9ff7e34
 /agent-note-the-ptc-runtime-python-fd-3-frame-protocol/mirror-alignment:
  en: 26128b65f2763920
  zh: df24359faebcbfed
 /agent-note-the-ptc-runtime-python-fd-3-frame-protocol/alternatives-considered:
-  en: cc42636bd7793305
-  zh: e196f980daec3037
+  en: 2f52b91980d013ed
+  zh: 12dc9a24c03c3c68
 /agent-note-the-ptc-runtime-python-fd-3-frame-protocol/consequences:
  en: 16df6efd46d71e85
  zh: 4062475bec04ab5f
@@ -22,11 +22,11 @@ The experimental package contains both the protocol and runtime implementation:

 `py/protocol.py` mirrors the message shapes as `TypedDict`s and re-declares the two surfaces both sides EXECUTE against — `PROTOCOL_FD = 3` and `log_truncation_marker` — with byte-identical text.

-The package ships the runtime alongside the protocol; it remains independently buildable. `check-workspace-constraints` reads every `packages/<group>/<pkg>/package.json` unconditionally, while the coverage and invariant-topology checks exercise the package as soon as its directory exists.
+The package ships the runtime alongside the protocol; it remains independently buildable. `check-workspace-constraints` reads every `packages/<group>/<pkg>/package.json` unconditionally, while the coverage check exercises the package as soon as its directory exists.

 ## Wire contract

-Frames are JSON-lines on fd 3, one object per line, leaving stdout/stderr free for the program's own output. Child → host: `boot-ack`, `call`, `log`, `done`. Host → child: `boot` (first frame), `run` (after `boot-ack`), and one `reply` per `call`. The `log` frame's `truncated` flag marks the frame that IS the child ledger's own truncation marker, so the host stops capturing at the same point the child did instead of inferring it from its own budget. The `log` frame's `open` flag marks an unterminated line committed by an explicit flush: the host holds it and appends the next frame to the same entry, so an explicit flush followed by more text reads back as one line rather than a fake newline. The one exception is truncation: when a later over-budget frame trips the ledger, the already-billed prefix is committed as its own entry and the truncation marker follows it (marker last, no re-charge). The merged entry's wire cost is billed exactly once, split incrementally across its fragments on both sides (O(k) for k fragments, never a re-walk of the whole hold): the FIRST fragment pays the full JSON-string cost plus the separator, each continuation and the closing frame pay only their content; the host's exact-cost caps are `logBudget - 1` for a first fragment (the ledger's reserved byte, matching `admit`) and `logBudget + 2` for a continuation or closing frame (billed without the two quotes), and `jsonStringCostUpTo` returns `undefined` below a 2-byte cap; the child keys its split billing off `_open_started` alone, so a closing frame bills as the merged tail. `done.error.kind` is one of `exception`, `invalid-output`, `output-limit`; wall/CPU budgets, aborts, and substrate death are observed host-side, not carried as frames.
+Frames are JSON-lines on fd 3, one object per line, leaving stdout/stderr free for the program's own output. Child → host: `boot-ack`, `call`, `log`, `done`. Host → child: `boot` (first frame), `run` (after `boot-ack`), and one `reply` per `call`. The `log` frame's `truncated` flag marks the frame that IS the child ledger's own truncation marker, so the host stops capturing at the same point the child did instead of inferring it from its own budget. The `log` frame's `open` flag marks an unterminated line committed by an explicit flush: the host holds it and appends the next frame to the same entry, so an explicit flush followed by more text reads back as one line rather than a fake newline. The one exception is truncation: when a later over-budget frame trips the ledger, the already-billed prefix is committed as its own entry and the truncation marker follows it (marker last, no re-charge). The merged entry's wire cost is billed exactly once, split incrementally across its fragments on both sides (O(k) for k fragments, never a re-walk of the whole hold): the FIRST fragment pays the full JSON-string cost plus the separator, each continuation and the closing frame pay only their content; the host's exact-cost caps are `logBudget - 1` for a first fragment (the ledger's reserved byte, matching `admit`) and `logBudget + 2` for a continuation or closing frame (billed without the two quotes), and `jsonStringCostUpTo` returns `undefined` below a 2-byte cap; the child keys its split billing off `_open_started` alone, so a closing frame bills as the merged tail. `done.error.kind` is one of `exception`, `invalid-output`, `output-limit`, or `timeout` from the CPU check after model code returns; wall deadlines, aborts, and substrate death are observed host-side. The post-return CPU check attempts a diagnostic on fd 3 before mandatory signal termination because a sandbox launcher can convert that signal into an ambiguous exit code. Ordinary soft-limit expiry retains default `SIGXCPU` termination without a Python handler, so native calls cannot postpone enforcement until Python resumes. These frames remain untrusted outcome reports; kernel resource limits enforce the CPU ceiling independently.

 ## Mirror alignment

@@ -36,7 +36,7 @@ Frames are JSON-lines on fd 3, one object per line, leaving stdout/stderr free f

 **Require a future Python JSON codec (`_encode_json_plain` / `_decode_json_plain`) to live in `py/protocol.py` for cross-side symmetry with `protocol.ts`.** Rejected. The repository's "prefer symmetry for parallel values" rule points at genuinely parallel values; these are not. The host-side codec in `protocol.ts` validates hostile input and is self-contained. A child-side codec would produce trusted output and belong with bootstrap-owned emission and cost accounting; forcing only its entry points into `protocol.py` would couple the vocabulary mirror to runtime internals or create an import cycle. `protocol.py` remains a pure wire-vocabulary mirror; the codec (`_encode_json_plain` / `_decode_json_plain`) lives in `bootstrap.py` with the runtime it serves.

-**Keep the protocol files outside a buildable package until a runtime ships.** Rejected: the workspace-constraint, coverage, and invariant-topology checks require every directory under `packages/<group>/<pkg>` to be a buildable package, and the protocol has independent tests and a public wire vocabulary.
+**Keep the protocol files outside a buildable package until a runtime ships.** Rejected: the workspace-constraint and coverage checks require every directory under `packages/<group>/<pkg>` to be a buildable package, and the protocol has independent tests and a public wire vocabulary.

 ## Consequences

@@ -22,11 +22,11 @@ CPython PTC 运行时位于 `packages/experimental/ptc-runtime-python`，以 `@d

 `py/protocol.py` 用 `TypedDict` 镜像消息形状，并重新声明两侧都会 EXECUTE 的两个面——`PROTOCOL_FD = 3` 与 `log_truncation_marker`——文本逐字节一致。

-该包随协议一起交付 runtime，同时保持独立可构建。`check-workspace-constraints` 会无条件读取每个 `packages/<group>/<pkg>/package.json`，coverage 与 invariant-topology 检查则会在包目录存在时立即覆盖该包。
+该包随协议一起交付 runtime，同时保持独立可构建。`check-workspace-constraints` 会无条件读取每个 `packages/<group>/<pkg>/package.json`，coverage 检查则会在包目录存在时立即覆盖该包。

 ## Wire contract

-帧是 fd 3 上的 JSON-lines，每行一个对象，让 stdout/stderr 空出给程序自己的输出。Child → host：`boot-ack`、`call`、`log`、`done`。Host → child：`boot`（首帧）、`run`（在 `boot-ack` 之后）、以及每个 `call` 对应一个 `reply`。`log` 帧的 `truncated` 标志标记那个本身就是子进程 ledger 截断标记的帧，使 host 在与子进程相同的点停止捕获，而不是从自己的预算去推断。`log` 帧的 `open` 标志标记由显式 flush 提交的未结束行：宿主持有它并把下一个帧追加到同一条目，因此显式 flush 后接更多文本读回为一行而不是假换行。唯一例外是截断：当后续超预算帧触发账本时，已计费的前缀作为独立条目先提交，截断 marker 跟在后面（marker 保持末位，无重复计费）。合并条目的线上成本恰好计费一次，在两侧按片段增量分摊（k 个片段 O(k)，绝不对整个持有重走）：首片段付完整 JSON 字符串成本加分隔符，每个续接与闭合帧只付内容；宿主精确成本 cap 是首片段 `logBudget - 1`（账本预留字节，与 `admit` 一致）、续接或闭合帧 `logBudget + 2`（不含两个引号计费），且 `jsonStringCostUpTo` 在低于 2 字节 cap 时返回 `undefined`；子进程按 `_open_started` 单独键控拆分计费，因此闭合帧按合并尾部计费。`done.error.kind` 是 `exception`、`invalid-output`、`output-limit` 之一；wall/CPU 预算、abort、substrate 死亡都在 host 侧观测，不作为帧携带。
+帧是 fd 3 上的 JSON-lines，每行一个对象，让 stdout/stderr 空出给程序自己的输出。Child → host：`boot-ack`、`call`、`log`、`done`。Host → child：`boot`（首帧）、`run`（在 `boot-ack` 之后）、以及每个 `call` 对应一个 `reply`。`log` 帧的 `truncated` 标志标记那个本身就是子进程 ledger 截断标记的帧，使 host 在与子进程相同的点停止捕获，而不是从自己的预算去推断。`log` 帧的 `open` 标志标记由显式 flush 提交的未结束行：宿主持有它并把下一个帧追加到同一条目，因此显式 flush 后接更多文本读回为一行而不是假换行。唯一例外是截断：当后续超预算帧触发账本时，已计费的前缀作为独立条目先提交，截断 marker 跟在后面（marker 保持末位，无重复计费）。合并条目的线上成本恰好计费一次，在两侧按片段增量分摊（k 个片段 O(k)，绝不对整个持有重走）：首片段付完整 JSON 字符串成本加分隔符，每个续接与闭合帧只付内容；宿主精确成本 cap 是首片段 `logBudget - 1`（账本预留字节，与 `admit` 一致）、续接或闭合帧 `logBudget + 2`（不含两个引号计费），且 `jsonStringCostUpTo` 在低于 2 字节 cap 时返回 `undefined`；子进程按 `_open_started` 单独键控拆分计费，因此闭合帧按合并尾部计费。`done.error.kind` 是 `exception`、`invalid-output`、`output-limit` 或模型代码返回后 CPU 检查产生的 `timeout` 之一；wall 截止、abort 和 substrate 死亡在 host 侧观测。返回后的 CPU 检查会在强制信号终止前尝试通过 fd 3 报告诊断，因为沙箱 launcher 可能把该信号转换为有歧义的退出码。普通软限制到期保留默认的 `SIGXCPU` 终止行为，不安装 Python handler，因此原生调用不能把强制执行延后到 Python 恢复运行。这些帧仍是不可信的结果报告；内核资源限制独立强制执行 CPU 上限。

 ## Mirror alignment

@@ -36,7 +36,7 @@ CPython PTC 运行时位于 `packages/experimental/ptc-runtime-python`，以 `@d

 **要求未来的 Python JSON codec（`_encode_json_plain` / `_decode_json_plain`）放进 `py/protocol.py`，以便与 `protocol.ts` 跨侧对称。**拒绝。仓库的 “prefer symmetry for parallel values” 规则指向真正平行的值；这两者不是。`protocol.ts` 中的 host 侧 codec 校验敌意输入且自包含。Child 侧 codec 会产出受信任输出，应与 bootstrap 拥有的发出逻辑和成本核算放在一起；只把入口强塞进 `protocol.py` 会让 vocabulary 镜像耦合 runtime 内部实现，或制造 import 环。`protocol.py` 保持纯 wire-vocabulary 镜像；codec（`_encode_json_plain`／`_decode_json_plain`）与它所服务的 runtime 一起位于 `bootstrap.py`。

-**在 runtime 交付前把协议文件放在不可构建的包外。**拒绝：workspace-constraint、coverage 与 invariant-topology 检查要求 `packages/<group>/<pkg>` 下的每个目录都是可构建包，而协议本身拥有独立测试与公开 wire vocabulary。
+**在 runtime 交付前把协议文件放在不可构建的包外。**拒绝：workspace-constraint 与 coverage 检查要求 `packages/<group>/<pkg>` 下的每个目录都是可构建包，而协议本身拥有独立测试与公开 wire vocabulary。

 ## Consequences

@@ -9,14 +9,14 @@
  en: 1fe344c95a0de36d
  zh: 656c3e0f1117f64e
 /agent-note-forked-children-preserve-the-parent-request-prefix/decision:
-  en: 7461852090348b34
-  zh: ad6c9e0ce65a3e85
+  en: b70aafc9ce30dd00
+  zh: 74e3ff915bd968a9
 /agent-note-forked-children-preserve-the-parent-request-prefix/alternatives-considered:
  en: 80504ffd8331e6c5
  zh: 193261bdde24b4bb
 /agent-note-forked-children-preserve-the-parent-request-prefix/consequences:
-  en: 54c4ce3ee0fee4d2
-  zh: 8a63fb3486c76551
+  en: 0738d36f17c889b5
+  zh: b71ee47f75d6d4e0
 /agent-note-forked-children-preserve-the-parent-request-prefix/consequences/accepted-risks:
  en: f634caa9973eaedb
  zh: 820291096c8e7352
@@ -12,9 +12,11 @@ The earlier shipped composition avoided this mismatch by keeping forked children

 ## Decision

+The shared activation entry point, external execution ownership, and caller-versus-parent result delivery are governed by [Unified subagent activations](../simplification/2026-09-17-unified-subagent-activations.md). This record retains the independent rationale described below.
+
 The model-facing `send_message` tool is registered globally for every Agent in a composition. A continuable forked child therefore receives the same tool name, description, schema, and ordering as its parent. Its initial task is appended after the inherited Session seed, and the task includes the direct parent id plus guidance to return results with `send_message({ agent_id, message })` when that tool is visible to the child.

-The base and headless compositions retain one-shot fork as their conservative lifecycle policy. The `cordis`, `standard`, and `ptc` CLI presets may bind fork to the continuable lifecycle because that binding no longer inserts child-only request-head fields. `ForkInProcessProvider.prepareContinuable()` and `ctx.subagents.startContinuable()` remain the implementation seam for those presets.
+The base bundle and the `cordis`, `standard`, and `ptc` CLI presets bind fork to the continuable lifecycle. Base-backed profiles, including headless, inherit that default. `ForkInProcessProvider.prepareContinuable()` and `ctx.subagents.startActivation()` preserve the same request-prefix behavior across these compositions.

 Byte-identical prefix reuse is qualified by explicit deployment choices. A fork delegation that applies a child persona or `toolFilter` may still change the request head. In particular, filtering out `send_message` removes both the schema and the return guidance from the child; the runtime does not bypass an explicit allow-list.

@@ -32,8 +34,8 @@ Byte-identical prefix reuse is qualified by explicit deployment choices. A fork

 - Parent and continuable-fork child expose byte-identical ordered tool schemas when the delegation does not request a persona or tool filter.
 - The inherited Session seed precedes the child's initial task and return guidance.
- The base and headless profiles keep one-shot fork, while selected CLI presets exercise continuable fork without a child-only request-head addition.
- A child sends zero or more messages to its direct parent explicitly; its final answer is not implicitly copied. The manager-owned settlement notice remains unconditional and separate.
+- The base bundle and full CLI presets use local continuable fork for both parent and caller delivery, without a child-only request-head addition.
+- The child can send messages to its direct parent through `send_message`. Parent delivery adds a separate runtime settlement notice; caller delivery returns the result through the activation receipt.
 - Keyless snapshots and package tests pin schema equality, inherited-history ordering, parent-id guidance, and child-to-parent delivery through the same `send_message` operation used in the other direction.

 ### Accepted risks
@@ -12,9 +12,11 @@ fork 与 spawn 的差异在于：fork 会用 parent 已完成轮次的前缀作

 ## 决策

+共享 activation 入口、外部执行所有权，以及调用方与父级之间的结果投递选择由[统一 subagent activation](../simplification/2026-09-17-unified-subagent-activations.zh.md) 决策拥有。本记录保留下述独立理由。
+
 面向模型的 `send_message` 工具在组合中的每个 Agent 上全局注册。因此，可继续 fork child 获得与 parent 相同的工具名称、描述、schema 和顺序。其初始任务追加在继承的 Session 种子之后；当 child 可以看到该工具时，任务还会包含直接 parent id，以及使用 `send_message({ agent_id, message })` 返回结果的指引。

-base 与 headless 组合保留 one-shot fork 作为其保守生命周期策略。`cordis`、`standard` 和 `ptc` CLI preset 可以把 fork 绑定为可继续生命周期，因为该绑定不再插入 child-only 请求头字段。`ForkInProcessProvider.prepareContinuable()` 与 `ctx.subagents.startContinuable()` 仍是这些 preset 使用的实现 seam。
+base 组合包与 `cordis`、`standard` 和 `ptc` CLI preset 将 fork 绑定为可继续生命周期。基于 base 的 profile（包括 headless）继承这一默认值。`ForkInProcessProvider.prepareContinuable()` 与 `ctx.subagents.startActivation()` 在这些组合中保持相同的请求前缀行为。

 逐字节相同的前缀复用受显式部署选择约束。配置 child persona 或 `toolFilter` 的 fork 委派仍可能改变请求头。尤其是过滤掉 `send_message` 时，child 会同时失去该 schema 与返回指引；运行时不会绕过显式 allow-list。

@@ -32,8 +34,8 @@ base 与 headless 组合保留 one-shot fork 作为其保守生命周期策略

 - 未请求 persona 或工具过滤时，parent 与可继续 fork child 暴露逐字节相同且顺序一致的工具 schema。
 - 继承的 Session 种子位于 child 初始任务及其返回指引之前。
- base 与 headless profile 保持 one-shot fork；选定的 CLI preset 会在没有 child-only 请求头增量的前提下使用可继续 fork。
- child 显式向直接 parent 发送零条或多条消息；最终回答不会被隐式复制。管理器负责的结算通知仍然无条件执行，并且与 Agent 消息分离。
+- base 组合包与完整 CLI preset 对 parent 和 caller 投递均使用本地可继续 fork，不增加 child-only 请求头字段。
+- child 可以通过 `send_message` 向直接 parent 发消息。parent 投递会追加独立的运行时结算通知；caller 投递通过 activation 回执返回结果。
 - keyless snapshot 与包测试固定 schema 相等性、继承历史顺序、parent-id 指引，以及通过同一个 `send_message` 操作完成的 child-to-parent 投递。

 ### 已接受风险
@@ -9,14 +9,14 @@
  en: f060b06cffd3ab9b
  zh: 350ce35558846227
 /agent-note-what-stays-host-plane-once-presets-own-the-agent-plane/decision:
-  en: 60be2f515ff5f46d
-  zh: ee8514deadb08260
+  en: be767ee6f00ac6c3
+  zh: 7742a77e3ea12a5e
 /agent-note-what-stays-host-plane-once-presets-own-the-agent-plane/testing:
-  en: a7b7ca354607dd21
-  zh: f88356bfc7dc770e
+  en: 960fc4b18dff9f38
+  zh: d549e33100351124
 /agent-note-what-stays-host-plane-once-presets-own-the-agent-plane/alternatives-considered:
-  en: eac46307265e647d
-  zh: acfad02f8ca1dc3f
+  en: ca7c9088d0793e1e
+  zh: ea648bac9e726c64
 /agent-note-what-stays-host-plane-once-presets-own-the-agent-plane/consequences:
-  en: d8576d7db9dea547
-  zh: 428bb5a7e609d170
+  en: de26cde94adda770
+  zh: 7f39760b77958966
@@ -18,7 +18,7 @@ Nothing named an agent that joined no preset. The join is a scope-parent link; w

 **The meter is host-plane.** `dsh-token-meter` returns to the host composition and leaves the presets' `isolate` map, so `compaction-basic` and `tool-result-pruner` resolve the one host instance from inside their realm. The presets keep the realm and the backend — what a preset chooses is whether its agent compacts, not whether its tokens are counted. This is the criterion `tasks` and `goals` are already read by, applied to a Service whose *projection* reach is what made preset ownership wrong: a unit whose empty value is indistinguishable from a real one cannot be per-composition while the table it registers into is per-process.

-**An unjoined agent fails at model use.** The invariant companion checks `system-prompt/assemble`, because a bare Agent can legally be bound later through `recompose`. Host-only and cold-scope prompt reads have no Agent and remain outside this check.
+**Entry points join Agents explicitly.** No runtime check rejects an unjoined Agent, because a bare Agent can legally be bound later through `recompose`.

 Projection key presence is not a per-session capability signal ([session projection](../../../../packages/session/session-projection/README.md)). Temporary plugins mounted through `cordis_mount` belong to the composition rather than the invoking session ([tool Cordis](../../../../packages/extensions/tool-cordis/README.md)). [Declarative presets](2026-09-18-declarative-agent-presets.md) own revision retention and reclaim retired trees after their final reference releases.

@@ -26,15 +26,13 @@ Projection key presence is not a per-session capability signal ([session project

 `apps/cli/tests/web-agent-presets.e2e.ts` reads `ctx.get('tokenMeter')` on the booted Web composition before any Agent is created — a preset-side meter sits behind an `isolate` realm and is invisible to `ctx.get`, so the read is an ownership assertion rather than a mount-order coincidence — then asserts a `minimal` session's snapshot carries all three units.

-`packages/preset/agent-preset-registry/tests/invariant.spec.ts` rejects an unjoined Agent's assembly and accepts a joined Agent, a Host read and a cold-scope read.
-
 ## Alternatives considered

 **Keep the meter in the preset and scope-layer the projection registry.** The precise fix, and much larger: `snapshot`, `checkpoint`, and the eager drive would each need a session→scope resolution that a cold read does not have without the api-proxy's `presenterScopeFor`. Rejected as disproportionate to one Service with no per-preset state at all; the general rule is documented on the registry instead.

 **Veto publication for an unjoined agent.** Loud beats silent, and the registry supports it — a synchronous `agent/created` listener that throws rolls the creation back. Rejected because composing an agent outside the roster is legal: `recompose` documents the bare agent it then binds, and the ACP bridge, the SDK server, and the headless bundle all create one. A veto would convert a capability gap into an outage.

-**Check the join at `agent/created` in the companion too.** Rejected: publication cannot distinguish a missed join from an agent that will be bound later, so the check would reject a documented path. Prompt assembly can distinguish them.
+**Check the join at `agent/created`.** Rejected: publication cannot distinguish a missed join from an agent that will be bound later, so the check would reject a documented path.

 **Move `plan-mode` and `tool-todo` off the agent plane for the same projection reason.** Rejected: both are genuinely per-preset capabilities, and their units compute an empty value for a session that never uses them, which clients already read by value (`plan.active`, an empty list). Only a unit whose empty value is indistinguishable from a real one — the meter — forces host ownership.

@@ -42,4 +40,4 @@ Projection key presence is not a per-session capability signal ([session project

 The context meter becomes a per-session fact instead of a function of mount history. A preset can no longer opt out of token accounting; no shipped preset did, and `minimal` now says it drops auto-compaction rather than the accounting.

-The invariant reaches compositions loading `dsh-invariants`. Production entry points must compose Agents explicitly; installing the registry alone does not bind them.
+Production entry points must compose Agents explicitly; installing the registry alone does not bind them. An unjoined Agent receives no tools, prompt sections, or skills and reports no error.
@@ -18,7 +18,7 @@ Status: implemented

 **meter 属于宿主平面。** `dsh-token-meter` 回到宿主组装，并离开各 preset 的 `isolate` 映射，于是 `compaction-basic` 与 `tool-result-pruner` 在自己的 realm 内部解析到那一份宿主实例。preset 保留 realm 与压缩后端——preset 选择的是它的 agent 是否压缩，而不是它的 token 是否被计。这正是 `tasks` 与 `goals` 已经采用的判据，只是这次适用于一个因**投影**触达面而不该归 preset 所有的 Service：当一个单元的空值与真实值无法区分时，只要它注册进的那张表是进程级的，它就不能是逐组装的。

-**未加入的 Agent 在使用模型时失败。** 不变量 companion 检查 `system-prompt/assemble`，因为未绑定的 Agent 可以合法地稍后通过 `recompose` 绑定。纯 Host 和历史 scope 提示词读取没有 Agent，不属于此检查范围。
+**入口显式让 Agent 加入。** 没有运行时检查会拒绝未加入的 Agent，因为未绑定的 Agent 可以合法地稍后通过 `recompose` 绑定。

 投影 key 是否存在不能代表逐会话能力（[会话投影](../../../../packages/session/session-projection/README.zh.md)）。通过 `cordis_mount` 挂载的临时插件属于组装，而非调用会话（[Cordis 工具](../../../../packages/extensions/tool-cordis/README.zh.md)）。[声明式 preset](2026-09-18-declarative-agent-presets.zh.md) 负责代际保留，在最后一个引用释放后回收退役树。

@@ -26,15 +26,13 @@ Status: implemented

 `apps/cli/tests/web-agent-presets.e2e.ts` 在创建任何 Agent **之前**，于已启动的 Web 组装上读取 `ctx.get('tokenMeter')`——preset 侧的 meter 会待在 `isolate` realm 里，对 `ctx.get` 不可见，因此这次读取是一次所有权断言而不是挂载顺序的巧合——随后断言一个 `minimal` 会话的快照带齐三个单元。

-`packages/preset/agent-preset-registry/tests/invariant.spec.ts` 拒绝未加入的 Agent 组装，并接受已加入的 Agent、Host 读取和历史 scope 读取。
-
 ## 考虑过的替代方案

 **把 meter 留在 preset，改为给投影注册表分层。** 这是更精确的修法，代价也大得多：`snapshot`、`checkpoint` 与主动驱动都需要一次「会话 → 作用域」的解析，而冷读在没有 api-proxy 的 `presenterScopeFor` 时并不具备。相对于一个完全没有 per-preset 状态的 Service，这不成比例，因此改为把通则写在注册表上。

 **对未加入的 agent 否决发布。** 大声胜过静默，注册表也支持这么做——同步的 `agent/created` 监听器抛出会把创建整体回滚。否决的理由是：在名单之外组装 agent 是合法的——`recompose` 写明了它随后绑定的那个裸 agent，而 ACP 桥、SDK server 与 headless bundle 都会创建一个。否决会把能力缺口变成一次故障。

-**让配套也在 `agent/created` 处检查加入情况。** 否决：发布时分不清漏掉的加入与之后才会被绑定的 agent，因此该检查会拒绝一条已写明的路径。提示词组装分得清。
+**在 `agent/created` 处检查加入情况。** 否决：发布时分不清漏掉的加入与之后才会被绑定的 agent，因此该检查会拒绝一条已写明的路径。

 **基于同样的投影理由，把 `plan-mode` 与 `tool-todo` 也搬离 agent 平面。** 否决：两者确实是逐 preset 的能力，且对从不使用它们的会话，其单元算出的就是空值，而客户端本来就按值读取（`plan.active`、空列表）。只有空值与真实值无法区分的单元——meter——才被迫归宿主所有。

@@ -42,4 +40,4 @@ Status: implemented

 context meter 成为逐会话的事实，而不再是挂载历史的函数。代价是 preset 不能再选择不做 token 记账；随附的 preset 没有一个这么做，`minimal` 现在也写明它放弃的是自动压缩而非记账。

-不变量覆盖加载了 `dsh-invariants` 的组装。生产入口必须显式组装 Agent；仅安装注册表不会自动绑定。
+生产入口必须显式组装 Agent；仅安装注册表不会自动绑定。未加入的 Agent 不会获得工具、提示词段落或 skill，也不会报告错误。
@@ -21,5 +21,5 @@
  en: ef7c5f6fa346c1d8
  zh: 439b0d8394015f1e
 /agent-note-credential-records-and-authorization-flows/testing:
-  en: 6c8c01f75e6f916b
-  zh: 7c5c7491f64f2936
+  en: 89f5714501a92b19
+  zh: c92fac2c35532db1
@@ -61,7 +61,7 @@ Two limits are recorded in the package READMEs rather than fixed. An attempt is

 ## Testing

-The seam's suite pins the lifecycle it owns: single-flight refusal and release, withdrawal before the flow starts and during it, a flow that ignores its signal, the commit confirmation, and the settlement event including the `failed` case a caller sees as a thrown error. The invariant companion pins that a settled key is a free key, because a wedged one is otherwise invisible.
+The seam's suite pins the lifecycle it owns: single-flight refusal and release, withdrawal before the flow starts and during it, a flow that ignores its signal, the commit confirmation, and the settlement event including the `failed` case a caller sees as a thrown error.

 `llm-pi-ai` covers the three translations against a real `$DSH_HOME` document — an api-key credential field by field, an OAuth credential verbatim including its refresh half, a foreign plugin's record skipped by scope, and the write refusal without a credentials service — plus every `AuthEvent` and `AuthPrompt` member restated, with `Models.login()` mocked at the collection boundary since a real one opens a browser. Two real-composition tests boot the plugin with and without the authorization seam.

@@ -61,7 +61,7 @@ seam 的边缘与写入路径同一纪律。prompt 被拒是结果而非故障

 ## Testing

-seam 自己的套件钉住它拥有的生命周期：单飞的拒绝与释放、flow 启动前与进行中的撤销、一个忽略自身信号的 flow、提交核实，以及包含"调用方看到的是抛出错误"那种 `failed` 情形的结算事件。invariant companion 钉住"已结算的键就是空闲的键"，因为被卡住的键否则不可见。
+seam 自己的套件钉住它拥有的生命周期：单飞的拒绝与释放、flow 启动前与进行中的撤销、一个忽略自身信号的 flow、提交核实，以及包含"调用方看到的是抛出错误"那种 `failed` 情形的结算事件。

 `llm-pi-ai` 针对一份真实的 `$DSH_HOME` 文档覆盖三处翻译——逐字段的 api-key 凭据、连 refresh 半边一起原样保存的 OAuth 凭据、按 scope 跳过的他插件记录，以及没有凭据服务时的写入拒绝——外加每一个 `AuthEvent` 与 `AuthPrompt` 成员的重述；`Models.login()` 在集合边界处被 mock，因为真实登录会打开浏览器。两个真实组合测试分别在挂载与不挂载授权 seam 的情况下启动插件。

@@ -21,8 +21,8 @@
  en: eb69576e756f4aa1
  zh: 5c1923159da3f7a2
 /agent-note-deepseek-llm-api-request-extensions-for-session-logs-and-plugin-packages/verification:
-  en: 0bda0074b5e11b44
-  zh: 4989c1bb840c78ce
+  en: 9935338a0970d09d
+  zh: a9a36702bc72a9f7
 /agent-note-deepseek-llm-api-request-extensions-for-session-logs-and-plugin-packages/alternatives-considered:
  en: 5faf7699272f99b4
  zh: 7a402e24c80131cf
@@ -50,7 +50,7 @@ The process-lifetime manifest-identity cache remains separate because in-process

 ## Verification

-Registry tests pin duplicate ownership, effect-scoped disposal, detached field values, concurrent and abortable preparation, receiver-preserving acceptance, one acceptance settlement, and failure aggregation. Session tests pin default-on and explicit-off policies, full-first/suffix-later delivery, direct complete event envelopes independent of base-body messages, incremental watermark folding, persisted restart recovery, fork identity fencing, out-of-order acceptance, and late invariant loading. Package-inventory tests pin default-on and explicit-off policies, host and standing-preset discovery, conflicting Loader resolution bases, manifest resolution, lifecycle filtering, and exact name/version ordering. The direct adapter mock proves pre-HTTP preparation failure, cancellation, non-2xx non-acceptance, 2xx acceptance before a later stream failure, and field collision. Keyless replay pins post-2xx extension acceptance, and the TypeScript JSON-RPC plus Python packaged-runtime snapshots project the acceptance event through both SDKs. Real Loader composition pins default package metadata and Session upload plus explicit upload disablement, one real-API request mounts both shipped extensions and proves the official endpoint accepts them, and pi-ai tests retain their unchanged wire requests.
+Registry tests pin duplicate ownership, effect-scoped disposal, detached field values, concurrent and abortable preparation, receiver-preserving acceptance, one acceptance settlement, and failure aggregation. Session tests pin default-on and explicit-off policies, full-first/suffix-later delivery, direct complete event envelopes independent of base-body messages, incremental watermark folding, persisted restart recovery, fork identity fencing, and out-of-order acceptance. Package-inventory tests pin default-on and explicit-off policies, host and standing-preset discovery, conflicting Loader resolution bases, manifest resolution, lifecycle filtering, and exact name/version ordering. The direct adapter mock proves pre-HTTP preparation failure, cancellation, non-2xx non-acceptance, 2xx acceptance before a later stream failure, and field collision. Keyless replay pins post-2xx extension acceptance, and the TypeScript JSON-RPC plus Python packaged-runtime snapshots project the acceptance event through both SDKs. Real Loader composition pins default package metadata and Session upload plus explicit upload disablement, one real-API request mounts both shipped extensions and proves the official endpoint accepts them, and pi-ai tests retain their unchanged wire requests.

 ## Alternatives considered

@@ -50,7 +50,7 @@ Status: implemented

 ## 验证

-注册表测试固定重复所有权、effect 作用域 dispose（资源释放）、分离字段值、并发且可取消的准备、保留接收者的接受操作、单次接受结算与失败聚合。会话测试固定默认开启与显式关闭策略、首次完整／后续后缀交付、与基础正文消息无关的直接完整事件信封、增量水位 fold、持久化重启恢复、fork 身份围栏、乱序接受与 invariant 延迟加载。插件包清单测试固定默认开启与显式关闭策略、宿主与 standing preset 发现、冲突的 Loader 解析基址、manifest 解析、生命周期过滤及确切名称／版本排序。直接适配器 mock 测试证明 HTTP 前准备失败、取消、非 2xx 不接受、2xx 在后续流失败前接受，以及字段冲突。无密钥回放会固定 2xx 后扩展接受，TypeScript JSON-RPC 与 Python 打包运行时快照则通过两套 SDK 投影接受事件。真实 Loader 组合会固定默认包元数据、默认会话上传与显式关闭上传，一个真实 API 请求会挂载两个随附扩展并证明官方端点接受它们；pi-ai 测试保持其协议请求不变。
+注册表测试固定重复所有权、effect 作用域 dispose（资源释放）、分离字段值、并发且可取消的准备、保留接收者的接受操作、单次接受结算与失败聚合。会话测试固定默认开启与显式关闭策略、首次完整／后续后缀交付、与基础正文消息无关的直接完整事件信封、增量水位 fold、持久化重启恢复、fork 身份围栏与乱序接受。插件包清单测试固定默认开启与显式关闭策略、宿主与 standing preset 发现、冲突的 Loader 解析基址、manifest 解析、生命周期过滤及确切名称／版本排序。直接适配器 mock 测试证明 HTTP 前准备失败、取消、非 2xx 不接受、2xx 在后续流失败前接受，以及字段冲突。无密钥回放会固定 2xx 后扩展接受，TypeScript JSON-RPC 与 Python 打包运行时快照则通过两套 SDK 投影接受事件。真实 Loader 组合会固定默认包元数据、默认会话上传与显式关闭上传，一个真实 API 请求会挂载两个随附扩展并证明官方端点接受它们；pi-ai 测试保持其协议请求不变。

 ## 考虑过的替代方案

@@ -24,8 +24,8 @@
  en: e9f140cd22670dfa
  zh: bf85cfe9c12a0345
 /agent-note-package-and-update-the-electron-desktop-application/security-and-release-policy:
-  en: 7fe7dae6bfff28ae
-  zh: 6e8deddf5e669a17
+  en: 97ee608e96fc3602
+  zh: 932b98e7d344cd87
 /agent-note-package-and-update-the-electron-desktop-application/implementation:
  en: 041a6d35ed61b149
  zh: 617c6b90a6f4fa4d
@@ -81,7 +81,7 @@ Test releases require `DOWNLOAD_TEST_RELEASE_ID` from the platform dotenv file.

 Core dsh and the private Desktop Host come only from the signed application resource tree. Plugin installation forwards package specs to pnpm, including local and remote sources, but never accepts raw pnpm commands. pnpm owns dependency resolution and the profile’s `allowBuilds` policy; the Host loads activated bundles.

-Electron release artifacts are signed; macOS artifacts are notarized. Package and upload commands read release settings from the Git-ignored target `.env.windows` or `.env.macos`; subprocesses receive the fields selected by orchestration. The target file exclusively owns release fields so stale shell or system credentials cannot override local selection, and loading does not mutate the parent environment. Packaging validates the mode-specific application ID, update origin, signing identity, and local files before builds, downloads, or release-record cleanup; macOS also requires one complete notarization strategy. The separate `check:package` command runs the same validation without accessing the token or Apple; actual signing and notarization still verify authentication. Configuration loading rejects missing or malformed identifiers and incomplete notarization credentials, while macOS packaging requires signing so certificate discovery cannot silently select another installed identity or emit an unsigned release. Runtime preparation verifies the exact Authority and Team ID plus the timestamp and hardened-runtime flags on every embedded Mach-O file. An after-sign hook performs Apple's deep strict application verification and requires the same leaf Authority and Team ID before artifact creation continues. The fixed-target installer command uses [isolated App copies for parallel notarization](../process/2026-09-09-parallel-macos-notarization.md): the ZIP contains a stapled App, while the signed DMG carries the ticket covering its unstapled inner App. The DMG artifact-completion hook requires the configured identity, a valid ticket, and Gatekeeper acceptance. Both artifact lanes must succeed before the command promotes their outputs and writes the release completion record; directory-only commands still notarize and staple the App. DMG blockmaps are disabled because macOS updates consume the signed ZIP, and stapling would otherwise invalidate an already-generated DMG blockmap.
+Electron release artifacts are signed; macOS artifacts are notarized. Release package and upload commands read release settings from the Git-ignored target `.env.windows` or `.env.macos`; subprocesses receive the fields selected by orchestration. The target file exclusively owns release fields so stale shell or system credentials cannot override local selection, and loading does not mutate the parent environment. Packaging validates the mode-specific application ID, update origin, signing identity, and local files before builds, downloads, or release-record cleanup; macOS also requires one complete notarization strategy. The separate `check:package` command runs the same validation without accessing the token or Apple; actual signing and notarization still verify authentication. Configuration loading rejects missing or malformed identifiers and incomplete notarization credentials, while macOS release packaging requires signing so certificate discovery cannot silently select another installed identity or emit an unsigned release. Runtime preparation verifies the exact Authority and Team ID plus the timestamp and hardened-runtime flags on every embedded Mach-O file. An after-sign hook performs Apple's deep strict application verification and requires the same leaf Authority and Team ID before artifact creation continues. The fixed-target installer command uses [isolated App copies for parallel notarization](../process/2026-09-09-parallel-macos-notarization.md): the ZIP contains a stapled App, while the signed DMG carries the ticket covering its unstapled inner App. The DMG artifact-completion hook requires the configured identity, a valid ticket, and Gatekeeper acceptance. Both artifact lanes must succeed before the command promotes their outputs and writes the release completion record; directory-only commands still notarize and staple the App. DMG blockmaps are disabled because macOS updates consume the signed ZIP, and stapling would otherwise invalidate an already-generated DMG blockmap.

 The [pinned osx-sign patch](../../../../patches/@[email protected]) uses `lstat` in both published module builds, so Framework file and directory aliases do not trigger duplicate signing. The patch remains necessary until the selected upstream release skips those aliases. PAK files are resources sealed by the enclosing bundle; individual signatures add serial timestamp requests without additional resource integrity. Desktop preserves all locale files and skips only their standalone signatures. Executable code retains Developer ID signatures, secure timestamps, and hardened runtime. The [signer traversal regression](../../../../apps/desktop/tests/macos-signing-walk.spec.ts) exercises the installed dependency with real Framework aliases; release qualification still requires strict application verification, notarization, and startup.

@@ -89,7 +89,7 @@ Windows release packaging supplies the public EV leaf certificate named by `DSH_

 Windows package invocations force `ELECTRON_BUILDER_7Z_FILTER=BCJ`. The bundled 7-Zip 24.09 encoder automatically selects ARM64 filters for ARM64 PE files, but the NSIS decoder from `nsis-resources-3.4.1` omits those entries during extraction. A native extraction probe with the actual NSIS plugin loses both `node-pty` ARM64 binaries under automatic filtering and restores both byte-for-byte with BCJ. Keeping a compatible filter preserves dependency contents and runtime integrity instead of removing architecture-specific files or weakening verification.

-Local Windows installation testing uses an explicit `--unsigned` package invocation with the same build and runtime preparation. It strips certificate inputs, isolates artifacts in `unsigned-artifacts`, and omits updater configuration and the release completion record. The regular package command explicitly selects signed mode even when its parent environment requests unsigned mode. This separation permits installation diagnosis without an EV token while preventing local test output from qualifying for release upload.
+Local Windows and macOS installation testing uses an explicit `--unsigned` package invocation with the same build and runtime preparation. It strips certificate inputs, isolates artifacts in `unsigned-artifacts`, and omits updater configuration and the release completion record. macOS local builds ignore dotenv files and inherited release settings, use the standard application ID, and omit mandatory-update policy so local testing needs no deployment configuration. Their App receives a certificate-free ad-hoc signature; their DMG is unsigned and unnotarized. Windows local builds retain their platform configuration requirements. The regular package command explicitly selects signed mode even when its parent environment requests unsigned mode. This separation permits installation diagnosis without release credentials while preventing local test output from qualifying for release upload.

 Windows application replacement follows the [directory-installation reference](../../../../apps/desktop/README.md): extract beside the destination with a command-line tool that returns failure status, then rename complete directories on the same volume. The installer retains the old directory through staging and restores it if promotion fails. Registration, shortcuts, and the signed uninstaller remain owned by electron-builder.

@@ -81,7 +81,7 @@ Electron 更新只使用一个 `electron-updater` 发布流和签名 `electron-b

 核心 dsh 和私有 Desktop Host 只来自签名应用的资源树。插件安装把包规格交给 pnpm，包括本地和远程来源，但不接受原始 pnpm 命令。pnpm 负责依赖解析和 profile 的 `allowBuilds` 策略；Host 加载已启用的 bundle。

-Electron 发布产物必须签名；macOS 产物必须公证。打包与上传命令从 Git 忽略的目标 `.env.windows` 或 `.env.macos` 读取发布配置，子进程通过编排器选择的环境字段接收配置。目标文件是发布字段的唯一来源，避免旧的 shell 或系统凭据覆盖本地选择；配置加载不修改父进程环境。打包在构建、下载或清理发布记录前校验该模式必需的应用 ID、更新地址、签名身份及本地文件，macOS 还要求一套完整公证凭据。单独的 `check:package` 执行同一校验而不访问 Token 或 Apple；凭据真实性仍由实际签名与公证验证。配置加载会拒绝缺失或格式错误的标识符和不完整的公证凭据，macOS 打包还会强制签名，避免证书发现过程静默选择其他已安装身份或生成未签名发布。运行时准备会验证每个内嵌 Mach-O 文件的精确 Authority 与 Team ID，以及时间戳和 hardened-runtime 标记。签名后钩子会执行 Apple 的深度严格应用验证，并要求同一叶证书 Authority 与 Team ID 完全匹配，验证通过后才继续生成产物。固定目标安装包命令使用[隔离的 App 副本并行公证](../process/2026-09-09-parallel-macos-notarization.zh.md)：ZIP 包含已钉票的 App，签名 DMG 则携带覆盖其中未钉票 App 的票据。DMG 的 artifact-completion hook 要求其使用配置的身份、具备有效票据并通过 Gatekeeper。只有两条产物流都成功，命令才会移入其输出并写入发布完成记录；仅生成目录的命令仍会公证 App 并钉票。macOS 更新使用签名 ZIP，因此 DMG 不生成 blockmap；否则钉票会让已经生成的 DMG blockmap 失效。
+Electron 发布产物必须签名；macOS 产物必须公证。发布打包与上传命令从 Git 忽略的目标 `.env.windows` 或 `.env.macos` 读取发布配置，子进程通过编排器选择的环境字段接收配置。目标文件是发布字段的唯一来源，避免旧的 shell 或系统凭据覆盖本地选择；配置加载不修改父进程环境。打包在构建、下载或清理发布记录前校验该模式必需的应用 ID、更新地址、签名身份及本地文件，macOS 还要求一套完整公证凭据。单独的 `check:package` 执行同一校验而不访问 Token 或 Apple；凭据真实性仍由实际签名与公证验证。配置加载会拒绝缺失或格式错误的标识符和不完整的公证凭据，macOS 发布打包还会强制签名，避免证书发现过程静默选择其他已安装身份或生成未签名发布。运行时准备会验证每个内嵌 Mach-O 文件的精确 Authority 与 Team ID，以及时间戳和 hardened-runtime 标记。签名后钩子会执行 Apple 的深度严格应用验证，并要求同一叶证书 Authority 与 Team ID 完全匹配，验证通过后才继续生成产物。固定目标安装包命令使用[隔离的 App 副本并行公证](../process/2026-09-09-parallel-macos-notarization.zh.md)：ZIP 包含已钉票的 App，签名 DMG 则携带覆盖其中未钉票 App 的票据。DMG 的 artifact-completion hook 要求其使用配置的身份、具备有效票据并通过 Gatekeeper。只有两条产物流都成功，命令才会移入其输出并写入发布完成记录；仅生成目录的命令仍会公证 App 并钉票。macOS 更新使用签名 ZIP，因此 DMG 不生成 blockmap；否则钉票会让已经生成的 DMG blockmap 失效。

 [固定版本的 osx-sign 补丁](../../../../patches/@[email protected])在两种已发布模块构建中使用 `lstat`，因此 Framework 的文件和目录别名不会触发重复签名。选定的上游版本能够跳过这些别名前，仍需保留该补丁。PAK 文件由外层 bundle 签名记录完整性；逐个签名会增加串行时间戳请求，但不会增加资源完整性保护。Desktop 保留全部语言文件，只跳过其单独签名。可执行代码仍使用 Developer ID 签名、安全时间戳和 hardened runtime。[签名器遍历回归测试](../../../../apps/desktop/tests/macos-signing-walk.spec.ts)使用真实 Framework 别名执行已安装依赖；发布验收仍要求严格应用验证、公证和启动。

@@ -89,7 +89,7 @@ Windows 发布打包通过 `/f` 向已配置且与 SafeNet 兼容的 SignTool

 Windows 打包调用强制设置 `ELECTRON_BUILDER_7Z_FILTER=BCJ`。内置的 7-Zip 24.09 编码器会为 ARM64 PE 文件自动选择 ARM64 过滤器，但 `nsis-resources-3.4.1` 中的 NSIS 解码器会在解压时遗漏这些条目。使用实际 NSIS 插件的原生解压验证表明，自动过滤会丢失两个 `node-pty` ARM64 二进制文件，而 BCJ 可以逐字节还原二者。使用兼容的过滤器能够保留依赖内容与运行时完整性，无需删除特定架构的文件或削弱校验。

-本地 Windows 安装测试使用显式的 `--unsigned` 打包调用，并执行相同的构建和运行时准备。它清除证书输入，将产物隔离到 `unsigned-artifacts`，并省略更新器配置和发布完成记录。即使父进程环境请求未签名模式，常规打包命令也会显式选择签名模式。这样既能在没有 EV Token 时诊断安装问题，也能防止本地测试产物通过发布上传校验。
+本地 Windows 和 macOS 安装测试使用显式的 `--unsigned` 打包调用，并执行相同的构建和运行时准备。它清除证书输入，将产物隔离到 `unsigned-artifacts`，并省略更新器配置和发布完成记录。macOS 本地构建忽略 dotenv 文件和继承的发布配置，使用标准应用 ID，并省略强制更新策略，使本地测试无需部署配置。其 App 使用无需证书的 ad-hoc 签名，DMG 不签名也不公证。Windows 本地构建保留平台配置要求。即使父进程环境请求未签名模式，常规打包命令也会显式选择签名模式。这样既能在没有发布凭据时诊断安装问题，也能防止本地测试产物通过发布上传校验。

 Windows 应用替换遵循[目录安装参考](../../../../apps/desktop/README.zh.md)：使用能返回失败状态的命令行工具解压到目标旁边，再在同卷内改名替换完整目录。安装器在暂存期间保留旧目录，正式替换失败时恢复旧目录。注册信息、快捷方式和签名卸载器仍由 electron-builder 持有。

@@ -9,11 +9,11 @@
  en: d2df1eb3602af45d
  zh: fd162b1c214f1494
 /agent-note-retain-ignorable-session-events-for-external-plugins/decision:
-  en: a4162e65cf6768f3
-  zh: bb700d9630642e7e
+  en: c78e92c0cc5a7eb2
+  zh: 62b29ccc5cd142f2
 /agent-note-retain-ignorable-session-events-for-external-plugins/alternatives-considered:
-  en: 30ec097e3ba4e951
-  zh: 3e90fc035d04b09b
+  en: c91cdee1dda42176
+  zh: 870dfbda591abb76
 /agent-note-retain-ignorable-session-events-for-external-plugins/consequences:
-  en: 5f65bfb81f172d49
-  zh: 069d41d6bda9f8af
+  en: b14df3e7f7489748
+  zh: ac227743cf5c11f7
@@ -16,6 +16,10 @@ The canonical `SessionEvent` envelope retains `ignorable?: true`, and every repr

 The field is removable only after a replacement supports the current third-party plugin across event production, persistence, reload, and transport, with an explicit cutover for sessions already containing the marker. The [session log versioning decision](2026-08-10-session-log-version-mechanism.md) continues to own the default-required safety rule and format-version policy.

+`appendPluginRecord()` in `@deepseek-ai/dsh-session` is the one first-party writer of the marker. It appends ignorable records whose type is in the `plugin:` namespace, which the V3-to-V4 edge already assigns to unknown ignorable V3 events, and only production source under `packages/experimental/` may call it; the `verify-plugin-record-callers` gate enforces that, and the persistence catalog generator rejects a `SessionEventMap` member in the namespace. Experimental packages keep state there that their owners can lose: a format migration retains records on a best-effort basis, so a release package declares its events instead.
+
+Experimental packages declare record names and payload types in the separate `PluginRecordMap`. The map types writes and supplies the dedicated [experimental persistence catalog](../../../../docs/experimental-persistence-catalog.md), making plugin-owned persistence discoverable from current source without expanding its payload schemas or recording released type history. It does not add names to `KNOWN_SESSION_EVENT_TYPES` or change stored-event admission. The reader returns unknown payloads for owner validation, including records whose declarations have changed or disappeared.
+
 Historical format migration is deliberately stricter in the alpha implementation. The v0-to-v1 edge refuses every unknown v0 type, including an ignorable one, because an opaque payload may contain references that a format edge cannot validate. The [alpha historical-event decision](2026-08-31-alpha-historical-unknown-event-refusal.md) owns that bounded exception; equal-version append and reload continue to follow this note.

 ## Alternatives considered
@@ -26,8 +30,16 @@ Historical format migration is deliberately stricter in the alpha implementation

 **Treat every repository-external event as ignorable.** Rejected because a reader cannot infer that an unknown durable event is informational. An external event may change later reconstruction or plugin-owned state.

+**Declare a `SessionEventMap` member for each experimental package's state.** Rejected because each member is required-on-read and enters the released-schema inventory and type history: a build without the experimental package refuses the Session, and removing the package leaves a released type behind.
+
+**Keep no catalog of plugin records.** Rejected because maintainers need to find in-repository persistence writers. The dedicated experimental catalog provides that inventory from current-source declarations while their payloads retain best-effort compatibility; a full schema history would impose the released-event obligations that these records deliberately avoid.
+
+**Let any package call the record writer.** Rejected because records survive a format migration only on a best-effort basis, and a release package must not keep state that an upgrade can drop.
+
+**Restrict the writer with a runtime capability.** Not adopted because the writer runs in its caller's process, where a runtime check cannot tell experimental code from release code; the repository gate checks every reference instead.
+
 **Register mounted plugin event names as known.** Not adopted as the removal mechanism because event-name registration alone does not classify whether absence is safe, and acceptance would depend on the reader's current composition rather than the stored record.

 ## Consequences

-Third-party informational events can remain reloadable when their stored records carry the explicit marker, while unknown required events still fail loudly. The field remains part of the public event envelope, JSONL representation, transport types, generated references, and their tests until a replacement satisfies the cutover condition.
+Third-party informational events can remain reloadable when their stored records carry the explicit marker, while unknown required events still fail loudly. The field remains part of the public event envelope, JSONL representation, transport types, generated references, and their tests until a replacement satisfies the cutover condition, which now also covers plugin records written by experimental packages.
@@ -16,6 +16,10 @@ Status: implemented

 只有替代机制在事件生产、持久化、重新加载与传输中都支持当前第三方插件，并为已包含该标记的会话提供显式切换方案后，才能删除此字段。[Session log 版本决策](2026-08-10-session-log-version-mechanism.zh.md)继续定义默认读取必需的安全规则与格式版本策略。

+`@deepseek-ai/dsh-session` 中的 `appendPluginRecord()` 是该标记唯一的第一方写入方。它追加类型位于 `plugin:` 命名空间的 ignorable 记录（V3-to-V4 迁移边已把未知的 ignorable V3 事件放入该命名空间），且只有 `packages/experimental/` 下的生产源码可以调用它；`verify-plugin-record-callers` 门禁强制这一点，持久化目录生成器也拒绝该命名空间中的 `SessionEventMap` 成员。实验性包在这里保存其所有者可以丢失的状态：格式迁移以尽力而为的方式保留记录，因此正式发布的包改为声明自己的事件。
+
+实验性包在独立的 `PluginRecordMap` 中声明记录名称与 payload 类型。该映射约束写入类型，并生成独立的[实验性持久化目录](../../../../docs/experimental-persistence-catalog.zh.md)，让维护者能够从当前源码找到插件自有的持久化数据，而无须展开其 payload schema 或记录已发布类型历史。它不向 `KNOWN_SESSION_EVENT_TYPES` 添加名称，也不改变已存事件的准入。读取方返回未知类型的 payload，由所属包校验，其中也包括声明已变更或消失的记录。
+
 Alpha 实现中的历史格式迁移有意更严格。v0-to-v1 迁移边会拒绝每个未知 v0 类型，包括 ignorable 类型，因为不透明 payload 可能包含格式迁移边无法校验的引用。[Alpha 历史事件决策](2026-08-31-alpha-historical-unknown-event-refusal.zh.md)定义该有限例外；同版本 append 与 reload 继续遵循本记录。

 ## 曾考虑的替代方案
@@ -26,8 +30,16 @@ Alpha 实现中的历史格式迁移有意更严格。v0-to-v1 迁移边会拒

 **把所有仓库外事件都视为可忽略。** 不予采用，因为读取器无法推断未知持久事件是否属于信息性事件。外部事件可能改变后续重建或插件自有状态。

+**为每个实验性包的状态声明 `SessionEventMap` 成员。** 不予采用，因为每个成员都是读取必需的，并会进入已发布 schema 清单及类型历史：没有该实验性包的构建会拒绝该会话，移除该包后还会留下一个已发布的类型。
+
+**不维护插件记录目录。** 不予采用，因为维护者需要找到仓库内的持久化写入方。独立的实验性目录根据当前源码声明提供这份清单，而 payload 仍然只有尽力而为的兼容性；完整的 schema 历史会施加这些记录刻意不承担的已发布事件义务。
+
+**允许任何包调用记录写入方。** 不予采用，因为记录只能以尽力而为的方式经受格式迁移，而正式发布的包不得保存升级可能丢弃的状态。
+
+**用运行时能力限制写入方。** 不予采用，因为写入方运行在调用方的进程中，运行时检查无法区分实验性代码与正式发布的代码；仓库门禁改为检查每一处引用。
+
 **把已挂载插件的事件名称注册为已知。** 不作为删除机制采用，因为只注册事件名称无法判定缺失该事件是否安全，而且接受结果会依赖读取器的当前组合，而不是已存记录。

 ## 影响

-第三方信息性事件的已存记录带有显式标记时可以继续重新加载，未知必需事件则仍会明确失败。在替代机制满足切换条件前，该字段继续属于公开事件信封、JSONL 表示、传输类型、生成引用及其测试。
+第三方信息性事件的已存记录带有显式标记时可以继续重新加载，未知必需事件则仍会明确失败。在替代机制满足切换条件前，该字段继续属于公开事件信封、JSONL 表示、传输类型、生成引用及其测试；该切换条件现在也涵盖实验性包写入的插件记录。
@@ -6,11 +6,11 @@
  en: f5e76516df025fc5
  zh: 462fe05b46e6c1ea
 /agent-note-explicit-agent-identity-at-runtime-boundaries/problem:
-  en: 0b737a098e4e19ce
-  zh: 97b4254c4533114f
+  en: 98b49b900b8d2f84
+  zh: 557faac2976592be
 /agent-note-explicit-agent-identity-at-runtime-boundaries/decision:
-  en: 1cb0015482bba539
-  zh: 7f4b2da7184f6f64
+  en: 1c628cf9c743c639
+  zh: d969b2475fe4a155
 /agent-note-explicit-agent-identity-at-runtime-boundaries/verification:
  en: 85130faaa171036b
  zh: 06e5e9fab32dbfb4
@@ -10,7 +10,7 @@ An Agent's Cordis Context owns registrations and their cleanup. Agent identity i

 The reverse association also required compensating mechanisms after type erasure. Host Remote forwarding inspected a routed subject for its Context, creation inferred runtime parentage from the caller Context, and adapters maintained reverse identity scans. These mechanisms duplicated identity already present in typed requests and obscured which caller owned an Agent at runtime.

-Without an explicit owner, `SubagentContinuationManager` creates and resumes children through its private plugin Context, so Context-based inference classifies every continuable child as a runtime root even though the manager holds its exact parent. Root-only consumers could then attach scheduling tools, grant direct-human goal authority, or route user questions as if the child were top-level.
+Without an explicit owner, `SubagentManager` creates and resumes children through its private plugin Context, so Context-based inference classifies every continuable child as a runtime root even though the manager holds its exact parent. Root-only consumers could then attach scheduling tools, grant direct-human goal authority, or route user questions as if the child were top-level.

 ## Decision

@@ -18,7 +18,7 @@ Runtime interfaces carry Agent identity at the point that owns it. `AgentSetup`

 Scope-aware registries continue to use the opaque scope key only for registration membership. Tool-subagent does not classify that key or resolve an Agent from Context. A direct `AgentSetup` passes the unpublished Session explicitly and installs through the supplied Context before publication. For a settings-backed standing preset, the event payload supplies the Agent, its Session supplies the policy target, and its Context owns the registrations.

-`SubagentContinuationManager` puts the exact parent in both fresh-creation and cold-resume options. A live continuable child is therefore excluded from `AgentRegistry.roots()` and satisfies `isOwnedBy(child.id, parent)`. Durable `parentSession` metadata does not substitute for this relation: a fork or resumed Session may be a runtime root when no live Agent owns it.
+`SubagentManager` puts the exact parent in both fresh-creation and cold-resume options. A live continuable child is therefore excluded from `AgentRegistry.roots()` and satisfies `isOwnedBy(child.id, parent)`. Durable `parentSession` metadata does not substitute for this relation: a fork or resumed Session may be a runtime root when no live Agent owns it.

 The [scope reference](../../../../packages/core/scope/README.md) and [Agent loop reference](../../../../packages/core/agent-loop/README.md) document registration and lifecycle behavior. The [initiator-scope decision](2026-07-15-agent-initiator-scope.md) owns private-chain rationale; explicit runtime ownership does not change causal initiation or registration lifetime.

@@ -10,7 +10,7 @@ Agent 的 Cordis Context 拥有注册及其清理。Agent 身份则为某项操

 类型信息被擦除后，这项反向关联还需要补偿机制。Host Remote 转发会从已路由主体检查其 Context，创建流程会从调用方 Context 推断运行时父级，适配器则维护反向身份扫描。这些机制重复类型化请求中已有的身份，也掩盖了哪个调用方在运行时拥有 Agent。

-若没有显式所属方，`SubagentContinuationManager` 会通过私有插件 Context 创建和恢复子级，因此基于 Context 的推断会把每个可续跑子级归类为 runtime root，尽管管理器持有其确切父级。仅限根级的消费方随后可能附加调度工具、授予直接人类输入对应的 Goal 权限，或像处理顶层 Agent 一样路由用户问题。
+若没有显式所属方，`SubagentManager` 会通过私有插件 Context 创建和恢复子级，因此基于 Context 的推断会把每个可续跑子级归类为 runtime root，尽管管理器持有其确切父级。仅限根级的消费方随后可能附加调度工具、授予直接人类输入对应的 Goal 权限，或像处理顶层 Agent 一样路由用户问题。

 ## 决策

@@ -18,7 +18,7 @@ Agent 的 Cordis Context 拥有注册及其清理。Agent 身份则为某项操

 感知作用域的注册表继续仅使用不透明作用域键判断注册成员关系。tool-subagent 不会分类该键，也不会从 Context 解析 Agent。直接 `AgentSetup` 显式传入尚未发布的 Session，并在发布前通过所给 Context 完成安装。对于由设置控制的常驻 preset，事件 payload 提供 Agent，其 Session 提供策略目标，其 Context 拥有注册项。

-`SubagentContinuationManager` 会把确切父级放进全新创建与冷恢复的 options。因此，存活的可续跑子级不会出现在 `AgentRegistry.roots()` 中，并且满足 `isOwnedBy(child.id, parent)`。持久化 `parentSession` 元数据不能代替这项关系：没有存活 Agent 拥有 fork 或已恢复会话时，它仍可成为 runtime root。
+`SubagentManager` 会把确切父级放进全新创建与冷恢复的 options。因此，存活的可续跑子级不会出现在 `AgentRegistry.roots()` 中，并且满足 `isOwnedBy(child.id, parent)`。持久化 `parentSession` 元数据不能代替这项关系：没有存活 Agent 拥有 fork 或已恢复会话时，它仍可成为 runtime root。

 [作用域参考](../../../../packages/core/scope/README.zh.md)与 [Agent loop 参考](../../../../packages/core/agent-loop/README.zh.md)说明注册和生命周期行为。[发起方作用域决策](2026-07-15-agent-initiator-scope.zh.md)负责私有调用链理由；显式运行时归属不改变因果发起关系或注册生命周期。

@@ -9,8 +9,8 @@
  en: 5a991fec31578cea
  zh: 13b75aa36eb22907
 /agent-note-parent-owned-subagent-catalog-events/decision:
-  en: 198354f20b5d0a42
-  zh: 7a6b4392117a60b5
+  en: 4319c502038ab34d
+  zh: b11825ff9d744822
 /agent-note-parent-owned-subagent-catalog-events/alternatives-considered:
  en: 7a3d4b9f69c243d8
  zh: 82b03d16ccc94dd2
@@ -12,15 +12,17 @@ The child descriptor remains necessary for recovery and composition, but it cann

 ## Decision

-The parent Session's required `subagent/catalog` events are the persistent authority for direct-child discovery. Each event is one successful creation fact containing `childId`, `childCreatedAt`, mode, and the mode-discriminated label. Remote one-shot runs without a local Session remain outside this catalog. Invalid own facts, including unsupported payload versions, reject projection restoration because silently dropping a required fact would return an incomplete catalog.
+The shared activation entry point, external execution ownership, and caller-versus-parent result delivery are governed by [Unified subagent activations](../simplification/2026-09-17-unified-subagent-activations.md). This record retains the independent rationale described below.

-Creation publishes only successful facts. A one-shot run appends the catalog event after its provider returns a local child and before the run reaches its caller. A continuable run admits the initial prompt, appends the catalog event, then returns the child id. If admission or catalog append fails, creation fails and releases the activation; there is no compensating catalog event or rollback protocol.
+The parent Session's required `subagent/catalog` events are the persistent authority for direct-child discovery. Every local child enters the catalog independently of its result recipient; external children enter only with parent delivery. Workflow membership records describe execution progress and do not replace local Session discovery. Each event contains `childId`, `childCreatedAt`, mode, and the mode-discriminated label. Local children use `continuable`; external executions use `external` and cannot be opened as local Sessions. Historical `one-shot` and `unknown` entries remain readable. Invalid own facts, including unsupported payload versions, reject projection restoration because silently dropping a required fact would return an incomplete catalog.
+
+Creation publishes only successful facts. A local activation admits the initial prompt before appending its catalog event. An external activation appends its event after provider startup and before returning the receipt. Failed admission or publication releases the unpublished execution; there is no compensating catalog event or rollback protocol.

 The child header and `subagent/descriptor` remain authoritative for recovery and composition. An Activation and the exact parent relationship remain authoritative for authorization and delivery. Mode and label are snapshotted once and the same detached values reach the parent catalog fact and child descriptor.

 The registered `subagentCatalog` projection materializes the parent facts. It delegates storage, append, iteration, and checkpoint validation to [`dsh-chunked-list`](../../../../packages/util/chunked-list/README.md), which stores facts in a persistent stack of 64-entry chunks, so an append copies at most the head chunk in bounded O(1) work. Materialization visits chunks from oldest to newest and preserves parent catalog event order in O(D) time for D facts. Concurrent creation is ordered by successful catalog append, independent of child timestamps and ids. A projection checkpoint clones the state once in O(D); projection-cache writes remain asynchronous and use the existing mandatory creation, turn-end, and disposal points.

-The utility owns chunk layout and its shared capacity constant; the catalog owns event validation, fork filtering, and row conversion. Catalog projection state version 2 stores generic chunk values, so the projection registry rebuilds incompatible caches from Session events. Session event payloads and public catalog rows retain their formats.
+The utility owns chunk layout and its shared capacity constant; the catalog owns event validation, fork filtering, and row conversion. Catalog projection state version 6 accepts external membership, so the projection registry rebuilds incompatible caches from Session events. Payload v0 and v1 remain unchanged; v2 records external executions.

 Fork isolation uses the exact `Session.inheritedEventCount` supplied to projection initialization. The fold ignores `subagent/catalog` events below that offset. The state stores the inherited offset but not each event seq because acceptance is decided during folding.

@@ -12,15 +12,17 @@ child descriptor 对恢复与 composition 仍然必要，但它不能作为 disc

 ## 决策

-parent Session 的 required `subagent/catalog` 事件是直接 child discovery 的持久化权威。每个事件都是一条成功创建事实，包含 `childId`、`childCreatedAt`、mode 与按 mode 区分的 label。没有本地 Session 的远程 one-shot run 不进入该目录。无效的自身 fact（包括不支持的 payload 版本）会使 projection 恢复失败，因为静默丢弃 required fact 会返回不完整的目录。
+共享 activation 入口、外部执行所有权，以及调用方与父级之间的结果投递选择由[统一 subagent activation](../simplification/2026-09-17-unified-subagent-activations.zh.md) 决策拥有。本记录保留下述独立理由。

-创建只发布成功事实。one-shot run 在 provider 返回本地 child 后、run 到达调用方前追加目录事件。continuable run 先准入初始 prompt，再追加目录事件，最后返回 child id。准入或目录追加失败时，创建失败并释放 activation；不存在补偿目录事件或 rollback 协议。
+父级 Session 的必读 `subagent/catalog` 事件是发现直接子级的持久化权威。每个本地子级都会进入目录，与结果接收方无关；外部子级仅在 parent 投递时进入目录。工作流成员记录描述执行进度，不替代本地 Session 发现。每个事件包含 `childId`、`childCreatedAt`、mode 与按 mode 区分的 label。本地子级使用 `continuable`；外部执行使用 `external`，不能作为本地 Session 打开。历史 `one-shot` 与 `unknown` 条目仍可读取。无效的自身事实（包括不支持的载荷版本）会使投影恢复失败，因为静默丢弃必读事实将返回不完整的 catalog。
+
+创建只发布成功事实。本地 activation 先接纳初始提示词，再追加 catalog 事件。外部 activation 在提供方启动后、返回回执前追加事件。准入或发布失败会释放未发布的执行；不存在补偿 catalog 事件或回滚协议。

 child header 与 `subagent/descriptor` 继续拥有恢复与 composition 权威。Activation 与精确 parent 关系继续拥有授权与投递权威。mode 与 label 只快照一次，同一份分离值写入 parent catalog fact 与 child descriptor。

 注册的 `subagentCatalog` projection 物化 parent fact。它将存储、追加、迭代和检查点校验交给 [`dsh-chunked-list`](../../../../packages/util/chunked-list/README.zh.md)，后者以每块 64 项的持久 stack 保存事实，因此 append 最多复制 head chunk，以有界 O(1) 工作完成。materialization 从旧到新访问 chunk，对 D 条事实以 O(D) 时间保留父目录事件顺序。并发创建按目录成功追加的顺序排列，与 child 时间戳和 id 无关。projection checkpoint 以 O(D) 克隆 state；projection-cache 继续异步写入，并使用既有创建、turn-end 与 disposal 强制点。

-工具库拥有分块布局及其共享容量常量；目录拥有事件校验、fork 过滤和目录行转换。目录 projection state 版本 2 保存通用块值，因此 projection registry 从 Session 事件重建不兼容的缓存。Session 事件载荷和公开目录行保持各自格式。
+工具库拥有 chunk 布局与共享容量常量；catalog 拥有事件校验、fork 过滤和行转换。catalog 投影状态版本 6 接受外部成员，因此投影注册表会从 Session 事件重建不兼容缓存。载荷 v0 与 v1 保持不变；v2 记录外部执行。

 fork 隔离使用 projection 初始化时提供的精确 `Session.inheritedEventCount`。fold 忽略该 offset 之前的 `subagent/catalog` 事件。state 保存 inherited offset，但不保存每条 event seq，因为接受判定已在 fold 时完成。

@@ -18,8 +18,8 @@
  en: a217a08932938062
  zh: 4924d99d55d9c973
 /agent-note-the-system-prompt-is-surface-node-0/decision/ownership-in-the-loop:
-  en: 88945024c2efe271
-  zh: 05dca84a4ce5e614
+  en: a7d0d3a61d2fef04
+  zh: 29a3d5dbed2f987a
 /agent-note-the-system-prompt-is-surface-node-0/decision/consumers:
  en: 39f9f4acffcccdc6
  zh: 36b23a57e7d28950
@@ -33,5 +33,5 @@
  en: bccea8236b4c32b3
  zh: a1150784718a6639
 /agent-note-the-system-prompt-is-surface-node-0/testing:
-  en: f5b21c4863cd92bd
-  zh: 7d1efed827d55161
+  en: 9a5a241ae3d0c676
+  zh: 8f3e83cc54604bcc
@@ -36,7 +36,7 @@ When the initial rendered prompt is empty, the loop reserves an empty system hea

 `dsh-agent-loop` owns `SystemPromptProjection` beside `RuntimeContextProjection` in `packages/core/agent-loop/src/runtime-context.ts`. It reads the surviving `system/message` nodes from the current surface on every projection, so a compaction or replacement that ran earlier in the same step is already reflected. `project(rendered, { inHistory, startsSeries })` returns `{ message, intent }` — `intent` is `{ surfaceOp: 'append' }` when no system node survives or when the [in-history rule](../feature/2026-09-02-in-history-system-prompt-replacement.md) applies, otherwise a replacement of exactly the latest surviving system node — or `undefined` when the latest node already holds the rendered text.

-In `packages/core/agent-loop/src/agent.ts`, `preStep` renders the prompt with `renderPrompt(assembly)` and projects it after the `agent/pre-step` waterfall, so a compaction provider's replacement inside that waterfall is visible to the decision; `turn()` commits the `system/message` immediately after `step/start` and before the step's `user/message` events, so log order is wire order. `buildRequest` sets no `system` on the request: the request is `header.config`, `session.deriveMessages()` (system message first), and `header.tools`. The loop step order is: claim inbox → `systemPrompt.assemble()` → project runtime context → `agent/pre-step` waterfall → project system prompt → `step/start` → commit `system/message` (when changed) → commit `user/message`s → `agent/request` waterfall → `request/header` → `request/context` → stream. The `dsh-agent-loop/invariant` companion (`packages/core/agent-loop/src/invariant.ts`) asserts that a loop-built request has `system === undefined` and `messages` equal to `deriveMessages()`.
+In `packages/core/agent-loop/src/agent.ts`, `preStep` renders the prompt with `renderPrompt(assembly)` and projects it after the `agent/pre-step` waterfall, so a compaction provider's replacement inside that waterfall is visible to the decision; `turn()` commits the `system/message` immediately after `step/start` and before the step's `user/message` events, so log order is wire order. `buildRequest` sets no `system` on the request: the request is `header.config`, `session.deriveMessages()` (system message first), and `header.tools`. The loop step order is: claim inbox → `systemPrompt.assemble()` → project runtime context → `agent/pre-step` waterfall → project system prompt → `step/start` → commit `system/message` (when changed) → commit `user/message`s → `agent/request` waterfall → `request/header` → `request/context` → stream.

 `dsh-token-meter` anchors usage to the priced surface immediately before the successful `assistant/message`, not to `step/start`. The loop admits the system prompt and user messages after step start, and retry recovery can replace nodes before rebuilding the request. Capturing that current surface includes every admitted input once; the embedded provider output remains separately priced so durable assistant rewrites retain their signed delta. The open step stores only turn and step for lifecycle validation, not a second node snapshot.

@@ -90,6 +90,5 @@ The [canonical-envelope specification](../../../../packages/session/session-form
 - `packages/core/session/tests/surface.spec.ts` (`system/message surface node` block) pins the leading system-role projection, the empty-content `null` projection, `assertSystemHeadRewrite`'s acceptance and rejection paths, the unprotected later system nodes, and the rejection of a seeded `system/message` with a non-system role or non-plugin source.
 - `packages/core/agent-loop/tests/system-prompt-projection.spec.ts` pins the append on first render (including empty), the later non-empty prompt at the derived head in replacement mode, the no-op on an unchanged prompt, the replacement of the latest surviving node on change, the tail append after a replacement shadowed a non-head system node, and the in-history append and re-baseline rules.
 - `packages/core/agent-loop/tests/request-reconstruction.spec.ts` (`a system-prompt change replaces surface node 0 and starts a new series under the same header`) pins the `series` header that follows a prompt replacement.
- `packages/core/agent-loop/tests/invariant.spec.ts` pins the companion's rejection of a loop request carrying a `system` field and its `messages` equality check against the boundary derivation.
 - `packages/llm/llm-deepseek/tests/serialize.spec.ts` (`serializes a leading system message byte-for-byte like the same prompt passed as options.system`) pins wire identity. `packages/llm/llm-pi-ai/tests/context.spec.ts` compares both system sources on text and image paths. `packages/compaction/compaction-basic/tests/compaction-basic.spec.ts` pins the derived prefix, routed tools, absent separate `system` option, and protected non-empty or empty head through the region transaction and default summarizer.
 - The recorded snapshots under `snapshots/` pin the model-visible wire request of every shipped profile; a recorded session that renders a prompt carries the `system/message` event at surface node 0 in its `session.jsonl`, and a session with a mid-session prompt change carries the replacement of node 0 or, on an in-history route, the appended node.
@@ -36,7 +36,7 @@ Status: implemented

 `dsh-agent-loop` 在 `packages/core/agent-loop/src/runtime-context.ts` 中与 `RuntimeContextProjection` 并列拥有 `SystemPromptProjection`。它在每次投影时从当前 surface 读取存活的 `system/message` 节点，因此同一步骤中更早运行的压缩或替换已经反映在内。`project(rendered, { inHistory, startsSeries })` 返回 `{ message, intent }`——没有系统节点存活或[历史内规则](../feature/2026-09-02-in-history-system-prompt-replacement.zh.md)适用时 `intent` 为 `{ surfaceOp: 'append' }`，否则是对最新存活系统节点的精确替换——最新节点已持有渲染文本时返回 `undefined`。

-在 `packages/core/agent-loop/src/agent.ts` 中，`preStep` 用 `renderPrompt(assembly)` 渲染提示词，并在 `agent/pre-step` waterfall 之后投影它，因此压缩提供者在该 waterfall 内做出的替换对决定可见；`turn()` 紧接在 `step/start` 之后、该步骤的 `user/message` 事件之前提交 `system/message`，因此日志顺序即协议顺序。`buildRequest` 不在请求上设置 `system`：请求由 `header.config`、`session.deriveMessages()`（系统消息在先）和 `header.tools` 构成。循环步骤顺序为：领取收件箱 → `systemPrompt.assemble()` → 投影运行时上下文 → `agent/pre-step` waterfall → 投影系统提示词 → `step/start` → 提交 `system/message`（有变化时） → 提交各条 `user/message` → `agent/request` waterfall → `request/header` → `request/context` → 流式请求。`dsh-agent-loop/invariant` 伴随组件（`packages/core/agent-loop/src/invariant.ts`）断言循环构建的请求满足 `system === undefined` 且 `messages` 等于 `deriveMessages()`。
+在 `packages/core/agent-loop/src/agent.ts` 中，`preStep` 用 `renderPrompt(assembly)` 渲染提示词，并在 `agent/pre-step` waterfall 之后投影它，因此压缩提供者在该 waterfall 内做出的替换对决定可见；`turn()` 紧接在 `step/start` 之后、该步骤的 `user/message` 事件之前提交 `system/message`，因此日志顺序即协议顺序。`buildRequest` 不在请求上设置 `system`：请求由 `header.config`、`session.deriveMessages()`（系统消息在先）和 `header.tools` 构成。循环步骤顺序为：领取收件箱 → `systemPrompt.assemble()` → 投影运行时上下文 → `agent/pre-step` waterfall → 投影系统提示词 → `step/start` → 提交 `system/message`（有变化时） → 提交各条 `user/message` → `agent/request` waterfall → `request/header` → `request/context` → 流式请求。

 `dsh-token-meter` 把用量锚定到成功的 `assistant/message` 之前的已计价 surface，而不是 `step/start`。循环在步骤开始之后接纳系统提示词与用户消息，重试恢复还可能在重建请求之前替换节点。捕获当前 surface 会让每个已接纳输入恰好计入一次；内嵌的提供方输出仍单独计价，因此持久 assistant 改写保留其带符号增量。开放步骤只保存 turn 与 step 以验证生命周期，不保存第二份节点快照。

@@ -90,6 +90,5 @@ Status: implemented
 - `packages/core/session/tests/surface.spec.ts`（`system/message surface node` 块）钉住开头 system 角色的投影、空内容的 `null` 投影、`assertSystemHeadRewrite` 的接受与拒绝路径、更后位置系统节点不受保护，以及对 seed 中非 system 角色或非插件 source 的 `system/message` 的拒绝。
 - `packages/core/agent-loop/tests/system-prompt-projection.spec.ts` 钉住首次渲染时的追加（包括空提示词）、替换模式下后来非空提示词位于派生历史头部、提示词未变时的无操作、变更时对最新存活节点的替换、替换遮蔽了非头部系统节点之后的尾部追加，以及历史内追加与重新基线规则。
 - `packages/core/agent-loop/tests/request-reconstruction.spec.ts`（`a system-prompt change replaces surface node 0 and starts a new series under the same header`）钉住提示词替换之后跟随的 `series` header。
- `packages/core/agent-loop/tests/invariant.spec.ts` 钉住伴随组件对携带 `system` 字段的循环请求的拒绝，以及其 `messages` 与边界派生结果的相等性检查。
 - `packages/llm/llm-deepseek/tests/serialize.spec.ts`（`serializes a leading system message byte-for-byte like the same prompt passed as options.system`）钉住协议一致性。 `packages/llm/llm-pi-ai/tests/context.spec.ts` 在文本与图片路径上比较两种系统提示词来源。`packages/compaction/compaction-basic/tests/compaction-basic.spec.ts` 通过区域事务与默认摘要器钉住派生前缀、已路由工具、不携带单独 `system` 选项，以及非空或空头节点的保护。
 - `snapshots/` 下的录制快照钉住每个随发 profile 的模型可见协议请求；渲染了提示词的录制会话在其 `session.jsonl` 中于 surface 第 0 号节点携带 `system/message` 事件，会话中途发生提示词变更的会话则携带对第 0 号节点的替换，或在历史内路由上携带追加的节点。
@@ -15,5 +15,5 @@
  en: 09be2a1cf1d52fd5
  zh: 0bf0e18c73542012
 /agent-note-one-output-ring-one-projection-one-event-stream-for-background-jobs/consequences:
-  en: f95bac1d69346194
-  zh: 4e47dfa9d95ac3dd
+  en: 464eb843a71eb04e
+  zh: 783062f5b288b1b4
@@ -34,4 +34,4 @@ The job seam had grown by accretion. Producers declared their output twice — a

 The model-visible text is unchanged: status lines, tool descriptions and schemas, and notice wording are byte-identical, and the only new model-visible fact is the kill reason a `killed` status line now carries. A producer that needs to stream output picks pull sources or `append`; it never formats a consuming delta. The Web client renders every live job as expandable, so a job that never writes shows an empty running panel instead of a static row. `JobKindMap` merges are host-side, so a browser program types `JobView.kind` as the kinds it knows and treats the rest as opaque strings, which is all the roster does with it.

-Review follow-ups after the master merge tightened four of these edges. A job's first event is always `registered`: the announcement precedes the pump, whose first drain runs synchronously and may announce output. A settled ring keeps every byte the model cursor has not consumed until the first terminal model read, so a job that finishes before its first `job_output` loses nothing the live cap retained. `dsh-tool-jobs` holds one claim per wait call with a `live` flag that the caller's abort clears synchronously from the abort event, so a settlement announced before the registry's rejection reaches the tool still delivers its notice, and a timed-out wait drops only its own claim while a concurrent wait keeps the settlement covered. The browser records an observation failure that precedes the anchor as an errored view, so the panel shows the notice instead of staying blank. The `@deepseek-ai/dsh-jobs/invariant` companion checks the announced event protocol per job (registered first, one settlement, removal last) and each announced projection against the registry's own read, which is the cross-observation the [companion rule](../../../../packages/AGENTS.md) requires; the earlier single-view field checks are gone. The spill file a pull source keeps is job metadata (`JobView.output.spillPaths`, reported by every pump read and withdrawn once a read stops naming it), not per-chunk metadata, and the model's read renders the shell tools' dropped-output notice for a producer-side gap as well as for ring eviction, naming those files even after the gap chunk itself was evicted — the `before this read` variant this change had introduced is gone. An observation generation that sees its job removed mid-stream (the owner's teardown) closes with the removed job's terminal projection instead of a failed read. A rejected background spawn produces no process output, so the shell providers now serve the `spawn failed: …` note as the whole observed stderr stream (the consuming read still folds it in once), and `ShellProcess.observed` with both readers is required: the model's first `job_output` after such a failure reads exactly what master's consuming read rendered.
+Review follow-ups after the master merge tightened four of these edges. A job's first event is always `registered`: the announcement precedes the pump, whose first drain runs synchronously and may announce output. A settled ring keeps every byte the model cursor has not consumed until the first terminal model read, so a job that finishes before its first `job_output` loses nothing the live cap retained. `dsh-tool-jobs` holds one claim per wait call with a `live` flag that the caller's abort clears synchronously from the abort event, so a settlement announced before the registry's rejection reaches the tool still delivers its notice, and a timed-out wait drops only its own claim while a concurrent wait keeps the settlement covered. The browser records an observation failure that precedes the anchor as an errored view, so the panel shows the notice instead of staying blank. The spill file a pull source keeps is job metadata (`JobView.output.spillPaths`, reported by every pump read and withdrawn once a read stops naming it), not per-chunk metadata, and the model's read renders the shell tools' dropped-output notice for a producer-side gap as well as for ring eviction, naming those files even after the gap chunk itself was evicted — the `before this read` variant this change had introduced is gone. An observation generation that sees its job removed mid-stream (the owner's teardown) closes with the removed job's terminal projection instead of a failed read. A rejected background spawn produces no process output, so the shell providers now serve the `spawn failed: …` note as the whole observed stderr stream (the consuming read still folds it in once), and `ShellProcess.observed` with both readers is required: the model's first `job_output` after such a failure reads exactly what master's consuming read rendered.
@@ -34,4 +34,4 @@ job seam 是逐步堆出来的。生产者要把输出声明两次——模型

 模型可见文本保持不变：状态行、工具描述与 schema、播报措辞逐字节相同，唯一新增的模型可见事实是 `killed` 状态行现在携带的 kill 原因。需要流式输出的生产者选择拉取源或 `append`，从不格式化消耗式增量。Web 客户端把每个进行中的 job 渲染为可展开，因此从不写输出的 job 显示为空的运行中面板而非静态行。`JobKindMap` 的合并发生在宿主侧，浏览器程序把 `JobView.kind` 视为它认识的 kind 集合，其余当作不透明字符串——名册对它也只做这些。

-合并 master 之后的评审跟进收紧了其中四条边。job 的第一个事件永远是 `registered`：通告先于泵，而泵的首轮 drain 同步执行且可能通告输出。已结算的环在模型的首次终态读取之前保留模型游标尚未消费的全部字节，因此在首次 `job_output` 之前结束的 job 不会丢失运行期上限保留的任何内容。`dsh-tool-jobs` 为每次等待调用保存一条带 `live` 标记的认领，调用方 abort 时在 abort 事件里同步清掉该标记，因此注册表的拒绝尚未传回工具之前宣布的结算仍会投递通知；超时的等待只丢弃自己的认领，并发的另一个等待仍覆盖该结算。浏览器把先于锚点发生的观察失败记录为带错误的视图，面板显示提示而不是留白。`@deepseek-ai/dsh-jobs/invariant` 伴生插件校验每个 job 的事件协议（先 `registered`、恰一次结算、最后 `removed`）以及每个通告的投影与注册表自身读取的一致性，这正是[伴生插件规则](../../../../packages/AGENTS.md)要求的交叉观察；先前只针对单个视图的字段校验已删除。拉取源保留的 spill 文件是 job 元数据（`JobView.output.spillPaths`，每次泵读取都会上报，读取不再点名时即撤回），不是逐块元数据；模型读取对生产者侧缺口与环淘汰都渲染 shell 工具的丢失输出提示并列出这些文件，即使缺口块本身已被淘汰——本次变更曾引入的 `before this read` 变体已删除。观察生成过程若在流中看到其 job 被移除（拥有者 teardown），以被移除 job 的终态投影收尾，而不是一次失败的读取。被拒绝的后台 spawn 不产生任何进程输出，因此 shell provider 现在把 `spawn failed: …` 提示作为 observed stderr 的整条流提供（消耗式读取仍只折入一次），且 `ShellProcess.observed` 及其两个读取器改为必填：这类失败之后模型的首次 `job_output` 读到的正是 master 的消耗式读取所渲染的内容。
+合并 master 之后的评审跟进收紧了其中四条边。job 的第一个事件永远是 `registered`：通告先于泵，而泵的首轮 drain 同步执行且可能通告输出。已结算的环在模型的首次终态读取之前保留模型游标尚未消费的全部字节，因此在首次 `job_output` 之前结束的 job 不会丢失运行期上限保留的任何内容。`dsh-tool-jobs` 为每次等待调用保存一条带 `live` 标记的认领，调用方 abort 时在 abort 事件里同步清掉该标记，因此注册表的拒绝尚未传回工具之前宣布的结算仍会投递通知；超时的等待只丢弃自己的认领，并发的另一个等待仍覆盖该结算。浏览器把先于锚点发生的观察失败记录为带错误的视图，面板显示提示而不是留白。拉取源保留的 spill 文件是 job 元数据（`JobView.output.spillPaths`，每次泵读取都会上报，读取不再点名时即撤回），不是逐块元数据；模型读取对生产者侧缺口与环淘汰都渲染 shell 工具的丢失输出提示并列出这些文件，即使缺口块本身已被淘汰——本次变更曾引入的 `before this read` 变体已删除。观察生成过程若在流中看到其 job 被移除（拥有者 teardown），以被移除 job 的终态投影收尾，而不是一次失败的读取。被拒绝的后台 spawn 不产生任何进程输出，因此 shell provider 现在把 `spawn failed: …` 提示作为 observed stderr 的整条流提供（消耗式读取仍只折入一次），且 `ShellProcess.observed` 及其两个读取器改为必填：这类失败之后模型的首次 `job_output` 读到的正是 master 的消耗式读取所渲染的内容。
@@ -6,8 +6,8 @@
  en: 6a4338564c01ad91
  zh: 241248cff9bd4cfc
 /agent-note-add-immutable-profile-resolution-generations/problem:
-  en: 8e192c176fe48c4c
-  zh: adb965d650088eb0
+  en: 907a40c722a6faff
+  zh: a471d7034d8c231f
 /agent-note-add-immutable-profile-resolution-generations/decision:
  en: a3022a87337058c5
  zh: 1d53a08a25ed6eb3
@@ -21,8 +21,8 @@
  en: 53a9e92698ce9a5d
  zh: 6124d446e8d4a532
 /agent-note-add-immutable-profile-resolution-generations/decision/immutable-generations:
-  en: cd4e64bd80f448a2
-  zh: 585e1fbd8721ae99
+  en: e10b224e0e68b701
+  zh: d43fbdf37e6bfc54
 /agent-note-add-immutable-profile-resolution-generations/decision/shared-esm-and-commonjs-rule:
  en: 0e0575a04a081b52
  zh: 94c74334939e6d13
@@ -33,8 +33,8 @@
  en: 99308bd758859e02
  zh: 35f1e7719fe80d2e
 /agent-note-add-immutable-profile-resolution-generations/decision/additive-package-changes:
-  en: 718dfa7826783f2a
-  zh: 21c3d5fdfae9cb99
+  en: 0e5e2006caec3c91
+  zh: fb3b61dd5692d2e3
 /agent-note-add-immutable-profile-resolution-generations/decision/filesystem-and-runtime-carriers:
  en: b0607713102a093d
  zh: 2de9c33bfaa0e3e2
@@ -45,8 +45,8 @@
  en: 2426173c58a17a48
  zh: 0423b3700273accd
 /agent-note-add-immutable-profile-resolution-generations/verification:
-  en: fbb17aa8fe62b1e8
-  zh: 2ed091fdfd995fc8
+  en: 74cb43ea2ccdb334
+  zh: b966bbed43a83c82
 /agent-note-add-immutable-profile-resolution-generations/consequences:
-  en: 54cae20b2734a07e
-  zh: caa334f8f7a40452
+  en: 457a7d1e82b45fe0
+  zh: 800036e083a7674c
@@ -8,7 +8,7 @@ English | [中文](2026-09-09-profile-resolution-generations.zh.md)

 A profile loads plugin rows from its own package project, while Harness packages and packages carried by selected bundles can live outside that project's ordinary dependency tree. Bridging the trees through shared symlinks, profile-owned links, or packaged-executable proxy packages persists package selections across processes and installations. Those files require reconciliation and locking, expose generated proxy manifests to metadata readers, and cannot represent a process-local change atomically.

-The runtime design keeps installation-first, ordered-bundle, and local-before-fallback precedence. It covers imports performed by plugin modules as well as Loader row imports and works in the main thread and Harness-owned Workers. Generation replacement preserves existing package mappings and local package names, permits linked-root membership changes, and never mutates a live table entry by entry.
+The runtime design keeps installation-first, ordered-bundle, and local-before-fallback precedence. It covers imports performed by plugin modules as well as Loader row imports and works in the main thread and Harness-owned Workers. Generation replacement preserves retained package identities, permits removing profile packages and changing linked-root membership, and never mutates a live table entry by entry.

 ## Decision

@@ -75,7 +75,7 @@ Linked-root membership is immutable within a generation. A successor may add or

 The router retains the real target of each successfully published link name for its lifetime, solely to validate successors. Removing a root does not erase that record or keep its directory intercepted. Re-adding the same name and target is allowed; a different target is rejected because Node caches real paths. Failed publication changes neither the current generation nor the recorded targets.

-The launcher constructs one startup generation. The service accepts a complete successor, but no package-manager transaction invokes replacement in this implementation.
+The launcher constructs one startup generation. `ProfileRuntimeResolution` retains only the installation anchor, Harness home, and optional profile directory as recomputation inputs; successors reread disk selection and layers rather than inheriting a supplied profile's synthetic layers. A generation without a profile directory can recompute installation packages. The [package refresh decision](2026-09-30-profile-package-refresh-and-manifest-invalidation.md) assigns successor publication to Plugin Manager operations.

 ### Shared ESM and CommonJS rule

@@ -105,9 +105,9 @@ New Workers inherit the latest published generation. Existing Workers keep the g

 ### Additive package changes

-A caller adding a package completes its pnpm transaction before constructing a successor generation. Replacement rejects any generation that changes the directory or version of an existing package. The caller publishes an additive successor before mounting the new Loader row; this implementation does not provide that package transaction. A mount failure may leave the package installed but inactive.
+A caller adding a package completes its pnpm transaction before constructing a successor generation. Replacement rejects any generation that changes the directory or version of a retained package. Plugin Manager publishes the successor before mounting the new Loader row. A mount failure may leave the package installed but inactive.

-Changing or removing an existing runtime package mapping, or removing a recorded profile-local package name, requires process restart because Node's ESM Module Map, CommonJS cache, existing object references, and running Workers can retain the old module identity. These restrictions do not prohibit removing a linked root from the interception scope. Generation replacement does not claim to unload modules.
+A retained package keeps its normalized directory, version, and scope; installation entries also keep their declaring anchor and cannot be removed. Violating these restrictions requires process restart because Node's ESM Module Map, CommonJS cache, existing object references, and running Workers can retain the old module identity. A profile entry may change its declaring anchor: deselecting the first bundle that reaches a shared dependency can leave another bundle selecting the same physical package. Profile-scoped mappings and profile-local package names may be removed; the caller stops their plugins before deleting package files. These restrictions do not prohibit removing a linked root from the interception scope. Generation replacement does not claim to unload modules.

 ### Filesystem and runtime carriers

@@ -142,7 +142,7 @@ Behavior tests exercise root order, transitive and peer dependencies, local and
 ## Verification

 - One eager computation supplies the runtime resolution; startup neither writes nor retires module-resolution data.
- [Generation tests](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) cover installation and selected-bundle graphs with ordinary directories and recursive symlinks, including different dependency versions beside logical and real anchors. They also cover linked-root removal, same-target restoration, overlapping roots, native misses, new requests from loaded modules, and relink rejection after removal.
+- [Generation tests](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) cover installation and selected-bundle graphs with ordinary directories and recursive symlinks, including different dependency versions beside logical and real anchors. They also cover same-package profile declarer changes, retained-identity rejection, captured-directory recomputation, linked-root removal, same-target restoration, overlapping roots, native misses, new requests from loaded modules, and relink rejection after removal.
 - [Source-launch tests](../../../../apps/cli/tests/source-launch.compat.spec.ts) and [built-bin tests](../../../../apps/cli/tests/built-bin.e2e.ts) run both profile layouts through the real CLI. They assert ESM/CJS versions, loaded paths, per-format dependency identity, and consistent Tools/AgentLoop module instances with an accessible scheduler key.
 - Pkg and Electron carriers select runtime resolution; Electron executes its Host in Node mode from the ASAR-backed dsh tree while native executable entries remain unpacked.
 - ESM and CommonJS adapters share one router and delegate final resolution to Node without `module.registerHooks` or `_findPath` replacement.
@@ -152,4 +152,4 @@ Behavior tests exercise root order, transitive and peer dependencies, local and

 ## Consequences

-Runtime startup avoids disk mutation and proxy manifests while retaining package-precedence rules. Real-directory anchors align dependency discovery with default Node loading and tsx workspace mapping, including cases where a logical symlink path would select another version. The implementation accepts the maintenance cost of Node Internal compatibility tests and an early, self-contained bootstrap in each owned Worker; it provides no disk-only backend or dual comparison mode. Package mappings and local package names remain additive; linked-root membership may change without unloading modules.
+Runtime startup avoids disk mutation and proxy manifests while retaining package-precedence rules. Real-directory anchors align dependency discovery with default Node loading and tsx workspace mapping, including cases where a logical symlink path would select another version. The implementation accepts the maintenance cost of Node Internal compatibility tests and an early, self-contained bootstrap in each owned Worker; it provides no disk-only backend or dual comparison mode. Profile package records and linked-root membership may be removed without unloading modules; retained package identities stay unchanged.
@@ -8,7 +8,7 @@ Status: implemented

 profile 从自己的包项目加载插件配置项，而 Harness 包和所选 bundle 携带的包可能位于该项目普通依赖树之外。通过共享 symlink、profile 自有链接或打包可执行文件的代理包连接两棵依赖树，会让选包结果跨进程和安装版本持续存在。这些文件需要协调和锁来维护，并向元数据读取方暴露生成的代理 manifest（元数据清单），也无法原子表示进程内变更。

-运行时设计保留安装优先、有序 bundle 和本地包优先于 fallback 的顺序。它覆盖插件模块内部的 import 以及 Loader 配置项的 import，并在主线程和 Harness 自有 Worker 中工作。generation 替换保留既有包映射和本地包名，允许调整 linked root 集合，不会逐项修改正在使用的表。
+运行时设计保留安装优先、有序 bundle 和本地包优先于 fallback 的顺序。它覆盖插件模块内部的 import 以及 Loader 配置项的 import，并在主线程和 Harness 自有 Worker 中工作。generation 替换保持保留包的身份不变，允许移除 profile 包和调整 linked root 集合，不会逐项修改正在使用的表。

 ## Decision

@@ -75,7 +75,7 @@ linked root 集合在一个 generation 内不可变。后继 generation 可以

 解析器在自身生命周期内保留每个已成功发布的 link 名称对应的真实目标，仅用于校验后继 generation。移除 root 不会抹掉该记录，也不会让其目录继续被拦截。同名、同目标可以重新加入；不同目标会被拒绝，因为 Node 缓存真实路径。发布失败时，当前 generation 和已记录目标均不变。

-launcher 只构造启动 generation。服务接受完整的后继 generation，但本实现没有包管理器事务调用替换操作。
+launcher 只构造启动 generation。`ProfileRuntimeResolution` 仅保留安装锚点、Harness home 和可选的 profile 目录作为重算输入；后继代重新读取磁盘上的选择与配置层，不继承传入 profile 的合成层。没有 profile 目录的 generation 可以重算安装包。[包操作刷新决策](2026-09-30-profile-package-refresh-and-manifest-invalidation.zh.md)规定由 Plugin Manager 的操作发布后继代。

 ### ESM 与 CommonJS 共用规则

@@ -105,9 +105,9 @@ runtime resolution 列出它提供的包；Loader entries 组成活动插件列

 ### 只增加包的变更

-添加包的调用方先完成 pnpm 事务，再构造下一代。替换操作会拒绝改变任何既有 package name 的目录或版本。调用方先发布只增加映射的后继 generation，再挂载新的 Loader 配置项；本实现不提供该包事务。挂载失败可以留下已安装但未启用的包。
+添加包的调用方先完成 pnpm 事务，再构造下一代。替换操作会拒绝改变任何保留包的目录或版本。Plugin Manager 先发布后继 generation，再挂载新的 Loader 配置项。挂载失败可以留下已安装但未启用的包。

-修改或删除既有运行时包映射，或删除已记录的 profile 本地包名，需要重启，因为 Node 的 ESM Module Map、CommonJS cache、现存对象引用和运行中的 Worker 都可能保留旧模块 identity。这些限制不禁止从拦截范围移除 linked root。generation 换代不声称卸载模块。
+保留包的规范化目录、版本和作用域必须不变；安装条目还必须保留声明锚点，且不能移除。违反这些限制需要重启，因为 Node 的 ESM Module Map、CommonJS cache、现存对象引用和运行中的 Worker 都可能保留旧模块 identity。profile 条目可以改变声明锚点：取消选入最先找到共享依赖的组合包后，另一个组合包仍可能选中同一物理包。profile 范围的映射和 profile 本地包名可以移除；调用方在删除包文件之前先停止相关插件。这些限制不禁止从拦截范围移除 linked root。generation 换代不声称卸载模块。

 ### 文件系统与运行时载体

@@ -142,7 +142,7 @@ generation 构造发生在启动或显式更新阶段，不属于单次 resolve
 ## Verification

 - 一次 eager 计算供应 runtime resolution；启动既不写入也不退休模块解析数据。
- [Generation 测试](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts)覆盖普通目录和递归软链接下的安装图与所选 bundle 图，包括逻辑锚点和真实锚点旁存在不同依赖版本的情况。测试还覆盖 linked root 移除、同目标恢复、重叠 root、原生缺包、已加载模块的新请求，以及移除后重新链接不同目标时的拒绝。
+- [Generation 测试](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts)覆盖普通目录和递归软链接下的安装图与所选 bundle 图，包括逻辑锚点和真实锚点旁存在不同依赖版本的情况。测试还覆盖同包 profile 声明者变更、保留包身份变更拒绝、捕获目录后的重算、linked root 移除、同目标恢复、重叠 root、原生缺包、已加载模块的新请求，以及移除后重新链接不同目标时的拒绝。
 - [源码启动测试](../../../../apps/cli/tests/source-launch.compat.spec.ts)与[构建入口测试](../../../../apps/cli/tests/built-bin.e2e.ts)通过真实 CLI 运行两种 profile 布局，断言 ESM/CJS 版本、加载路径、各模块格式内的依赖身份，以及一致的 Tools/AgentLoop 模块实例和可访问的 scheduler 键。
 - pkg 与 Electron 载体选择 runtime 解析；Electron 以 Node 模式从 ASAR 承载的 dsh 依赖树执行 Host，原生可执行条目保持 unpacked。
 - ESM 与 CommonJS 适配器共享同一个路由器，并把最终解析委托给 Node，不使用 `module.registerHooks` 或替换 `_findPath`。
@@ -152,4 +152,4 @@ generation 构造发生在启动或显式更新阶段，不属于单次 resolve

 ## Consequences

-runtime 启动避免磁盘修改和代理 manifest，同时保留包优先级规则。真实目录锚点让依赖发现对齐 Node 默认加载与 tsx workspace 映射，也覆盖软链接逻辑路径会选中另一版本的情况。实现需要持续维护 Node Internal 兼容测试，并在每个自有 Worker 中尽早执行自包含 bootstrap；它不提供纯磁盘后端或 dual 对比模式。包映射和本地包名仍只允许新增；linked root 集合可以变化，而不卸载模块。
+runtime 启动避免磁盘修改和代理 manifest，同时保留包优先级规则。真实目录锚点让依赖发现对齐 Node 默认加载与 tsx workspace 映射，也覆盖软链接逻辑路径会选中另一版本的情况。实现需要持续维护 Node Internal 兼容测试，并在每个自有 Worker 中尽早执行自包含 bootstrap；它不提供纯磁盘后端或 dual 对比模式。profile 包记录和 linked root 集合可以移除，而不卸载模块；保留包的身份保持不变。
@@ -9,11 +9,11 @@
  en: bd3ad5505204ec0b
  zh: 770b6089c760d99f
 /agent-note-plugin-owned-message-projections/decision:
-  en: 2b33d4a1cfba0f53
-  zh: 55347f3ecf234862
+  en: 50c02960b1f087c6
+  zh: fa3f5c18b897eab9
 /agent-note-plugin-owned-message-projections/alternatives-considered:
-  en: c6e4c770739dca68
-  zh: 7bfcb3dda06a22a1
+  en: b0da1fbf24bc506a
+  zh: c4e35896599f824c
 /agent-note-plugin-owned-message-projections/consequences:
  en: c2f3ff0b9639bec5
  zh: 357f90d9a3423751
@@ -16,7 +16,7 @@ The `@messageProjection` tag on the owning `SessionEventMap` member generates th

 The compaction-image-offload plugin registers its definition through a fiber-owned `ctx.sessions.registerMessageProjection()` effect. Each event has one registered owner. Removing a definition invalidates pending committed decisions and cached reads that used it; a replacement definition requires restoring the session. Rejected, uncommitted candidates retain no interpreter dependency.

-Detached readers pass definitions explicitly. The current Session format catalog assembles the same browser-safe plugin exports for persistence validation and offline queries. This static assembly does not mount recovery listeners. Live sessions use the registered composition, while compaction invariants borrow that composition's definitions. No process-global registry or import-time registration is involved.
+Detached readers pass definitions explicitly. The current Session format catalog assembles the same browser-safe plugin exports for persistence validation and offline queries. This static assembly does not mount recovery listeners. Live sessions use the registered composition. No process-global registry or import-time registration is involved.

 The image event payload and required-on-read semantics remain owned by the image-offload note. Its indexes, selection policy, retry behavior, and SDK recordings are unchanged; this decision partially supersedes that note's core-owned interpretation.

@@ -26,7 +26,7 @@ The image event payload and required-on-read semantics remain owned by the image

 **Use the ordinary session-projection registry.** Its folds expose domain state after commit. They cannot veto an invalid append or supply canonical `deriveMessages()` content without another integration point.

-**Transform only the outgoing request.** Compaction, fork, offline replay, and request invariants also derive messages. A send-time transformation does not cover these consumers.
+**Transform only the outgoing request.** Compaction, fork, and offline replay also derive messages. A send-time transformation does not cover these consumers.

 ## Consequences

@@ -16,7 +16,7 @@ Status: implemented

 compaction-image-offload 插件通过 fiber 拥有的 `ctx.sessions.registerMessageProjection()` effect 注册处理器。每种事件只有一个注册者。移除处理器后，尚未应用的已提交决策和使用过它的缓存读取都会失效。替换处理器需要重新恢复会话。被拒绝且未提交的候选事件不会保留对处理器的依赖。

-独立读取器显式传入处理器。当前 Session 格式目录装配相同的浏览器安全插件导出，供持久数据校验和离线查询使用。这项静态装配不挂载恢复监听器。实时会话使用已注册的组合，压缩 invariant 借用该组合的处理器。不使用进程全局注册表，也不在导入模块时注册。
+独立读取器显式传入处理器。当前 Session 格式目录装配相同的浏览器安全插件导出，供持久数据校验和离线查询使用。这项静态装配不挂载恢复监听器。实时会话使用已注册的组合。不使用进程全局注册表，也不在导入模块时注册。

 图片事件载荷和读取时必须识别的语义仍由图片省略记录负责。索引、选图策略、重试行为和 SDK 录制保持不变。本决策部分取代该记录中由核心负责解释事件的职责划分。

@@ -26,7 +26,7 @@ compaction-image-offload 插件通过 fiber 拥有的 `ctx.sessions.registerMess

 **使用普通的 session-projection 注册表。** 它的折叠在提交后公开领域状态。没有额外集成点，它无法否决无效追加，也无法提供标准 `deriveMessages()` 内容。

-**只转换发出的请求。** 压缩、分叉、离线回放和请求 invariant 也会派生消息。发送时转换无法覆盖这些消费方。
+**只转换发出的请求。** 压缩、分叉和离线回放也会派生消息。发送时转换无法覆盖这些消费方。

 ## 影响

@@ -12,8 +12,8 @@
  en: cf072f53de09faca
  zh: 9edd5c4a2bfaae5a
 /agent-note-sandboxed-node-execution-for-ptc/decision/resolved-inputs-and-policy:
-  en: e93df995efab569a
-  zh: 850daf02d1207028
+  en: 3aef37bb4f8a8e53
+  zh: a7b477324d486ab3
 /agent-note-sandboxed-node-execution-for-ptc/decision/control-and-lifetime:
  en: 2c7a694b04951772
  zh: 133b95b0477b127f
@@ -22,7 +22,7 @@ The host preserves `ELECTRON_RUN_AS_NODE` for child startup; the bootstrap remov

 File mode, observed denial and enforcement completeness travel in `PtcRunResult.sandbox` separately from the program outcome. Restricted execution fails if the required sandbox backend cannot launch. Full access is an explicit policy mode. Program success does not prove full enforcement, and neither the `process` descriptor nor the extra control pipe claims multi-tenant isolation.

-The private Python provider keeps its existing execution implementation and configured wall deadline. Its resolver accepts cwd but rejects an explicit file policy or per-call timeout override; a capability descriptor never silently grants unsupported protection.
+The [experimental Python provider](../../../../packages/experimental/ptc-runtime-python/README.md) shares the resolved file policy and sandbox diagnostics while retaining its local Unix execution and configured wall deadline. Per-call timeout overrides remain unsupported.

 ### Control and lifetime

@@ -22,7 +22,7 @@ Host 在子进程启动时保留 `ELECTRON_RUN_AS_NODE`；bootstrap 在求值前

 文件模式、观察到的拒绝与强制完整性通过 `PtcRunResult.sandbox` 独立于程序结果传递。所需沙箱后端无法启动时，受限执行失败。完整访问是显式策略模式。程序成功不证明完整强制能力，`process` 描述符与额外控制管道也不声明多租户隔离。

-私有 Python 提供方保留现有执行实现与配置的经过时间截止。其解析器接受 cwd，但拒绝显式文件策略或单次 timeout 覆盖；能力描述符不会静默授予不受支持的保护。
+[实验性 Python 提供方](../../../../packages/experimental/ptc-runtime-python/README.zh.md)共享已解析文件策略与沙箱诊断，同时保留本地 Unix 执行和配置的经过时间截止。仍不支持单次 timeout 覆盖。

 ### 控制与生命周期

@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-09-13-session-working-directory.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-13-session-working-directory.md
+/agent-note-session-working-directory:
+  en: 4d5b74f6b55a2270
+  zh: 8323ea3fbdf8fd8d
+/agent-note-session-working-directory/problem:
+  en: 31fba384d90ce7d2
+  zh: f8b814868f3280c3
+/agent-note-session-working-directory/decision:
+  en: 9ccde1c5e635b9c0
+  zh: 4dc76229703d3ef7
+/agent-note-session-working-directory/alternatives-considered:
+  en: f0995feb9b6bcce8
+  zh: 97417085fd17f70f
+/agent-note-session-working-directory/consequences:
+  en: 2dd3a4de72ee6d74
+  zh: be5d8a80c8eaac6e
@@ -0,0 +1,47 @@
+# Agent Note: Session working directory
+
+Status: implemented
+
+English | [中文](2026-09-13-session-working-directory.zh.md)
+
+## Problem
+
+A fixed Session creation directory cannot represent a task that changes checkout during its conversation. Independent tools resolving paths from different sources can read and write different projects, while changing the process directory also affects unrelated Sessions. Putting mutable directory information in the system prompt changes the reusable prompt prefix.
+
+## Decision
+
+`dsh-working-directory` owns one logged effective directory per Session. Its projection initializes from the immutable original project and folds `working-directory/change`; consumers read that owner instead of deriving execution paths from the header or sandbox root. Directory changes validate through the filesystem provider, serialize within the Session, and publish only after the new directory is available.
+
+The `dsh-base` composition mounts `working_directory({ cd? })` globally. The tool reads or changes the Session directory, so every Agent preset can select or recover it, including presets without file-editing tools. The Web composition keeps action tools in preset scopes.
+
+Required user-context snapshots carry the current value; each committed change attempts to queue a notice through the ordinary Agent inbox. Cancellation or disposal may discard unadmitted notices while the directory event survives for subsequent requests. The original project is the recovery destination when the selected directory disappears. Missing recovery destinations produce an error. Write permissions remain independent.
+
+Subagents capture the parent's current directory or an explicit override and commit their selected directory after inherited history. Existing processes, terminals, and persistent shells keep their process-local directory. Project instructions, skills, and completion follow the effective directory without changing Session identity, grouping, or runtime composition.
+
+Live Session skill catalogs and file completion validate through the same directory owner. These reads can commit recovery and queue its notice before discovery, keeping discovered files and subsequent operations tied to the committed Session directory. Cold skill catalogs read the recorded projection without activating an Agent.
+
+Web sidebar terminal environment lookup reads the effective directory without filesystem validation or recovery, so a missing directory does not prevent reconnecting to a retained terminal. New terminal creation validates and recovers through the directory owner before spawning; the process keeps that directory independently of later Session changes.
+
+Playwright MCP and Chrome DevTools MCP validate the effective directory when acquiring a Session's MCP connection and use it to launch the server. Later directory changes do not restart the retained server or change its process directory.
+
+File links and command directory labels use result metadata captured when each operation runs, so historical rows remain correct after later directory changes.
+
+The [prompt-variables note](2026-07-05-prompt-variables-and-tool-guidance-ownership.md) retains strict interpolation, route-variable ownership, and tool-guidance ownership. The [environment-suffix note](../../archived/bug-fix/2026-09-06-environment-prompt-suffix.md) retains ordered prefix/suffix placement for deployment, Harness source, and Web guidance. This decision owns directory state and placement in user context.
+
+## Alternatives considered
+
+**Rewrite the Session header.** The header is immutable identity metadata used by storage, grouping, and permission roots. Rewriting it would conflate current execution state with the original project.
+
+**Let worktree tools own directory state.** Ordinary directory changes, filesystem tools, and subagents need the same value. A Git-specific owner would duplicate selection and recovery.
+
+**Change the process directory or synchronize every shell.** Concurrent Sessions and existing subprocesses have independent lifetimes. A Session change affects new directory-based operations, while a shell's `cd` remains local.
+
+**Keep directory text in the system prompt.** Mutable operational context belongs after retained history, using the same user-context mechanism as permission state.
+
+## Consequences
+
+The runtime exposes one directory owner and preserves the original project. Consumers migrate together, including filesystem, shell, instructions, skills, subagents, and both SDKs. Directory existence can change outside the harness, so validation and logged recovery occur at use. Required runtime context remains visible even when optional context is suppressed.
+
+`{{cwd}}` has no loop-provided value; custom personas that depend on that built-in fail strict interpolation. Deployments remove those references using the [system-prompt migration guidance](../../../../packages/core/system-prompt/README.md). When both the current directory and its recovery destination are unavailable, prompt assembly rejects model turns; the [directory service recovery guidance](../../../../packages/session/working-directory/README.md#known-limitations-and-deferred-work) requires restoring the directory or selecting an existing absolute directory through the SDK or host service.
+
+Verification covers independent Sessions, relative changes, replay, cancellation, recovery, tool disposal, user-context rendering, provider inheritance, and real directory-based operations.
@@ -0,0 +1,47 @@
+# Agent Note: Session working directory
+
+Status: implemented
+
+[English](2026-09-13-session-working-directory.md) | 中文
+
+## Problem
+
+固定的 Session 创建目录无法表示在对话中切换检出目录的任务。各工具从不同来源解析路径时，可能读写不同项目；改变进程目录还会影响其他 Session。把可变目录信息放入系统提示词会改变可复用的提示词前缀。
+
+## Decision
+
+`dsh-working-directory` 拥有每个 Session 的一个日志化有效目录。投影从不可变的原始项目初始化，并折叠 `working-directory/change`；消费者读取该服务，而不是从 header 或沙箱根目录派生执行路径。目录变更通过文件系统 provider 验证，在 Session 内串行执行，并只在新目录可用后发布。
+
+`dsh-base` 组合在全局挂载 `working_directory({ cd? })`。该工具读取或改变 Session 目录，使每个 Agent preset 都能选择或恢复它，包括没有文件编辑工具的 preset。Web 组合把操作工具放在 preset 作用域中。
+
+必需的用户上下文快照携带当前值；每次已提交变更都会尝试通过普通 Agent 收件箱排入通知。取消或销毁可能丢弃尚未进入请求的通知，但目录事件仍然保留，供后续请求使用。所选目录消失时恢复到原始项目。恢复目录也消失时返回错误。写权限保持独立。
+
+子代理捕获父代理当前目录或显式覆盖值，并在继承历史之后提交选定目录。已有进程、终端和持久 shell 保留进程局部目录。项目指令、技能和补全跟随有效目录，不改变 Session 身份、归属或运行时组合。
+
+活跃 Session 的技能目录与文件补全通过同一个目录 owner 验证目录。这些读取可在发现操作之前提交恢复并排入通知，使发现的文件与后续操作关联到已提交的 Session 目录。冷态技能目录读取已记录的投影，不激活 Agent。
+
+Web 侧栏终端的环境查询读取有效目录，不验证文件系统或执行恢复，因此目录缺失不会阻止重新连接保留的终端。新终端在创建进程前通过目录 owner 验证和恢复目录；后续 Session 目录变更不会改变该进程的目录。
+
+Playwright MCP 和 Chrome DevTools MCP 在获取 Session 的 MCP 连接时验证有效目录，并在该目录启动服务器。后续目录变更不会重启保留的服务器，也不会改变其进程目录。
+
+文件链接与命令目录标签使用各次操作执行时记录的结果元数据，因此后续目录变更不会使历史记录指向错误的位置。
+
+[提示词变量记录](2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md)保留严格插值、路由变量归属与工具指导归属。[环境后缀记录](../../archived/bug-fix/2026-09-06-environment-prompt-suffix.md)保留部署、Harness 源码与 Web 指导的有序前缀／后缀位置。本决策拥有目录状态及其用户上下文位置。
+
+## Alternatives considered
+
+**改写 Session header。** header 是存储、归属与权限根目录使用的不可变身份元数据。改写它会混淆当前执行状态与原始项目。
+
+**让 worktree 工具拥有目录状态。** 普通目录变更、文件系统工具和子代理需要同一个值。Git 专用 owner 会重复实现选择与恢复。
+
+**改变进程目录或同步所有 shell。** 并发 Session 与已有子进程具有独立生命周期。Session 变更影响新的目录相关操作，shell 内的 `cd` 则保持局部。
+
+**把目录文本留在系统提示词中。** 可变操作上下文应位于保留历史之后，复用权限状态的用户上下文机制。
+
+## Consequences
+
+运行时提供一个目录 owner，并保留原始项目。消费者一起迁移，包括文件系统、shell、指令、技能、子代理和两种 SDK。目录可能在 harness 之外消失，因此在使用时执行验证和日志化恢复。即使可选上下文被禁用，必需运行时上下文也仍然可见。
+
+`{{cwd}}` 没有循环提供的值；依赖该内置变量的自定义 persona 会触发严格插值错误。部署方按照[系统提示词迁移说明](../../../../packages/core/system-prompt/README.zh.md)移除这些引用。当前目录与恢复目标均不可用时，提示词组装会拒绝模型轮次；[目录服务恢复说明](../../../../packages/session/working-directory/README.zh.md#known-limitations-and-deferred-work)要求恢复目录，或通过 SDK 或 Host 服务选择现有的绝对目录。
+
+验证覆盖 Session 相互独立、相对路径变更、回放、取消、恢复、工具卸载、用户上下文渲染、provider 继承和真实目录操作。
@@ -15,8 +15,8 @@
  en: be64b541f4d81e7c
  zh: 8600531c08ab4288
 /agent-note-guided-plugin-installation/consequences:
-  en: e4536b20f3587497
-  zh: a8eeb1d3c578b785
+  en: bc1b116dd15ff420
+  zh: e886e84cc3081feb
 /agent-note-guided-plugin-installation/testing:
  en: 1e121dca5f7dc572
  zh: bcdb1b6482cc1af6
@@ -38,7 +38,7 @@ The install dialog put a spec straight into `pnpm add` and showed pnpm's termina

 ## Consequences

-`inspect`, `cancelInstall`, and the `plugin-manager/changed`, `plugin-manager/install-log`, and `plugin-manager/install-state` events join the manager's Remote; `listBundles` carries titles, rows, and overrides; `ChangeResult` gains `cancelled`, `bundle`, and `packageResult.kind`; the config gains `pnpmCommand`, `inspectTimeoutMs` and `githubConnectionTimeoutMs`. The dialog is four screens over one subject card.
+`inspect`, `cancelInstall`, and the `plugin-manager/changed`, `plugin-manager/install-log`, and `plugin-manager/install-state` events join the manager's Remote; `listBundles` carries titles, rows, and overrides; `ChangeResult` gains `cancelled`, `bundle`, `version`, and `packageResult.kind`; the config gains `pnpmCommand`, `inspectTimeoutMs` and `githubConnectionTimeoutMs`. The dialog is four screens over one subject card.

 ## Testing

@@ -38,7 +38,7 @@ Status: implemented

 ## 后果

-`inspect`、`cancelInstall` 以及 `plugin-manager/changed`、`plugin-manager/install-log`、`plugin-manager/install-state` 事件加入管理器的 Remote；`listBundles` 携带标题、行与覆盖项；`ChangeResult` 增加 `cancelled`、`bundle` 与 `packageResult.kind`；配置增加 `pnpmCommand`、`inspectTimeoutMs` 与 `githubConnectionTimeoutMs`。对话框是围绕同一张主题卡的四个画面。
+`inspect`、`cancelInstall` 以及 `plugin-manager/changed`、`plugin-manager/install-log`、`plugin-manager/install-state` 事件加入管理器的 Remote；`listBundles` 携带标题、行与覆盖项；`ChangeResult` 增加 `cancelled`、`bundle`、`version` 与 `packageResult.kind`；配置增加 `pnpmCommand`、`inspectTimeoutMs` 与 `githubConnectionTimeoutMs`。对话框是围绕同一张主题卡的四个画面。

 ## 测试

@@ -9,8 +9,8 @@
  en: 2c774d05ae75784f
  zh: 619ba7f281b13233
 /agent-note-host-owned-scheduled-messages/decision:
-  en: 98c9d9ee6954beab
-  zh: 32139d9452c544f4
+  en: 1210b3975fd26bb3
+  zh: 3322e6d0aa63fdb0
 /agent-note-host-owned-scheduled-messages/alternatives-considered:
  en: 21d7ec9a9ff3cbf2
  zh: 93d03b8b3012aa7e
@@ -14,7 +14,7 @@ The existing Schedule package owns one Host storage domain containing each task'

 The task domain declares the whole-unit layout. Tasks are authoritative, so the JSON backend rejects an unreadable file, malformed document, unsupported version, or invalid task as a complete load failure instead of interpreting it as deletion. Failed recovery leaves `schedule.json` unchanged, while an initially absent file opens as an empty domain; repairing the file preserves task identity. `Service.init` waits for both storage validation and runtime setup, management methods wait for the same initialization result, and an unloading owner releases late-acquired storage without starting dispatch. Dispatch admission is separate from initialization: an ancestor can close Agent admission after a task mutation commits but before runtime cleanup starts. That refusal is logged without automatic retry and does not turn the persisted mutation into a failed management result. Invalid storage and failed cleanup registration still reject startup.

-This replaces the earlier Session-log authority, live-only activation, and read-only catalog decisions. The [Schedule reference](../../../../packages/schedule/schedule/README.md) owns explicit absolute-time validation, fixed-rate arithmetic, and the distinction between queue admission and model completion. Historical `schedule/change` creation, fold, and invariant types remain restricted to After, At, and Every through `LegacyScheduleRecord`; a separate Host decoder accepts the current `ScheduleRecord`, including Daily, Weekly, and Cron. The Host record decoder requires a stored `title` that is non-empty after trimming, already trimmed, and at most 120 characters, and the strict task schema rejects the whole domain open instead of dropping such a task. The historical change decoder tolerates an absent `title` so an already-written Session log stays readable, and it applies the same three checks when the member is present. The storage domain remains version 1. Historical events do not populate that domain, and existing `at` tasks are not converted into daily or weekly rules. Loading a Session with active legacy reminders warns that they must be recreated.
+This replaces the earlier Session-log authority, live-only activation, and read-only catalog decisions. The [Schedule reference](../../../../packages/schedule/schedule/README.md) owns explicit absolute-time validation, fixed-rate arithmetic, and the distinction between queue admission and model completion. Historical `schedule/change` creation and fold types remain restricted to After, At, and Every through `LegacyScheduleRecord`; a separate Host decoder accepts the current `ScheduleRecord`, including Daily, Weekly, and Cron. The Host record decoder requires a stored `title` that is non-empty after trimming, already trimmed, and at most 120 characters, and the strict task schema rejects the whole domain open instead of dropping such a task. The historical change decoder tolerates an absent `title` so an already-written Session log stays readable, and it applies the same three checks when the member is present. The storage domain remains version 1. Historical events do not populate that domain, and existing `at` tasks are not converted into daily or weekly rules. Loading a Session with active legacy reminders warns that they must be recreated.

 A plugin-sourced `followup()` synchronously appends the message to the Session inbox. Successful Session flush acknowledges durable delivery. One task-record put stores `lastDelivery`, appends a delivery record with the occurrence target, acknowledgment time, actual message id, and instruction snapshot, and updates the one-shot's `inactive` status or the recurring task's next target and status. Task state and its saved history therefore share one commit. Inactive tasks remain stored and never schedule another delivery; explicit deletion stops future delivery and removes the row together with its saved records. These records acknowledge inbox delivery, not user receipt or model execution completion.

@@ -14,7 +14,7 @@ Status: implemented

 任务 domain 声明整 unit 布局。任务是权威数据，因此 JSON 后端会把文件不可读、文档损坏、版本不受支持或任务非法作为整批加载失败，而不是解释为删除。恢复失败不会改写 `schedule.json`，初始不存在的文件则作为空 domain 打开；修复该文件后会保留任务身份。`Service.init` 等待存储校验和运行时初始化，管理方法等待同一初始化结果；拥有方卸载时释放迟到的存储资源，而不开始投递。投递调度准入与初始化分开：任务变更提交后、运行时清理开始前，祖先可能关闭 Agent 准入。此类拒绝会记录日志而不自动重试，不会将已持久化的变更变成失败的管理结果。存储非法和清理注册失败仍拒绝启动。

-本决策替代先前的 Session 日志权威来源、仅 live 时激活和只读目录决策。[Schedule 参考](../../../../packages/schedule/schedule/README.zh.md)负责显式绝对时间校验、固定速率计算，以及区分排队接纳与模型完成。历史 `schedule/change` 的创建、fold 和 invariant 类型通过 `LegacyScheduleRecord` 保持为 After、At 和 Every；独立的宿主解码器接受包含 Daily、Weekly 与 Cron 的当前 `ScheduleRecord`。宿主记录解码器要求已存储的 `title` 去除首尾空白后非空、本身已去除首尾空白且不超过 120 个字符，严格的 task schema 会拒绝整个 domain 的打开，而不是丢弃这样的任务。历史变更解码器容忍缺失的 `title`，以便已写入的 Session 日志仍可读取；该成员存在时，同样按这三项检查校验。storage domain 保持版本 1。历史事件不会填充该 domain，已有 `at` 任务也不会转换为每日或每周规则。加载含有活动旧提醒的 Session 时，会警告需要重新创建提醒。
+本决策替代先前的 Session 日志权威来源、仅 live 时激活和只读目录决策。[Schedule 参考](../../../../packages/schedule/schedule/README.zh.md)负责显式绝对时间校验、固定速率计算，以及区分排队接纳与模型完成。历史 `schedule/change` 的创建与 fold 类型通过 `LegacyScheduleRecord` 保持为 After、At 和 Every；独立的宿主解码器接受包含 Daily、Weekly 与 Cron 的当前 `ScheduleRecord`。宿主记录解码器要求已存储的 `title` 去除首尾空白后非空、本身已去除首尾空白且不超过 120 个字符，严格的 task schema 会拒绝整个 domain 的打开，而不是丢弃这样的任务。历史变更解码器容忍缺失的 `title`，以便已写入的 Session 日志仍可读取；该成员存在时，同样按这三项检查校验。storage domain 保持版本 1。历史事件不会填充该 domain，已有 `at` 任务也不会转换为每日或每周规则。加载含有活动旧提醒的 Session 时，会警告需要重新创建提醒。

 插件来源的 `followup()` 同步将消息追加到 Session 收件箱。Session flush 成功后确认持久投递。一次任务记录 put 存储 `lastDelivery`，追加包含发生目标、确认时间、真实消息 id 和指令快照的发送记录，并更新一次性任务的 `inactive` 状态或重复任务的下一目标和状态。因此，任务状态与其保存的历史共用一次提交。未运行任务仍保留在存储中，且不会再次安排投递；显式删除会阻止后续投递，并把该行连同其已保存记录一并移除。这些记录确认收件箱投递，不表示用户收到消息或模型执行完成。

@@ -9,11 +9,11 @@
  en: cfb527c1c2ca661a
  zh: b61a906330cdaf97
 /agent-note-mandatory-native-v4-relationship-validation/decision:
-  en: 14feaf74a58d5609
-  zh: 8aea80c89110e638
+  en: 534efaae5eb9beb0
+  zh: ccb3734458248383
 /agent-note-mandatory-native-v4-relationship-validation/alternatives-considered:
-  en: d6296e00a6b30d48
-  zh: 9f7074c69fb42e5f
+  en: 96a37d9ba0252630
+  zh: fdf2d085805f0010
 /agent-note-mandatory-native-v4-relationship-validation/consequences:
  en: b76aaca1c35dcc6c
  zh: b933c2518c64c60c
@@ -16,7 +16,7 @@ The V4 format restorer and current JSONL scanner share one mandatory cross-event

 An unfinished tail may retain an open turn, step, tool call, or compaction. A closing event must settle the relationships it closes. An inherited unfinished compaction ends at its `session/end-seed` marker; it does not constrain the child's lifecycle. Repair message identities retain their historical numeric suffix after earlier migrations change sequence coordinates. Fork repairs retain their separately validated native identities.

-Installed Session adoption continues to own event envelopes, message roles and metadata, canonical request headers, and surface replacement reference coverage. Optional runtime invariants provide diagnostics; their installation is not required for durable admission. Native system-message admission also validates coordinates, identity, content blocks, and known image/tool-call fields before physical recovery can discard rows. Additional JSON fields and unknown nonempty content tags remain intact; retired tool-result wrappers are refused. Retired `request/header.header.system` and required `tool/code-dispatch*` tags remain hard refusals before recovery; obsolete ignorable PTC records remain opaque. Physical framing alone does not establish semantic validity.
+Installed Session adoption continues to own event envelopes, message roles and metadata, canonical request headers, and surface replacement reference coverage. Native system-message admission also validates coordinates, identity, content blocks, and known image/tool-call fields before physical recovery can discard rows. Additional JSON fields and unknown nonempty content tags remain intact; retired tool-result wrappers are refused. Retired `request/header.header.system` and required `tool/code-dispatch*` tags remain hard refusals before recovery; obsolete ignorable PTC records remain opaque. Physical framing alone does not establish semantic validity.

 A retired tool-result wrapper outside its owning `tool/result` row would require changing the event, role, or source to represent it in V4. The adjacent migration lifts only the canonical owned wrapper; target restoration refuses wrappers remaining in interpreted content. Native row admission applies the same refusal before recoverable tail suppression. The check follows declared message, content, and Assistant-stream slots instead of recursively inspecting JSON, so tool arguments, replay state, schema parameters, nested extensions, and unknown ignorable payloads retain their recorded values.

@@ -26,8 +26,6 @@ A retired tool-result wrapper outside its owning `tool/result` row would require

 **Project V4 back into a frozen V3 validation view.** This couples current acceptance to retired representations and invites new fields to disappear in the projection. Frozen generations remain independently readable, while the current restorer interprets its own fields.

-**Rely on optional runtime invariants.** Detached readers and restoration paths may not install diagnostic companions. A required relationship must be checked before publication or consumption of the restored Session.
-
 ## Consequences

 The native restorer maintains one bounded state machine per read and rejects contradictions before successor publication. Frozen V0–V3 validators and committed Session generations remain unchanged. Public catalog regressions cover invalid relationships alongside partial tails, inherited cuts, immutable unknown attribution, and complete tool exchanges; these checks enforce the declared V4 representation without changing its schemas. Breaking changes require a successor; compatible additions use new acknowledgements, and implementation fixes preserve the declared meaning.
@@ -16,7 +16,7 @@ V4 格式恢复器与当前 JSONL 扫描器共用同一强制跨事件关系校

 未完成的尾部可以保留打开的 turn、step、工具调用或压缩事务。关闭事件必须结清它关闭的关系。继承的未完成压缩事务在其 `session/end-seed` 标记处结束，不约束子 Session 的生命周期。较早迁移改变序号坐标后，修复消息身份仍保留历史数字后缀。fork 修复保留经过独立校验的原生身份。

-已安装的 Session 接纳器继续负责事件封装、消息角色与元数据、规范请求头，以及 surface 替换的引用覆盖。可选运行时不变式提供诊断；持久化准入不要求安装它们。原生 system 消息准入还会在物理恢复可能丢弃行之前，校验坐标、身份、内容块及已知 image/tool-call 字段。额外 JSON 字段和非空的未知内容标签保持不变，退役的 tool-result 包装会被拒绝。退役的 `request/header.header.system` 和必需的 `tool/code-dispatch*` 标签仍在恢复前强制拒绝；标记为可忽略的过时 PTC 记录保持不透明。仅通过物理分帧不能证明语义有效。
+已安装的 Session 接纳器继续负责事件封装、消息角色与元数据、规范请求头，以及 surface 替换的引用覆盖。原生 system 消息准入还会在物理恢复可能丢弃行之前，校验坐标、身份、内容块及已知 image/tool-call 字段。额外 JSON 字段和非空的未知内容标签保持不变，退役的 tool-result 包装会被拒绝。退役的 `request/header.header.system` 和必需的 `tool/code-dispatch*` 标签仍在恢复前强制拒绝；标记为可忽略的过时 PTC 记录保持不透明。仅通过物理分帧不能证明语义有效。

 退役的 tool-result 包装若不属于对应的 `tool/result` 行，就需要改变事件、角色或来源才能在 V4 中表示。相邻迁移只提升规范的自有包装；目标恢复器拒绝解释内容中剩余的包装。原生行准入在可恢复尾部被忽略之前执行同样的拒绝。检查沿声明的消息、内容和 Assistant stream 字段进行，不递归扫描 JSON，因此工具参数、replay state、schema 参数、嵌套扩展和未知可忽略载荷保留其记录值。

@@ -26,8 +26,6 @@ V4 格式恢复器与当前 JSONL 扫描器共用同一强制跨事件关系校

 **将 V4 投影回冻结的 V3 校验视图。** 这会将当前准入与退役表示绑定，并容易让新增字段在投影中消失。冻结代际仍可独立读取，当前恢复器解释自己的字段。

-**依赖可选运行时不变式。** 分离读取器和恢复路径可能不安装诊断组件。必需关系必须在发布或消费恢复后的 Session 之前完成校验。
-
 ## Consequences

 原生恢复器为每次读取维护独立状态机，在发布后继文件之前拒绝矛盾。冻结的 V0–V3 校验器及已提交的 Session 代际保持不变。公开目录回归覆盖无效关系、部分尾部、继承切分点、未知归属的不可变保存，以及完整工具交互；这些检查落实已声明的 V4 表示，不改变其 schema。破坏性变更要求后继版本；兼容新增使用新的确认记录，实现修复须保留声明的含义。
@@ -9,11 +9,11 @@
  en: 2ba6c43b20a3d347
  zh: 5647179ddaa38ad9
 /agent-note-ship-experimental-capabilities-as-optional-bundles/decision:
-  en: 0d6c40e376fb6e48
-  zh: b0cf2ded4e395942
+  en: e6ffc783859d7509
+  zh: 8678f323985a24f4
 /agent-note-ship-experimental-capabilities-as-optional-bundles/alternatives-considered:
-  en: a65d84004e48b3ef
-  zh: 17221f08e7a8a89b
+  en: 9ff0511566948d8b
+  zh: 4e1e37b79f63d390
 /agent-note-ship-experimental-capabilities-as-optional-bundles/consequences:
-  en: d690cf4d49c6af79
-  zh: 1c7a3077c35ae5b8
+  en: 9d2b313f15fc9ce0
+  zh: 522341c83565ac33
@@ -10,9 +10,13 @@ The Web plugin page offered two optional bundles, Agent Teams and voice input. A

 ## Decision

-`OPTIONAL_BUNDLES` lists Agent Teams, voice input, Auto review, and the Inspector profile. Every optional bundle declares `icon` and exports `./locale/*.json` with `meta.title` and `meta.description`, so the Official group renders a localized title, description, and image; `verify-default-product-isolation` rejects an optional bundle without them. The Inspector profile owns the package-named bundle patch. The standalone Inspector's `cordis.patch.yml` mounts its local built entry as an explicit repository overlay; [Session Inspector](../feature/2026-09-24-session-inspector.md) owns the inspection behavior and activation choices.
+`OPTIONAL_BUNDLES` owns the installation's default-off selections, including maintained optional capabilities and experimental capabilities. Every bundle declares `icon` and exports `./locale/*.json` with `meta.title` and `meta.description`; the Official group displays that metadata. A bundle's presentation does not determine its [experimental status](../../../../packages/experimental/README.md#status). The isolation check validates admission and still rejects experimental dependencies of nonexperimental bundles.

-An optional bundle is a runtime dependency of the installation, so its dependency graph is downloaded by every `dsh` install. The list weighs the added installation cost: Auto review reuses the installation's closure, while the Inspector profile adds inspection packages, `serve-static`/`open`/`ws`, and 535 mirrored DevTools resources (about 11.95 MiB uncompressed), without another browser binary. The Inspector profile appears in the default plugin list but remains disabled until selected. The browser-use and computer-use providers stay explicit compositions: Playwright MCP, Chrome DevTools MCP, and the native Cua Driver runtime binaries add about 85 MB and 21 packages to every install whether or not the bundle is enabled, and a shipped Cua Driver MCP switch would offer a capability whose executable the installation does not carry. Those provider packages keep locale display metadata for their component rows. Two more packages stay out for other reasons: `ptc-runtime-python` replaces the PTC runtime, and `workflow-ptc` rejects a non-TypeScript runtime at load while the Web presets carry `workflow-ptc` rows a bundle patch cannot reach; `browser-use-stagehand-native` requires a native model name and API key at schema validation with no configuration form on the page.
+An optional bundle's dependencies are downloaded with every `dsh` installation. [Reasoning translation](2026-10-05-anonymous-reasoning-translation.md) uses three experimental packages without adding third-party runtime dependencies. Admission therefore considers installation cost and whether a switch supplies a usable composition without an additional configuration form. Browser and computer providers remain explicit compositions because they add substantial runtimes or require an external executable. Stagehand requires model credentials; Python PTC replaces a core provider and conflicts with TypeScript workflow consumers. Demonstrative hooks, webhooks, and mods stay outside the list. [Session Inspector](../feature/2026-09-24-session-inspector.md) owns the Inspector's distinct activation behavior.
+
+Bundles add scoped rows with the [profile patch operation](../../../../packages/boot/app-boot/README.md): `preset` names a declaration row, and the ordinary patch operates on its child list. Full Web presets receive the optional model tools; minimal retains its current shell and working-directory tools. Search, Ralph, and terminals supply their own isolated services. Search opens one in-memory index on demand per retained preset revision; the Host search policy stays unchanged. Badge skills and title providers act on the Host. Existing Agents retain their preset generation, and later user patch layers retain precedence. Title replacement waits for disposal of the previous provider.
+
+Claude Code and Codex install on demand through the separate `ON_DEMAND_BUNDLES` catalog; the [on-demand native-bundle decision](2026-10-05-official-on-demand-bundles.md) owns the cost, version, and offline-discovery trade-offs.

 ## Alternatives considered

@@ -20,6 +24,8 @@ An optional bundle is a runtime dependency of the installation, so its dependenc

 **Mount the registration-only `computer-use` and `browser-use` services in `dsh-base`.** The shared composition would carry rows that only an optional provider bundle needs; a provider bundle can insert the service row from its own patch and dependencies.

+**Register preset extensions at runtime.** A separate registration path would need its own ordering, module resolution, generation updates, and inspection behavior. Profile patches keep one effective composition for boot, dumps, validation, and user overrides.
+
 ## Consequences

-The Official group carries four optional-bundle entries, each tagged experimental by its experimental name. Their runtime dependencies are installed even while the bundles are disabled. A browser-use or computer-use provider still needs its Service Definition and the provider in a profile patch or composition.
+Official discovery does not imply experimental status or a different plugin lifecycle. Switching a bundle off keeps its installed files; failed activation retains the existing saved-selection behavior. Scoped rows appear read-only under their bundle, and removal respects modules retained by live preset generations. Individual and combined composition tests cover the supported presets; live switching and recorded Sessions cover activation and model-visible behavior.
@@ -10,9 +10,13 @@ Web 插件页只提供两个可选 bundle：Agent Teams 与语音输入。Auto r

 ## 决策

-`OPTIONAL_BUNDLES` 列出 Agent Teams、语音输入、Auto review 与 Inspector profile。每个可选 bundle 都声明 `icon` 并导出带 `meta.title` 与 `meta.description` 的 `./locale/*.json`，官方分组因此能渲染本地化标题、描述和图片；`verify-default-product-isolation` 会拒绝缺少这些声明的可选 bundle。Inspector profile 管理按包名挂载的 bundle patch。独立 Inspector 的 `cordis.patch.yml` 通过本地构建入口提供显式仓库 overlay；[Session Inspector](../feature/2026-09-24-session-inspector.zh.md) 管理检查行为与启用选择。
+`OPTIONAL_BUNDLES` 管理安装随附且默认关闭的选项，包括维护中的可选能力与实验性能力。每个 bundle 声明 `icon`，并导出带 `meta.title` 与 `meta.description` 的 `./locale/*.json`；官方分组显示这些元数据。Bundle 的展示方式不决定其[实验性状态](../../../../packages/experimental/README.zh.md#status)。隔离检查校验准入，并继续拒绝非实验 bundle 的实验性依赖。

-可选 bundle 是安装的运行时依赖，其依赖图会随每次 `dsh` 安装一起下载。名单权衡新增安装成本：Auto review 复用安装闭包，Inspector profile 增加检查包、`serve-static`/`open`/`ws` 和 535 个镜像 DevTools 资源（未压缩约 11.95 MiB），但不携带另一个浏览器二进制。Inspector profile 在默认插件列表显示，选中前保持关闭。浏览器操作与电脑操作提供方仍保持显式组合：Playwright MCP、Chrome DevTools MCP 与原生 Cua Driver 运行时二进制会让每次安装多出约 85 MB、21 个包，无论 bundle 是否启用；而随附的 Cua Driver MCP 开关会提供一个安装本身并不携带其可执行文件的能力。这些提供方包保留 locale 显示元数据，供组件行使用。另有两个包因其他原因不纳入：`ptc-runtime-python` 会替换 PTC 运行时，而 `workflow-ptc` 在加载时拒绝非 TypeScript 运行时，且 Web preset 内含 bundle patch 无法触及的 `workflow-ptc` 行；`browser-use-stagehand-native` 在 schema 校验时就要求原生模型名称与 API 密钥，而插件页没有对应的配置表单。
+可选 bundle 的依赖随每次 `dsh` 安装下载。[思考过程翻译](2026-10-05-anonymous-reasoning-translation.zh.md)使用三个实验包，不增加第三方运行时依赖。因此准入需要考虑安装成本，以及开关能否在不增加配置表单的情况下提供可用组合。浏览器与电脑提供方仍使用显式组合，因为它们会增加较大的运行时或要求外部可执行文件。Stagehand 需要模型凭据；Python PTC 替换核心提供方，并与 TypeScript workflow 消费方冲突。演示性钩子、webhook 与模组不进入名单。[Session Inspector](../feature/2026-09-24-session-inspector.zh.md) 管理 Inspector 特有的激活行为。
+
+Bundle 通过 [profile patch 操作](../../../../packages/boot/app-boot/README.zh.md)添加作用域行：`preset` 指定声明行，普通 patch 对其子列表生效。完整 Web 预设获得可选模型工具；minimal 保持当前的 shell 与工作目录工具。搜索、Ralph 与终端提供自己的隔离服务。搜索在每个保留的预设修订中按需打开一个内存索引；Host 搜索策略保持不变。徽章技能与标题提供方作用于 Host。已有 Agent 保留其预设代际，后续用户 patch 层继续优先。标题替换等待前一个提供方完成清理。
+
+Claude Code 与 Codex 通过独立的 `ON_DEMAND_BUNDLES` 目录按需安装，其成本、版本与离线发现取舍由[按需原生 bundle 决策](2026-10-05-official-on-demand-bundles.zh.md)管理。

 ## 考虑过的替代方案

@@ -20,6 +24,8 @@ Web 插件页只提供两个可选 bundle：Agent Teams 与语音输入。Auto r

 **在 `dsh-base` 中挂载仅负责注册的 `computer-use` 与 `browser-use` 服务。** 共享组合将携带只有可选提供方 bundle 才需要的行；提供方 bundle 可以从自己的 patch 和依赖插入服务行。

+**在运行时注册预设扩展。** 独立注册路径需要自己的排序、模块解析、代际更新与检查行为。Profile patch 为启动、配置导出、校验和用户覆盖保留同一个有效组合。
+
 ## 后果

-官方分组包含四个可选 bundle 条目，每项都因实验包名而带实验性标签。即使组合包关闭，其运行时依赖也会安装。浏览器操作或电脑操作提供方仍需在 profile patch 或组合中同时挂载其 Service Definition 与提供方。
+官方发现不表示实验性状态，也不引入不同的插件生命周期。关闭 bundle 保留已安装文件；激活失败保留现有的已保存选择行为。作用域行在 bundle 内只读展示，删除操作尊重 live 预设代际仍持有的模块。独立与组合测试覆盖受支持的预设；实时切换与已记录 Session 覆盖激活和模型可见行为。
@@ -0,0 +1,37 @@
+# Bilingual-pair consistency record for 2026-09-30-profile-package-refresh-and-manifest-invalidation.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-30-profile-package-refresh-and-manifest-invalidation.md
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration:
+  en: ea66719b3dcdd21c
+  zh: 893364551594ddaf
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/problem:
+  en: e59e3f5c61158701
+  zh: 2ced78e3c84f604e
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/decision:
+  en: a15c7c13f167e5ac
+  zh: a15c7c13f167e5ac
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/decision/responsibilities:
+  en: 3ffd0c78fa204b04
+  zh: f468bab00a7ff357
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/decision/runtime-resolution:
+  en: ca45b973e1968533
+  zh: 002f23bb70e4fed7
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/decision/plugin-manager:
+  en: 9b04926c175f22e8
+  zh: fbf05dd4065b0738
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/decision/hmr-package-configuration-expiry:
+  en: c7de8dafe47a5587
+  zh: 6010a70d8451edd1
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/decision/future-work:
+  en: 31818f8f7f80470b
+  zh: ecb7ac85bb49cf6d
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/alternatives-considered:
+  en: 7c1c6d21570cda0d
+  zh: e6f8334c85f1b404
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/verification:
+  en: 939cedceed200cb2
+  zh: c7bb02d0da400c8d
+/agent-note-refresh-runtime-resolution-after-package-operations-and-expire-hmr-package-configuration/consequences:
+  en: 1b9e31b4e773fac5
+  zh: c140ce07fc64bd55
@@ -0,0 +1,119 @@
+# Agent Note: Refresh runtime resolution after package operations and expire HMR package configuration
+
+Status: implemented
+
+English | [中文](2026-09-30-profile-package-refresh-and-manifest-invalidation.zh.md)
+
+## Problem
+
+Two pieces of Host state did not follow changes while the process ran:
+
+- **Runtime resolution was built only at startup.** After a GUI install or enablement, nothing published the latest generation, so a bundle's private dependencies never reached the profile fallback and its bare plugins could not be found. After disablement or removal, a new generation could not remove profile-scoped entries or profile-local names, so stale records and package metadata remained. A newly installed package directory is new, and Node holds no stale cache for it; only the table was missing.
+- **Package configuration and module evaluation have separate caches.** Clearing a plugin's module cache does not refresh the package.json fields that Node uses for exports, main, imports, and format detection. A package.json can also be imported as a JSON module, in which case its consumers need ordinary module reloads.
+
+## Decision
+
+### Responsibilities
+
+| Owner | Does | Does not |
+|---|---|---|
+| resolver (`app-boot/src/profile-resolution/resolver.ts`) | `replace()` allows removing `scope: profile` entries and profile-local names | Touch any Node cache |
+| plugin-manager | Calls `pluginPackages.refresh()` at fixed points of package operations | Construct resolutions or manage module and package-configuration caches |
+| HMR (`packages/boot/hmr`) | Expires package configuration and preserves ordinary reloads for manifests loaded as JSON modules | Reload plugins for configuration-only manifests; handle `node_modules` package replacement |
+
+### Runtime resolution
+
+The [generation Note](2026-09-09-profile-resolution-generations.md) owns package identity and Worker inheritance rules.
+
+Validation of a new generation in `replace()`:
+
+- `scope: profile` entries may be removed.
+- Profile-local package names may be removed.
+- Retained profile entries keep their normalized directory, version, and scope, but may change declaring anchor when another selected bundle supplies the same package. Installation mappings and declaring anchors remain unchanged. The profile scope cannot change; a new local name cannot override an existing entry; a published link name cannot select another real directory.
+
+### Plugin Manager
+
+| Operation | Publication point |
+|---|---|
+| Install a new package | After pnpm succeeds and the bundle selection is saved, before reconciliation, whether or not the bundle is enabled |
+| Overwrite an installed package | No publication; the result is `restart-required` |
+| Enable a bundle | After the selection is saved, before reconciliation |
+| Disable a bundle | With HMR, after reconciliation stops its plugins; without HMR, no publication, and running plugins keep the current table |
+| Remove | After pnpm remove succeeds, inside the HMR transaction |
+| Failed or cancelled install, failed removal | No publication |
+
+`createRuntimeResolution()` returns a `ProfileRuntimeResolution`, which privately keeps the installation anchor, Harness home, and profile directory it was computed from. Its `computeLatestResolution()` rereads that profile with the same inputs and returns a new object for the latest generation, leaving the original unchanged; Workers receive only the table fields. `PluginPackages.refresh()` calls the current resolution's `computeLatestResolution()` and then `replace()`; a resolution constructed as plain data cannot be refreshed and makes the call throw.
+
+Without HMR, deselecting a startup bundle does not stop its plugins. While such a bundle remains deselected, later package operations keep the existing runtime table instead of publishing its removal. Other no-HMR installations and removals of non-running bundles still publish normally.
+
+A successful package operation is not rolled back when publication is rejected afterwards. The result reports the failed runtime application and retains the successful disk changes. Recomputing uses the captured profile directory on disk, not synthetic in-memory layers; a computed resolution without a profile recomputes installation packages only.
+
+### HMR package-configuration expiry
+
+In HMR's change dispatch, a changed file named `package.json` outside `node_modules` goes to `PackageManifests.invalidate()`. A manifest in the host dependency graph still requests a host reload; one loaded as a JSON module still reloads its consumers. A configuration-only manifest schedules no module reload. Configuration-owned paths stay with their dedicated watcher. Source changes in the same batch reload afterwards.
+
+`invalidate(manifest)` records the directory as expired. Afterwards:
+
+- package.json reads, scope lookups, type lookups, and nearest-manifest lookups below that directory read the current file. Ownership follows the real directory when a consumer reaches the package through a link.
+- ESM `ResolveCache` is cleared. Its entries do not record every consulted manifest, and a package entry may resolve outside the package directory.
+- CommonJS `_pathCache` is cleared for the same reason. Unrelated requests recompute their resolution without unloading their modules.
+- CommonJS loads using the default resolver pass the freshly resolved filename to the native loader. Its private request alias cannot select an older entry; cached module instances remain intact.
+
+Configuration invalidation alone leaves loaded modules unchanged. Loader entries retain their raw import results before export normalization. HMR matches imported Node module objects to cached ModuleJob namespaces and reloads the loaded URLs. All matching entry records, including disabled entries, update only after a successful reload and remain unchanged on failure. Stopping and restarting a Loader entry resolves its package name again and selects the new entry.
+
+Entry names are scoped by configuration-tree base URL and retain all distinct imported namespaces. An uninitialized entry contributes the name without erasing loaded namespaces; name-based resolution is used only when none is recorded, or for `cordis:` builtins. Dependency analysis considers every recorded module. Entries sharing a plugin runtime use one replacement operation, while each Loader entry selects its replacement by its original namespace. Module imports and export normalization finish before the old runtime is removed. Failed imports or activation restore the previous modules and plugin implementations and clean up partially activated replacements.
+
+An instance without a Loader entry has no recorded module identity. If a shared runtime's replacement modules have different plugin callbacks, HMR reports an ambiguity error and rolls back instead of assigning that instance to an arbitrary module.
+
+Package invalidation lives in `packages/boot/hmr/src/package-manifest.ts`, which encapsulates its Node internal interfaces. `index.ts` dispatches manifest changes and locates loaded entries by module identity. HMR's `node_modules` exclusion is unchanged.
+
+| Interface | Action |
+|---|---|
+| modules binding `readPackageJSON`, `getPackageScopeConfig`, `getPackageType` | Replaced: paths in an expired directory read the current file; other calls reach the native method |
+| `package_json_reader.getNearestParentPackageJSON` | Replaced: expired directories bypass its JS cache; a lookup without a manifest returns the native absent result |
+| The ESM Loader's `ResolveCache` instance | The prototype `get` is replaced for one lookup to obtain the instance and restored at once; the resolution cache is then cleared |
+| CommonJS `Module._pathCache` | The request-to-filename cache is cleared |
+| CommonJS `Module._load` | Default-resolver requests load by resolved filename; builtins and registered resolve hooks keep the original path |
+
+The binding's `getNearestParentPackageJSON` is called only by `package_json_reader` and is not replaced. Each HMR instance owns a separate configuration cache. Its replacements are installed at the first expiry and restored when the service is disposed, alongside watcher and reload-queue cleanup.
+
+### Future Work
+
+- Online replacement inside `node_modules`, same-path reinstall, changed link targets, and cross-package reload propagation remain unsupported. Package updates need process restart; this does not guarantee that every management result already reports that requirement correctly.
+- TSX versions using an asynchronous loader thread keep that thread's package configuration outside these hooks. Synchronizing it is deferred; this change does not provide general Worker cache synchronization.
+- CommonJS private-request-cache refresh with registered synchronous resolve hooks is deferred. Those requests retain their original loader behavior.
+- Disposing HMR restores the native readers, whose previous cached configuration can become visible again. Preserving invalidation state across HMR replacement is deferred.
+
+## Alternatives considered
+
+**Read current disk on every lookup (#4703).** Resolution follows the disk, but module caches stay and running plugins do not reload. Same-URL contents do not take effect, and different URLs load a second version beside the first in one process. It also maintains its own entry resolver, bypasses custom bare-name hooks, and does not refresh runtime resolution, so GUI-installed private dependencies still cannot be found.
+
+**Reread every observed manifest when runtime resolution publishes (#5496).** This places package-configuration expiry in table publication, decoupled from module caches: overwriting an installed package reports restart, yet the next unrelated publication makes new imports load the new version while the old plugin still runs. Package configuration is content and belongs with module caches, in HMR.
+
+**Let HMR reload packages inside `node_modules`.** It requires finding affected plugins over a module graph that includes `node_modules`, preventing duplicate evaluation of shared libraries and Cordis, and handling missing dynamic-import edges, module side effects, and Workers. It is not done here; those scenarios keep requiring restart.
+
+**Reload every plugin for a package.json change.** Configuration-only manifests do not require module evaluation. Manifests actually imported as JSON modules retain ordinary dependency-driven reloads.
+
+**Re-import reloaded plugins by package name.** It would let an entry rename follow a source reload, but changes `partialReload`'s rule that the loaded URL is the reload unit. Entry renames already take effect when the Loader entry restarts, so this is not changed.
+
+**Keep one namespace per entry name.** Entries with the same name and base URL can have loaded different modules before and after a manifest change. Keeping only the first or last namespace loses a live module; an uninitialized entry must not erase another entry's imported namespace.
+
+## Verification
+
+| Coverage | Location |
+|---|---|
+| A new generation removes profile entries and local names and still rejects retained-entry changes | `packages/boot/app-boot/tests/profile-resolution.spec.ts` |
+| GUI install, deferred enablement, disablement, removal, overwrite, failure, and cancellation, with and without HMR | `packages/boot/plugin-manager/tests/package-reload.spec.ts` |
+| Captured-directory recomputation, computed installation-only refresh, and plain-data rejection | `packages/boot/app-boot/tests/profile-resolution.spec.ts`, `packages/boot/app-boot/tests/profile-resolution-service.spec.ts` |
+| Sequential no-HMR operations, shared dependency declarers, and disk-success/publication-failure outcomes | `packages/boot/plugin-manager/tests/package-reload.spec.ts` |
+| Expired exports, main, imports, type, scope, and nearest manifests; native-reader parity; actual CommonJS loads and retained module instances; the `node_modules` boundary; restoration | `packages/boot/hmr/tests/package-manifest.spec.ts` |
+| Configuration-only manifests, JSON-module and host reloads, source reloads, same-name and shared-runtime entries, import and activation rollback, entry restarts, and the `node_modules` exclusion | `packages/boot/hmr/tests/package-manifest-dispatch.spec.ts` |
+
+Tests need no API key and make no model calls.
+
+## Consequences
+
+- With HMR, supported package operations publish the updated private dependencies and remove unused mappings after plugins stop. Without HMR, a pending startup-bundle disablement defers later publications until restart, preserving running plugins' mappings.
+- In the supported thread, package.json configuration reads use the changed fields; JSON modules retain their own reload behavior. The separate module, loader-thread, and Worker limitations above still apply.
+- Package configuration below expired directories is parsed in JavaScript and must keep the native reader's field and error semantics; tests compare it with the native reader on Node 22, 24, and 26.
+- The implementation depends on several Node internal interfaces, and these tests must run again for Node upgrades.
@@ -0,0 +1,119 @@
+# Agent Note: 包操作刷新 runtime resolution 与 HMR 包配置失效
+
+Status: implemented
+
+[English](2026-09-30-profile-package-refresh-and-manifest-invalidation.md) | 中文
+
+## Problem
+
+Host 运行期间有两处状态没有随变化更新：
+
+- **runtime resolution 只在启动时构造。** GUI 安装或启用 bundle 后，没有人发布最新代，bundle 的私有依赖进不了 profile fallback，它的 bare 插件找不到。停用、卸载后，新一代又不允许移除 profile 范围的条目和本地包名，旧记录和包元数据一直留着。新安装的包目录本身是新的，Node 对它没有旧缓存，缺的只是这张表。
+- **包配置与模块求值使用独立缓存。** 清理插件的模块缓存不会刷新 Node 用于 exports、main、imports 和格式判断的 package.json 字段。package.json 也可以被作为 JSON 模块导入，此时其消费方需要普通的模块重载。
+
+## Decision
+
+### 职责
+
+| 负责方 | 做什么 | 不做什么 |
+|---|---|---|
+| resolver（`app-boot/src/profile-resolution/resolver.ts`） | `replace()` 允许移除 `scope: profile` 条目和 profile 本地包名 | 不碰 Node 的任何缓存 |
+| plugin-manager | 在包操作的确定时点调用 `pluginPackages.refresh()` | 不构造 resolution；不管模块缓存与包配置缓存 |
+| HMR（`packages/boot/hmr`） | 使包配置失效，并保留作为 JSON 模块加载的 manifest 的普通重载 | 不因仅作为配置的 manifest 重载插件；不处理 `node_modules` 包替换 |
+
+### runtime resolution
+
+包身份与 Worker 继承规则由[代际说明](2026-09-09-profile-resolution-generations.zh.md)定义。
+
+`replace()` 对新一代的校验：
+
+- `scope: profile` 的条目可以移除。
+- profile 本地包名可以移除。
+- 保留的 profile 条目保持规范化目录、版本与作用域不变；另一个已选 bundle 提供同一包时，可以更换声明锚点。安装范围的映射与声明锚点保持不变。profile 范围不能变；新本地包名不能覆盖已有条目；已发布的 link 名称不能换真实目录。
+
+### plugin-manager
+
+| 操作 | 发布时点 |
+|---|---|
+| 安装新包 | pnpm 成功、保存 bundle 选择之后，reconciliation 之前；无论是否立即启用都发布 |
+| 覆盖已安装的包 | 不发布，结果为 `restart-required` |
+| 启用 bundle | 保存选择后发布，再做 reconciliation |
+| 停用 bundle | 有 HMR 时，reconciliation 让插件退出后再发布；没有 HMR 时不发布，运行中的插件继续使用原表 |
+| 卸载 | pnpm remove 成功后，在 HMR 事务内发布 |
+| 安装失败、取消、卸载失败 | 不发布 |
+
+`createRuntimeResolution()` 返回 `ProfileRuntimeResolution`，它私有保存构造时的 installAnchor、home 和 profile 目录；`computeLatestResolution()` 用同一组输入重新读取 profile，返回表示最新代的新对象，原实例不变；Worker 只收到表数据。`PluginPackages.refresh()` 调用当前 resolution 的 `computeLatestResolution()` 再 `replace()`；以纯数据构造的 resolution 无法刷新，调用时抛错。
+
+没有 HMR 时，取消启动 bundle 的选择不会停止它的插件。只要该 bundle 仍未选中，后续包操作就保留当前 runtime 表，不发布其移除。其他无 HMR 的安装和未运行 bundle 卸载仍正常发布。
+
+包操作成功后若发布被拒绝，不回滚已完成的包操作。结果报告运行时应用失败，并保留成功的磁盘变更。重新计算使用捕获的磁盘 profile 目录，不继承内存合成 layers；没有 profile 的已计算 resolution 只重算安装范围的包。
+
+### HMR 包配置失效
+
+HMR 的文件变化分派中，文件名为 `package.json` 且不在 `node_modules` 内的变化，交给 `PackageManifests.invalidate()`。位于宿主依赖图中的 manifest 仍请求宿主重载；作为 JSON 模块加载的 manifest 仍重载消费方。仅作为配置的 manifest 不安排模块重载。配置专属路径仍由其独立 watcher 处理。同一批的源码变化随后重载。
+
+`invalidate(manifest)` 把该目录登记为已失效，之后：
+
+- 位于该目录下的 package.json 读取、scope 查询、type 查询、最近 package.json 查询，都按当前磁盘解析。消费方经由链接路径访问时，按真实目录判断归属。
+- 清空 ESM `ResolveCache`。其条目不记录查询过的全部 manifest，包入口也可能解析到包目录之外。
+- 基于相同原因清空 CommonJS `_pathCache`。无关请求重新计算解析结果，不卸载其模块。
+- 使用默认 resolver 的 CommonJS 加载把重新解析的文件名交给原生 loader。其私有请求别名不再选中旧入口，已缓存的模块实例保持不变。
+
+仅使配置失效不会改变已加载模块。Loader entry 保留导出规范化之前的原始导入结果。HMR 将已导入的 Node 模块对象与缓存中 ModuleJob 的模块命名空间按对象身份匹配，重载已加载 URL。所有匹配的 entry 记录，包括已停用的 entry，仅在重载成功后更新，失败时保持不变。停止并重新启动 Loader entry 时，会重新按包名解析并选择新入口。
+
+entry 名称以配置树 base URL 为作用域，并保留所有不同的已导入命名空间。尚未初始化的 entry 只登记名称，不抹去已加载的命名空间；仅在没有记录命名空间或入口为 `cordis:` 内置模块时按名称解析。依赖分析考虑每个已记录模块。共享插件运行时的 entry 使用同一次替换操作，但每个 Loader entry 按自身原命名空间选择替换实现。模块导入与导出规范化在移除旧运行时之前完成。导入或激活失败时，恢复原来的模块和插件实现，并清理已部分激活的替换实例。
+
+没有 Loader entry 的实例不具备已记录的模块身份。如果共享运行时的替换模块具有不同的插件回调，HMR 会报告歧义错误并回滚，而不是将该实例随意分配给某个模块。
+
+包配置失效实现在 `packages/boot/hmr/src/package-manifest.ts`，封装其使用的 Node internal 接口。`index.ts` 分派 manifest 变更，并按模块身份定位已加载 entry。HMR 的 `node_modules` 排除规则不变。
+
+| 接口 | 动作 |
+|---|---|
+| modules binding 的 `readPackageJSON`、`getPackageScopeConfig`、`getPackageType` | 替换：路径位于已失效目录时按当前磁盘解析，其余调用原生方法 |
+| `package_json_reader.getNearestParentPackageJSON` | 替换：已失效目录绕过它的 JS 缓存；没有 manifest 时返回原生的缺失结果 |
+| ESM Loader 的 `ResolveCache` 实例 | 临时替换原型的 `get`，取得实例后立即恢复，再清空解析缓存 |
+| CJS `Module._pathCache` | 清空请求到文件名的缓存 |
+| CJS `Module._load` | 默认 resolver 的请求按解析后的文件名加载；内置模块及注册的 resolve hooks 保留原路径 |
+
+binding 的 `getNearestParentPackageJSON` 只被 `package_json_reader` 自己调用，不替换。每个 HMR 实例拥有独立的配置缓存，在第一次失效时安装 hook，并在服务销毁时恢复，同时清理 watcher 和重载队列。
+
+### 后续工作
+
+- 不支持 `node_modules` 内在线替换、同路径重装、link 换目标及跨包重载传播。包更新需要重启进程；这不保证每个管理操作的结果都已正确报告这一要求。
+- 使用异步 loader 线程的 TSX 版本，其线程内包配置不受这些 hook 管理。线程同步留待后续；本次不提供通用 Worker 缓存同步。
+- 注册了同步 resolve hooks 时，CommonJS 私有请求缓存刷新留待后续；这些请求保留原有 loader 行为。
+- 销毁 HMR 会恢复原生 reader，其此前缓存的配置可能重新可见。跨 HMR 替换保留失效状态留待后续。
+
+## Alternatives considered
+
+**每次查找都读当前磁盘（#4703）。** 解析能跟上磁盘，但不清模块缓存，也不重载运行中的插件。同一 URL 时新内容不生效，不同 URL 时新旧版本在同一进程并存。它还要维护一份入口解析实现，并且绕过自定义 bare-name hook。它也没有刷新 runtime resolution，GUI 安装的私有依赖依然找不到。
+
+**在 runtime resolution 发布时全量重读已见过的 manifest（#5496）。** 它把包配置失效放进了绑定表发布，和模块缓存脱了钩：覆盖已安装的包时报需要重启，但下一次无关的发布会让新导入拿到新版本，旧插件仍在运行。包配置缓存属于内容，应该和模块缓存由同一方负责，也就是 HMR。
+
+**让 HMR 支持 `node_modules` 内的包重载。** 这需要沿包含 `node_modules` 的模块图确定受影响插件，防止共享库和 Cordis 被重复求值，还要处理动态 import 漏边、模块副作用和 Worker。本次不做，这些场景继续要求重启。
+
+**package.json 变化时重载所有插件。** 仅作为配置的 manifest 不要求模块求值。实际作为 JSON 模块导入的 manifest 保留普通的依赖驱动重载。
+
+**按插件名重新 import 被重载的插件。** 这能让入口改名随源码重载生效，但会改变 `partialReload` 以已加载 URL 为重载单位的规则。入口改名在 Loader entry 重启时已经生效，所以本次不改。
+
+**每个 entry 名称只保留一个命名空间。** 名称和 base URL 相同的 entry，可能在 manifest 变化前后加载了不同模块。只保留最早或最后一个命名空间会遗漏仍在使用的模块；尚未初始化的 entry 也不能抹去其他 entry 的已导入命名空间。
+
+## Verification
+
+| 覆盖面 | 位置 |
+|---|---|
+| 新一代可移除 profile 条目与本地包名、仍拒绝修改保留条目 | `packages/boot/app-boot/tests/profile-resolution.spec.ts` |
+| GUI 安装、延迟启用、停用、卸载、覆盖、失败、取消，有无 HMR | `packages/boot/plugin-manager/tests/package-reload.spec.ts` |
+| 捕获目录后的重新计算、无 profile 的已计算 resolution 刷新、纯数据拒绝 | `packages/boot/app-boot/tests/profile-resolution.spec.ts`、`packages/boot/app-boot/tests/profile-resolution-service.spec.ts` |
+| 无 HMR 连续操作、共享依赖声明来源、磁盘成功但发布失败 | `packages/boot/plugin-manager/tests/package-reload.spec.ts` |
+| 失效后的 exports、main、imports、type、scope、最近 package.json，原生 reader 对照，实际 CommonJS 加载及旧模块实例保留，node_modules 边界，恢复 | `packages/boot/hmr/tests/package-manifest.spec.ts` |
+| 配置专用 manifest、JSON 模块与宿主重载、源码重载、同名及共享运行时的 entry、导入与激活失败回滚、entry 重启和 node_modules 排除规则 | `packages/boot/hmr/tests/package-manifest-dispatch.spec.ts` |
+
+测试不需要 API key，不调用模型。
+
+## Consequences
+
+- 有 HMR 时，支持的包操作发布更新后的私有依赖，并在插件停止后移除不再需要的映射。没有 HMR 时，待生效的启动 bundle 停用会将后续发布延迟到重启，保留运行中插件的映射。
+- 在支持的线程内，package.json 配置读取使用更新后的字段；JSON 模块保留自己的重载行为。上述模块、loader 线程及 Worker 的独立限制仍然适用。
+- 包配置读取改由 JS 解析 package.json，需要与原生读取保持字段和错误语义一致；测试在 Node 22、24、26 上与原生读取逐项比较。
+- 依赖多个 Node internal 接口，Node 升级时需要重跑这些测试。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-05-anonymous-reasoning-translation.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-05-anonymous-reasoning-translation.md
+/agent-note-anonymous-translation-remains-separate-from-model-history:
+  en: ab8fee99b1f6d828
+  zh: 0e324a42eebc1403
+/agent-note-anonymous-translation-remains-separate-from-model-history/problem:
+  en: 5e10347fa87f98b5
+  zh: cf3569631af8d66f
+/agent-note-anonymous-translation-remains-separate-from-model-history/decision:
+  en: f13c134f53ed63c9
+  zh: 868aacd453d26c82
+/agent-note-anonymous-translation-remains-separate-from-model-history/alternatives-considered:
+  en: 083d50f8564b0378
+  zh: 50af332e64ad06f3
+/agent-note-anonymous-translation-remains-separate-from-model-history/consequences:
+  en: 57c774c6fb14a1b4
+  zh: 5a05393e6f1d25b1
@@ -0,0 +1,31 @@
+# Agent Note: Anonymous translation remains separate from model history
+
+Status: implemented
+
+English | [中文](2026-10-05-anonymous-reasoning-translation.zh.md)
+
+## Problem
+
+Readers need reasoning in their chosen language without another model credential or replacement of the original assistant output. Translation needs an owner for external requests, cancellation, and failures independent of Agent execution.
+
+## Decision
+
+The experimental translator owns explicit Google or Bing routing, provider-language normalization, and bounded network requests. Its Service Definition and both providers share one package because their current consumers use the same operation and lifetime. The optional GUI consumer owns settings, paragraph scheduling, per-disclosure caches, and translated display. Its authenticated Remote calls the translator; the agent loop and Session event types remain independent.
+
+Bing is the configured default. Enabling the bundle permits transmission of expanded reasoning to the chosen service, disclosed in plugin metadata and settings. Failure never selects another provider. Original remains available; translated text neither replaces persisted assistant output nor enters model input. The [optional-bundle admission policy](2026-09-21-experimental-capabilities-as-optional-bundles.md) keeps the feature disabled until selected.
+
+The reasoning-body chain carries original text and streaming status. Native Chat owns its original Markdown fallback; consumers do not replace the assistant renderer or alter Session projection. Only expanded bodies start translation. Collapsing, changing selection, or unloading aborts outstanding work and excludes late results.
+
+## Alternatives considered
+
+**Translate through the conversation's LLM provider.** This adds model requests and depends on model credentials, pricing, and routing. Anonymous translation has separate availability and requires none of those credentials.
+
+**Rewrite reasoning in the Session or provider stream.** This changes the original trajectory and can affect model reasoning passback. Display translation preserves the original model history.
+
+**Silently try another endpoint after failure.** This sends potentially private text to another operator without an explicit selection. Retry uses the same provider; switching providers is a user action.
+
+## Consequences
+
+Anonymous translation adds no third-party translation library or model-token usage. Anonymous endpoints provide no developer availability guarantee. Both providers send source text in POST request bodies. Translations may alter Markdown or code formatting and do not translate collapsed summaries.
+
+The translator retains Session-bound results under the [shared machine-translation persistence decision](2026-10-05-persistent-machine-translation.md); its stateless calls do not record results.
@@ -0,0 +1,31 @@
+# Agent Note: 免登录翻译独立于模型历史
+
+Status: implemented
+
+[English](2026-10-05-anonymous-reasoning-translation.md) | 中文
+
+## 问题
+
+读者需要用指定语言阅读思考内容，同时无需额外模型凭据，也不替换原始 assistant 输出。翻译需要独立于 Agent 执行的所有者，负责外部请求、取消与失败。
+
+## 决策
+
+实验性 translator 负责显式 Google 或 Bing 路由、Provider 语言标签映射及有界网络请求。Service Definition 与两种 Provider 共用一个包，因为当前消费者使用相同操作与生命周期。可选 GUI 消费者负责设置、段落调度、展开组件内缓存及译文展示。其经过身份验证的 Remote 调用 translator；agent loop 与 Session 事件类型保持独立。
+
+配置的默认服务为 Bing。启用 Bundle 允许将展开的思考内容发送给所选服务，插件元数据与设置公开说明接收方。失败时不选择其他 Provider。原文始终可访问；译文不替换持久化 assistant 输出，也不进入模型输入。[可选 Bundle 准入规则](2026-09-21-experimental-capabilities-as-optional-bundles.zh.md) 保证功能在显式选择前保持关闭。
+
+reasoning-body chain 传递原始文本与流式状态。原生 Chat 负责原始 Markdown fallback；消费者不替换 assistant 渲染器，也不改变 Session projection。只有展开内容才开始翻译。折叠、切换设置或卸载都会中止未完成工作并忽略迟到结果。
+
+## 考虑过的替代方案
+
+**通过对话使用的 LLM Provider 翻译。** 这会增加模型请求，并依赖模型凭据、定价与路由。免登录翻译有独立的可用性，且无需这些凭据。
+
+**重写 Session 或 Provider 流中的思考内容。** 这会改变原始轨迹，并可能影响思考内容回传。展示翻译保留原始模型历史。
+
+**失败后静默尝试另一端点。** 这会在没有显式选择的情况下将潜在私有文本发送给另一个运营方。重试使用同一 Provider；切换 Provider 是用户操作。
+
+## 后果
+
+匿名翻译不增加第三方翻译库或模型 token 消耗。免登录端点不保证开发者可用性。两种服务均通过 POST 请求体发送原文。译文可能改变 Markdown 或代码格式，也不翻译折叠摘要。
+
+translator 按[统一的机器翻译持久化决策](2026-10-05-persistent-machine-translation.zh.md)保留绑定 Session 的结果；无状态调用不记录结果。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-05-official-on-demand-bundles.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-05-official-on-demand-bundles.md
+/agent-note-discover-official-bundles-without-installing-their-runtimes:
+  en: 1f2387f10628638b
+  zh: c835a8ee615e9da6
+/agent-note-discover-official-bundles-without-installing-their-runtimes/problem:
+  en: a590bcef6c9760c0
+  zh: 19e6f61c2c7d8d3b
+/agent-note-discover-official-bundles-without-installing-their-runtimes/decision:
+  en: 31e3c52841f31a11
+  zh: ac2ad6e54ef9e150
+/agent-note-discover-official-bundles-without-installing-their-runtimes/alternatives-considered:
+  en: 42cb0f808a145871
+  zh: 225012615d1ecdf5
+/agent-note-discover-official-bundles-without-installing-their-runtimes/consequences:
+  en: 899b07d90024e019
+  zh: 01d22ac4b2444feb