Merge remote-tracking branch 'origin/master' into xtr/trajectory-virtual-scroll

# Conflicts: # docs/core-data-structures/session.i18n.yaml # packages/client/ui-trajectory/README.i18n.yaml # packages/client/ui-trajectory/README.zh.md # packages/core/session/README.i18n.yaml # packages/core/session/README.zh.md
2026-08-05 15:41:04 +08:00
parent afb6ee2c9b e4d5ec548e
commit a00b11be76
1305 changed files with 8237 additions and 4447 deletions
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/README.md
 README.md: 63ca0f7711c2c9deb193d5a9a574ff909a04602e
-README.zh.md: a217868f6c25ddce690ca32fc09b1d68b8ab48d2
+README.zh.md: d4c1a85ef7dd33be5419245464d83da24756443a
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-会话日志、系统提示词组装、工具注册表、agent（智能体）词汇，以及构成 harness 默认控制主干的具体循环。这些是 **产品** 包（package），插件和消费方以其稳定接口为基础构建。
+会话日志、系统提示词组装、工具注册表、agent（智能体）词汇，以及构成 harness 默认控制主干的具体循环。这些是 **产品** 包，插件和消费方以其稳定接口为基础构建。

 | 包 | 角色 | ctx 键 |
 |---|---|---|
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent-loop/README.md
 README.md: 2ce85071c4b7408adb4ee05291c499ec642be114
-README.zh.md: bc78c02fc046f3bb5820f89bae5a90b26b5a8ced
+README.zh.md: d0ef7f3d9bf3a2fe297171c4015f8500210e0155
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -2,15 +2,15 @@

 [English](README.md) | 中文

-唯一的实体 agent（智能体）插件与循环驱动器。其包（package）内部实现满足 `Agent` 接口，并驱动会话／轮次／步骤生命周期。
+唯一的具体 agent（智能体）插件与循环驱动器。其包内部实现满足 `Agent` 接口，并驱动会话／轮次／步骤生命周期。

-这是 harness 中唯一包含实体循环逻辑的包。其他所有内容要么是抽象服务，要么是针对扩展 seam 的插件：新行为应放入插件，而不是这里。
+这是 harness 中唯一包含具体循环逻辑的包。其他所有内容要么是抽象服务，要么是针对扩展 seam 的插件：新行为应放入插件，而不是这里。

 ## 服务：`AgentLoop`（ctx 键：`agentLoop`）

 ### 公开 API

-创建与恢复属于同一个受回滚保护的事务：构造私有会话、实体 agent 和带作用域的上下文；等待可选 setup；同步调用其可选的发布提交；进入两个注册表；依次宣告 `session/created` 和 `agent/created`；发出 `agent/session-start`；此后才启动驱动器。Setup 接收完整的带作用域 `Context`，作为受信任的同进程组合代码，并且不得驱动尚未发布的 agent。其可选提交会在所有 setup 的 await 均结算后、进入注册表之前立即重新校验可变的配置状态；若其抛出异常，则回滚私有事务且不发布任何一个 id。普通的类型化身份与选项输入遵循只读契约以借用方式传入；seed 事件与会话元数据会跨越持久会话边界，因此系统会验证并快照它们。可选的 `AbortSignal` 只取消加载／setup／发布，并在返回的 handle 可见前分离。
+创建与恢复属于同一个受回滚保护的事务：构造私有会话、具体 agent 和带作用域的上下文；等待可选 setup；同步调用其可选的发布提交；进入两个注册表；依次宣告 `session/created` 和 `agent/created`；发出 `agent/session-start`；此后才启动驱动器。Setup 接收完整的带作用域 `Context`，作为受信任的同进程组合代码，并且不得驱动尚未发布的 agent。其可选提交会在所有 setup 的 await 均结算后、进入注册表之前立即重新校验可变的配置状态；若其抛出异常，则回滚私有事务且不发布任何一个 id。普通的类型化身份与选项输入遵循只读契约以借用方式传入；seed 事件与会话元数据会跨越持久会话边界，因此系统会验证并快照它们。可选的 `AbortSignal` 只取消加载／setup／发布，并在返回的 handle 可见前分离。

 调用方 fiber 与 AgentLoop 提供方共同拥有 agent。`AgentFactory.createAgent(ownerCtx, options)` 与 `resume(ownerCtx, options)` 显式接收调用方所有权，而工厂为 `sessions`/`llm`/`tools`/`systemPrompt` 保留自身的依赖上下文；这样，调用方可以只注入 `agents`，而不会缩减新 agent 的服务接口。调用方卸载、handle dispose（资源释放）或提供方卸载都会汇合到同一个记忆化的完全停稳边界。提供方关闭会同时等待资源 teardown，以及已经观测到停用的公开 create/resume 包装层，因此依赖消失后，任何 continuation 都无法继续发布。

@@ -51,25 +51,25 @@ interface Config {

 通过配置创建的 agent 会自动启动。模型调用同时需要 `provider` 和 `model`；`agent/request` 可以在分发前补齐缺失的这一对值。可选的正数 `maxTokens` 会为每次对话请求提供初始输出上限，并记录在请求 header 中。`maxParallelToolCalls` 限制每个 agent 针对并行安全调用使用的滚动池，默认值为 `10`。`cwd` 仅应用于全新会话，而 `resumeSessionId` 保留持久化元数据。通过配置创建的 agent 使用部署 persona；编程式 setup 可以按 agent 遮蔽它。该插件为每个 agent 提供 `provider`、`model` 和 `cwd` 提示词变量；harness 身份与部署 persona 属于 `dsh-system-prompt`。

-### 包内部实体驱动器
+### 包内部具体驱动器

-实体 `ReactLoopAgent`、其排队输入、outbox 与运行控制均为包内部实现。包根只导出插件／服务／配置契约，包导出映射不提供 `./src/*` 逃逸路径；生命周期拥有方通过 `ctx.agents` 创建 agent，而不是点名、构造或启动驱动器内部组件。一个准备完成的会话只能由一个实体驱动器认领；所有可观测行为都通过会话事件和 `agent/*` 事件分类体系发生。
+具体 `ReactLoopAgent`、其排队输入、outbox 与运行控制均为包内部实现。包根只导出插件／服务／配置契约，包导出映射不提供 `./src/*` 逃逸路径；生命周期拥有方通过 `ctx.agents` 创建 agent，而不是点名、构造或启动驱动器内部组件。一个准备完成的会话只能由一个具体驱动器认领；所有可观测行为都通过会话事件和 `agent/*` 事件分类体系发生。

 统一的 `send()` 原语按（`target` × `wakeup`）路由内容与来源；`followup`/`steer`/`inject` 是它的固定预设别名。`next-turn` 项加入排队 FIFO，除非 `wakeup: false`，否则会唤醒驱动器；接纳发生在任何轮次开启之前。`reserveTurnAdmission()` 可以为独立持久操作同步保留该空闲边界：已获接纳的唤醒工作拥有优先权，之后发送的项保留普通队列身份与 FIFO 位置，释放会重新启用同一驱动器路径，`whenIdle()` 会等待预留结束，但 teardown 不会等待它。循环在 `agent/prompt-submit` 之前打开一个私有的 next-step 接收窗口，并在 `turn/end` 之前关闭它。在该窗口内，`steer()` 与 `inject()` 会暂存到同一个 outbox；接纳获准后会开启轮次，记录提示词及其返回的 `additionalContexts`，再于首次请求前排空暂存输入。接纳被阻止或失败时，不会写入提示词或钩子生成的上下文。之后，仅含调用方暂存上下文的批次会采用空闲注入的立即追加行为，而 steering（中途引导）及与其一同暂存的上下文则继续待处理，以供重试或之后获准的提示词使用。窗口之外，steering 会成为唤醒驱动器的排队提示词，而注入会立即追加 `user/message`，不开启轮次也不运行模型。

-`steer()` 会把一次性准入回执附着到其准确的已接收消息。`agent/step` 和异步提示词组装成功后，循环把稳定的待处理批次提交为 `steering/message`、捕获派生历史并开启 `step/start`；只有此时，每个回执才会解析为 `admitted`，并附带轮次与步骤。之后到达的消息继续待处理。空闲 steering 会进入普通 FIFO，并以其最终轮次的首次请求作为相同准入边界。结束轮次的工具结果、广义取消、dispose（资源释放），或已领取 idle-steering 消息却从未到达请求的轮次，会把受影响回执解析为 `rejected`；`cancel(..., { keepInbox: true })` 和非终止型路由会保留待处理投递。活跃轮次内的 `inject()` 仍会在所有工具结果后提交，包括被中断批次中已最终确认的上下文；steering 则保持待准入，直到请求接纳它。
+`steer()` 会把一次性准入回执附着到其准确的已接收消息。`agent/step` 和异步提示词组装成功后，循环把稳定的待处理批次提交为 `steering/message`、为派生历史创建快照并开启 `step/start`；只有此时，每个回执才会解析为 `admitted`，并附带轮次与步骤。之后到达的消息继续待处理。空闲 steering 会进入普通 FIFO，并以其最终轮次的首次请求作为相同准入边界。结束轮次的工具结果、广义取消、dispose，或已领取 idle-steering 消息却从未到达请求的轮次，会把受影响回执解析为 `rejected`；`cancel(..., { keepInbox: true })` 和非终止型路由会保留待处理投递。活跃轮次内的 `inject()` 仍会在所有工具结果后提交，包括被中断批次中已最终确认的上下文；steering 则保持待准入，直到请求接纳它。

 每次 FIFO 接受项时都会铸造一个 `InboxItemId`，并通过 `agent/inbox/enqueue` 发布完整的单次入队项。`updateInbox()` 持有同步 queued 项边界：编辑会冻结替换内容，但不改变消息标识或位置；移除会发布 discard；严格 steering 会把不可变消息作为新的 steering 单次入队项转移到开放的 next-step 窗口。窗口关闭时返回 `steer-unavailable`，且不做任何变更；待处理 steering 和已被认领的项会返回 `not-found`。认领操作会发布 `agent/inbox/dequeue`，并在提示词接纳前不可逆地移除实时寻址标识，因此竞态中的更新无法改写持久历史；`cancel()` 在不带 `keepInbox` 时会发布 `agent/inbox/discard`。

 ### 循环生命周期（`agent.ts`）

-驱动器在其整个生命周期内拥有一个 agent，并在 `ctx.agents.withInitiator(agent, ...)` 内运行。包私有的编排入口点会恢复确切的 Agent，一次性派生 `agent.session`，并让操作局部的辅助函数捕获它，而不是通过浅层接口继续传递实体驱动器或每次操作的 `Session`。如果显式 `Session` 正是辅助函数的实际接口，该辅助函数会保留它；创建、持久化加载、未发布 setup、服务、worker、进程、持久化和 wire 协议则继续保留各自的显式身份。[agent 服务](../agent/README.md#initiating-agent-scope)规定传播、teardown 和分离工作规则。
+驱动器在其整个生命周期内拥有一个 agent，并在 `ctx.agents.withInitiator(agent, ...)` 内运行。包私有的编排入口点会恢复确切的 Agent，一次性派生 `agent.session`，并让操作局部的辅助函数捕获它，而不是通过浅层接口继续传递具体驱动器或每次操作的 `Session`。如果显式 `Session` 正是辅助函数的实际接口，该辅助函数会保留它；创建、持久化加载、未发布 setup、服务、worker、进程、持久化和 wire 协议则继续保留各自的显式身份。[agent 服务](../agent/README.md#initiating-agent-scope)规定传播、teardown 和分离工作规则。

 每次提供方调用成功结束时，都会恰好追加一个 `assistant/message` 完成锚点，包括无内容调用和以 `max-tokens` 结束的调用。该锚点原样记录组装后的内容，保留确切的分片溯源（流没有分片时为 `[]`），并在用量可用时包含用量；空内容不会进入派生消息历史。

 在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会应用同一来源规则。

-插件失败会结束当前轮次，而不是结束循环。只有最终适配器分发／迭代失败以及带内的终止错误或中止结束才进入 `agent/request-error`；中间件、结果处理、工具及其他扩展失败会直接关闭轮次。失败步骤关闭后，恢复逻辑会接收确切的实时错误、不可变的提供方事实、不可变的先前失败、为请求提供服务的适配器注册所对应的不可变重试策略，以及轮次信号；如果没有最终适配器为其提供服务，则该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；循环用其错误关闭失败轮次，并在不插入空闲通知的情况下开启一个编号重试轮次。成功会清除连续失败历史；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)规定生命周期与竞态契约。
+插件失败会结束当前轮次，而不是结束循环。只有最终适配器分发／迭代失败以及带内的终止错误或中止结束才进入 `agent/request-error`；中间件、结果处理、工具及其他扩展失败会直接关闭轮次。失败步骤关闭后，恢复逻辑会接收确切的实时错误、不可变的提供方事实、不可变的先前失败、为请求提供服务的适配器注册所对应的不可变重试策略，以及轮次信号；如果没有最终适配器为其提供服务，则该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；循环用其错误关闭失败轮次，并在不插入空闲通知的情况下开启一个编号重试轮次。成功会清除连续失败历史；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose 则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)规定生命周期与竞态契约。

 在步骤内，独占调用形成屏障；并行安全调用使用有界滚动池，并在启动前重新分类。只有分发／主体会重叠。策略、持久结果和结果上下文仍保持模型顺序。中止会停止新调用，drain 已启动的结果，并保留其已定案的结果上下文，不区分取消原因。内部调度器故障会停止新的分发，等待已启动的分发，然后在不虚构工具结果的情况下到达轮次错误边界。

@@ -126,7 +126,7 @@ interface Config {

 #### KV Cache 影响

-仅追加；每个合成结果都位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+仅追加；每个合成结果都位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。

 ## 已知限制与暂缓事项

--- a/packages/core/agent-loop/package.json
+++ b/packages/core/agent-loop/package.json
@@ -20,9 +20,7 @@
  "files": [
    "lib/index.js",
    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -14,6 +14,7 @@ import type {
  AgentFactory,
  AgentHandle,
  AgentOptions,
+  AgentSetup,
  CreateAgentOptions,
  ResumeAgentOptions,
  SessionStartSource,
@@ -555,23 +556,40 @@ export class AgentLoop extends Service implements AgentFactory {
      ...options.seed === undefined ? {} : { seed: options.seed },
      ...options.meta === undefined ? {} : { meta: options.meta },
    })
-    const prepared = this.prepare(ownerCtx, options.sessionId, options.agentOptions ?? {}, session, options.signal)
-    const published = (async () => {
-      try {
-        const setupCommit = await raceAbort(
-          options.setup?.(prepared.agent.ctx), prepared.signal, options.sessionId,
-        )
-        setupCommit?.commit()
-        return prepared.publish('startup')
-      } catch (error: unknown) {
-        await prepared.dispose()
-        throw error
-      }
-    })()
+    const published = this.setupAndPublish(
+      ownerCtx,
+      options.sessionId,
+      session,
+      options.agentOptions ?? {},
+      options.setup,
+      options.signal,
+      'startup',
+    )
    this.ownership.trackWrapper(published)
    return published
  }

+  /** Prepare one Agent around an acquired Session, run setup, and publish it. */
+  private async setupAndPublish(
+    ownerCtx: Context,
+    id: SessionId,
+    session: Session,
+    agentOptions: AgentOptions,
+    setup: AgentSetup | undefined,
+    signal: AbortSignal | undefined,
+    source: SessionStartSource,
+  ): Promise<AgentHandle> {
+    const prepared = this.prepare(ownerCtx, id, agentOptions, session, signal)
+    try {
+      const setupCommit = await raceAbort(setup?.(prepared.agent.ctx), prepared.signal, id)
+      setupCommit?.commit()
+      return prepared.publish(source)
+    } catch (error: unknown) {
+      await prepared.dispose()
+      throw error
+    }
+  }
+
  /**
   * Resume an owned agent from the configured persistence service.
   * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
--- a/packages/core/agent-loop/src/invariant.ts
+++ b/packages/core/agent-loop/src/invariant.ts
@@ -44,7 +44,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
    if (header === undefined) {
      return fail('a loop-built request with no request/header event in its session log')
    }
-    const rebuilt = new Session(
+    const rebuilt = Session.create(
      SessionId(`${String(session.id)}-invariant-rebuild`),
      structuredClone(events.slice(0, boundary)),
    )
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -203,7 +203,7 @@ describe('addressable inbox operations', () => {

  it('keeps a queued occurrence when the next-step window is closed', () => {
    const ctx = new Context()
-    const session = new Session(SessionId('queue-to-steer-closed'))
+    const session = Session.create(SessionId('queue-to-steer-closed'))
    const agent = new ReactLoopAgent(ctx, session.id, {}, session)
    const enqueued: InboxItem[] = []
    const discarded: InboxItem[] = []
@@ -772,7 +772,7 @@ describe('turn numbering continues across seeded sessions', () => {

 describe('discriminated SessionEvent narrows without casts', () => {
  it('narrows event.data from event.type', () => {
-    const session = new Session(SessionId('s'))
+    const session = Session.create(SessionId('s'))
    const appended: SessionEvent = session.append('tool/call', {
      turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}',
    })
--- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts
+++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts
@@ -597,7 +597,7 @@ describe('request stability across the loop', () => {
      const stepStart = stepStarts[index]!
      // Messages: the derivation over the log prefix strictly before this
      // step's step/start — rebuilt here through a completely fresh Session.
-      const rebuilt = new Session(SessionId(`rebuild-${index}`), structuredClone(events.slice(0, stepStart.seq)))
+      const rebuilt = Session.create(SessionId(`rebuild-${index}`), structuredClone(events.slice(0, stepStart.seq)))
      expect(structuredClone(request.messages)).toEqual(rebuilt.deriveMessages())

      // Header: the latest request/header snapshot up to this step's dispatch
--- a/packages/core/agent-loop/tests/resume.spec.ts
+++ b/packages/core/agent-loop/tests/resume.spec.ts
@@ -625,7 +625,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
    expect(a2.session.events.length).toBe(events1.length + 1)
    expect(a2.session.firstLiveSeq).toBe(events1.length)
    expect(a2.session.events.at(-1)?.type).toBe('session/end-seed')
-    const replay = new Session(SessionId('replay'), events1)
+    const replay = Session.create(SessionId('replay'), events1)
    expect(a2.session.deriveMessages()).toEqual(replay.deriveMessages())

    // …and a new turn continues numbering (turn 2) with contiguous seqs.
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent/README.md
 README.md: 98421aa6de3d6778702665854ed723507e933028
-README.zh.md: bfc8d68a9656a29a809de0848986e4ee9eb3fe7c
+README.zh.md: 287a0feddba5c1092aab17e361b9382a52179b63
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -4,7 +4,7 @@

 Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事件词汇。每个插件（UI、钩子、编排器）都面向此处定义的 `Agent` handle 编程；它不依赖循环，因此循环可以替换。

-可选配套包（package）`@deepseek-ai/dsh-agent/invariant` 会向 `ctx.invariants` 注册此包的 agent（智能体）状态转换检查。根 agent 服务不会隐式加载诊断。
+可选配套包`@deepseek-ai/dsh-agent/invariant`会向 `ctx.invariants` 注册此包的 agent（智能体）状态转换检查。根 agent 服务不会隐式加载诊断。

 ## 服务：`AgentRegistry`（ctx 键：`agents`）

@@ -14,7 +14,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事

 带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installAgentLlmTarget(agentCtx, target)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将路由应用到提示词变量，并将完整目标应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使该目标使用适配器／提供方默认值。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 可以返回一个 `AgentSetupCommit`；所有 setup 的 await 均结算后，工厂会在进入注册表前立即调用其同步 `commit()`，若其抛出异常，则回滚私有事务且不发布任何一个 id。Setup 仍是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。

-`AgentOptions` 提供初始的提供方／模型路由，以及可选的正数 `maxTokens` 输出上限。实体循环会解析确切模型的适配器默认值，把生效上限记录到请求 header，并应用到每次对话模型请求；显式 Agent 选项优先，省略时由适配器或提供方路由默认值控制。
+`AgentOptions` 提供初始的提供方／模型路由，以及可选的正数 `maxTokens` 输出上限。具体循环会解析确切模型的适配器默认值，把生效上限记录到请求 header，并应用到每次对话模型请求；显式 Agent 选项优先，省略时由适配器或提供方路由默认值控制。

 - `ctx.agents.register(agent: Agent): () => void`：记录一个 **已经构造完成** 的 agent。随调用 fiber dispose。
 - 高级有序生命周期：`enter(agent, owner): () => void` 强制 `agent.id === agent.session.id`，执行权威 ID 冲突检查，并在不通知的情况下插入；`owner` 显式记录实时创建方 agent 关系（根 agent 为 `undefined`），与持久会话谱系无关。`announce(agent)` 恰好发出一次 `agent/created`。创建监听器同步请求的 detach 会延后到该次分发结束；每次 detach 都会检查捕获的条目对象，因此陈旧能力无法删除后续使用同一 ID 的替代项。异步工厂使用这一拆分；普通插件使用 `register()`。
@@ -36,7 +36,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事

 #### 工厂 seam（创建）

-Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，并通过 `setFactory` 注册。这样，创建功能留在 `dsh-agent` 接口上，消费方（UI、ACP 桥接层）可以面向 `ctx.agents` 编程，而不依赖具体循环包。注册表会把已经 traced 的 Service 规范化为具体目标，并通过调用方上下文重新 trace 每次调用；这既避免嵌套 Cordis shadow，也会把显式、绑定调用方的 `ownerCtx` 传给普通工厂。
+Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，并通过 `setFactory` 注册。这样，创建功能留在 `dsh-agent` 接口上，消费方（UI、ACP（Agent Client Protocol）桥接层）可以面向 `ctx.agents` 编程，而不依赖具体循环包。注册表会把已经 traced 的 Service 规范化为具体目标，并通过调用方上下文重新 trace 每次调用；这既避免嵌套 Cordis shadow，也会把显式、绑定调用方的 `ownerCtx` 传给普通工厂。

 - `ctx.agents.setFactory(factory: AgentFactory): () => void`：注册创建工厂（循环在构造时调用）。第二个工厂会导致抛出；dispose 时清空槽位。
 - `ctx.agents.create(options: CreateAgentOptions): Promise<AgentHandle>`：创建会话和 agent，在不发布的情况下等待可选 setup，调用其可选的同步提交，然后通过最终的 `SessionStore.enter()` 与 `AgentRegistry.enter()` 检查发布。不支持并发创建同一 ID：多个操作可以进行准备，但只有一个能进入；每个失败方都会回滚其私有作用域／会话／驱动器。可选且只用于创建的 `signal` 会取消未发布的 setup，并在返回 handle 前分离；之后的取消使用 `handle.dispose()` 或 `agent.cancel()`。发布包含在回滚范围内，回滚期间每条已交付创建边都会成对处理。未注册工厂时拒绝。
@@ -50,7 +50,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，

 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。

-大多数拦截点都是协作式 waterfall（瀑布式事件）。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧邻 waterfall 最终的 `next`；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：失败步骤关闭后，它接收确切错误、规范化失败事实和信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`；循环会关闭失败轮次，并打开一个编号重试轮次。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。有效的广义取消会先发出只观测的 `agent/cancel-requested` 及其解析后的类型化原因，再清空队列并中止；通知失败会被收容，不能 veto 停止。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
+大多数拦截点都是协作式 waterfall（瀑布式事件）。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧接在 waterfall 最终的 `next` 之前；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：失败步骤关闭后，它接收确切错误、规范化失败事实和信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`；循环会关闭失败轮次，并打开一个编号重试轮次。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。有效的广义取消会先发出只观测的 `agent/cancel-requested` 及其解析后的类型化原因，再清空队列并中止；通知失败会被收容，不能 veto 停止。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域运行时设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。

 `PromptDecision.additionalContexts` 是由带标识且冻结的 `UserMessage` 值组成的数组，因此每个上下文都保留自己的标识和来源。获准的提示词与每个附加上下文都会在轮次运行前成为各自独立、面向模型的 `user/message` 事件。包装下游允许决策的监听器会保留其 `content` 与 `additionalContexts`，除非有意替换任一字段；替换获准内容时仍会保留提示词的标识。

@@ -64,7 +64,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 - `agent.reserveTurnAdmission()`：在任何已排队唤醒提示词认领其轮次之前，同步预留空闲边界。已获接纳的提示词拥有优先权，包括同一 tick 内仍在等待唤醒的项，此时预留返回 `undefined`。预留期间，之后发送的项保留其普通 ID、FIFO 位置与唤醒信息；`acceptsNextStep` 保持 false，`inject()` 不受阻塞，`whenIdle()` 将该预留计为活动，返回的释放函数可幂等调用。这项范围有限的协调能力使手动压缩（compaction）等独立持久操作能够在排队提示词从会话派生内容前完成并 flush。
 - `agent.updateInbox(itemId, action)`：同步编辑、移除一个仍处于待处理状态的 queued 入队项，或对其执行严格 steering。编辑会替换已冻结的内容，同时保留其 `MessageId`、`InboxItemId`、来源与 FIFO 位置；移除会发出该项的终态 discard。严格 steering 要求 `acceptsNextStep` 为 true；它会结束 queued 单次入队项，并把同一条不可变消息接受为新的 steering 单次入队项，后者使用新的 `InboxItemId`。窗口关闭时返回 `steer-unavailable`，且不做任何变更。待处理 steering 和已被认领的项会返回 `not-found`。
 - `agent.followup(input)`：`send()` 的 `next-turn`／wakeup 预设：排队一个普通后续轮次并唤醒驱动器。
- `agent.steer(input)`：`next-step`／wakeup 预设：提交一条已有标识的消息，并取得其 `SteeringReceipt`。提示词接纳期间或轮次打开时，消息会为下一个安全请求边界暂存，且不分发 `agent/prompt-submit`；该接收窗口之外则成为会唤醒驱动器的排队提示词。只有循环记录消息、将其捕获到不可变请求历史并提交 `step/start` 后，`receipt.outcome` 才会解析为 `admitted`，并附带轮次与步骤。结束轮次的工具结果、广义取消、dispose（资源释放）或准入前故障会使其解析为 `rejected`；`cancel(..., { keepInbox: true })` 和非终止型路由会保留待处理投递。需要可靠投递的调用方应等待回执；尽力执行的 UI steering 可以忽略它。
+- `agent.steer(input)`：`next-step`／wakeup 预设：提交一条已有标识的消息，并取得其 `SteeringReceipt`。提示词接纳期间或轮次打开时，消息会为下一个安全请求边界暂存，且不分发 `agent/prompt-submit`；该接收窗口之外则成为会唤醒驱动器的排队提示词。只有循环记录消息、将其捕获到不可变请求历史并提交 `step/start` 后，`receipt.outcome` 才会解析为 `admitted`，并附带轮次与步骤。结束轮次的工具结果、广义取消、dispose 或准入前故障会使其解析为 `rejected`；`cancel(..., { keepInbox: true })` 和非终止型路由会保留待处理投递。需要可靠投递的调用方应等待回执；尽力执行的 UI steering 可以忽略它。
 - `agent.inject(input)`：`next-step`／不唤醒预设：追加面向模型的上下文而不运行模型；下一次请求会看到一条逐字的 user role 消息，其来源由必填的 `input.source` 携带。提示词接纳期间或轮次打开时，注入会在 outbox 中等待下一个安全边界。该接收窗口之外，它会立即追加而不开启轮次；如果接纳结束却未开启轮次，仅含上下文的接纳批次会采用这一回退，而与 steering 一同暂存的上下文则会随其继续待处理。持久化独立地响应 `session/event`。注入不发出 `agent/inbox/*` 事件。
 - `agent.acceptsNextStep`：当前发送 `next-step` 时，是否会加入提示词接纳或已打开的轮次。当调用方必须在 steering 与新接纳的提示词之间选择时，应使用这一更窄的路由判定；`status === 'running'` 还涵盖接纳收尾与轮次结算阶段。
 - `agent.cancel(cause, options?)`：取消活动轮次，并在未设置 `options.keepInbox` 时取消全部待处理工作。调用方必须显式选择 `user | parent` 原因；活动持有者会在中止前把其判别字段复制为已分离、冻结的信号原因。有效调用会在清除排队与 steering 工作前，随原因发出 `agent/cancel-requested`；丢弃项在 `agent/inbox/discard` 上报告，观察方可以同步状态，但不能 veto 取消。`keepInbox: true` 会中止轮次，但保留排队与 steering 项（不丢弃，且不删除尚未开始的工作）。同进程类型化 seam 不会为无类型调用方添加运行时校验或兼容回退。重复取消活动轮次时，首个信号生效；空闲取消是安全空操作，不发通知。ACP 映射到 `user`，进程内父传播映射到 `parent`。原因只存在于运行时；持久 `turn/end` 保持粗粒度的 `aborted`。
@@ -77,7 +77,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，

 - Agent 创建：`AgentLoop.create()` 是具体配置路径实现（位于 `dsh-agent-loop`），程序化消费方则通过 `ctx.agents.create()`/`ctx.agents.resume()` 创建或恢复有所有权的 agent。替换循环时，应实现 `Agent` 并通过 `ctx.agents.register()` 注册。
 - 事件监听器：全部 `agent/*` 事件都在此处声明，不需要依赖循环包。
- Subagent 委派不是 `Agent` 方法；提供方通过工厂 seam 创建或驱动普通 handle，因此委派传输留在核心 agent 接口之外。
+- subagent 委派不是 `Agent` 方法；提供方通过工厂 seam 创建或驱动普通 handle，因此委派传输留在核心 agent 接口之外。

 ## 模型体验

@@ -115,6 +115,6 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 - **环境身份可能比存活状态更久**：消费方在生命周期敏感工作前，仍要检查 `agent.status`、取消状态和所属能力契约。
 - **委派以外的 agent 间通道**：共享状态、流式子输出和后台／轮询语义仍在当前同步 `ctx.subagents` seam 之外。
 - **`agent/session-start` 不能为启动设置门禁**：它仍是同步且不可 veto 的通知；必须在发布前完成的异步组合属于工厂的 `setup(agentCtx)` 事务。
- **`cancel()` 默认清空 inbox**：它会中止正在处理的轮次以及排队和 steering 工作；`cancel(cause, { keepInbox: true })` 只中止轮次并保留待处理项。仍不存在只中止步骤、同时让正在处理的轮次继续运行的操作（[停止表层 Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)）。
+- **`cancel()` 默认清空 inbox**：它会中止正在处理的轮次以及排队和 steering 工作；`cancel(cause, { keepInbox: true })` 只中止轮次并保留待处理项。仍不存在只中止步骤、同时让正在处理的轮次继续运行的操作（[关于停止操作接口的 Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)）。
 - **每条附加 `UserMessage` 恰好携带一个 `MessageSource`**：多个插件合并到一次工具调用上的贡献会归入一个来源；无法表示混合来源。
 - **`SessionStartSource` 预留 `'clear'`/`'compact'`，但还没有发出方**：在驱动子系统落地前，只会出现 `'startup'`/`'resume'`（`TODO(compaction)`）。
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -26,9 +26,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/types/**/*.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
--- a/packages/core/agent/tests/agent.spec.ts
+++ b/packages/core/agent/tests/agent.spec.ts
@@ -19,7 +19,7 @@ function stubAgent(rawId: string, overrides: Partial<Agent> = {}): Agent {
  const agent: Agent = {
    id,
    options: {},
-    session: new Session(id),
+    session: Session.create(id),
    status: 'idle',
    acceptsNextStep: false,
    ctx: new Context(),
@@ -58,7 +58,7 @@ describe('AgentRegistry', () => {
  it('rejects an agent whose registry and session identities differ', async () => {
    const ctx = new Context()
    await ctx.plugin(AgentRegistry)
-    const agent = stubAgent('agent-id', { session: new Session(SessionId('session-id')) })
+    const agent = stubAgent('agent-id', { session: Session.create(SessionId('session-id')) })

    expect(() => ctx.agents.enter(agent, undefined))
      .toThrow('agent id "agent-id" does not match session id "session-id"')
--- a/packages/core/scope/README.i18n.yaml
+++ b/packages/core/scope/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/scope/README.md
 README.md: 4f32573779a15e8c34b4936bfe75549dfc86d9f6
-README.zh.md: b060d8f8e44a28e717ee4724249b797941388798
+README.zh.md: 16ec60a5489f909a46fd5f803dbf08490cd07988
--- a/packages/core/scope/README.zh.md
+++ b/packages/core/scope/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-带作用域的注册原语。`createScope(ctx, key)` 创建一个带标签的 Cordis 上下文，其底层 fiber 拥有通过该上下文进行的每项注册。`scopeOf(ctx)` 读取标签；`scopeTarget(base, key)` 将带作用域的事件路由到键相同的监听器，同时让无作用域监听器保持全局可见。agent loop（智能体循环）为每个实时 agent 创建一个作用域，但该机制与键的具体含义无关，因此底层包（package）无需依赖 agent 即可使用。
+带作用域的注册原语。`createScope(ctx, key)` 创建一个带标签的 Cordis 上下文，其底层 fiber 拥有通过该上下文进行的每项注册。`scopeOf(ctx)` 读取标签；`scopeTarget(base, key)` 将带作用域的事件路由到键相同的监听器，同时让无作用域监听器保持全局可见。agent loop（智能体循环）为每个实时 agent 创建一个作用域，但该机制与键的具体含义无关，因此底层包无需依赖 agent 即可使用。

 ## 公开 API

@@ -23,7 +23,7 @@

 ## 设计契约

-注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。
+注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。

 感知作用域的服务会定义具体 `ScopeLayer`，聚合各自不同的表与领域辅助函数。`ScopedLayers.effect()` 接受一个返回同步撤销函数的同步动作，在可选通知前安装该撤销函数，并且只有在完整聚合为空时才回收精确作用域层。`notify` 默认为 `true`；由所提供的回调决定观测方失败是向外抛出还是在内部处理。`EntryValues` 保持内部可见；存储类从包根而非 `/store` 子路径导入；共享存储不定义注册表专属的筛选或迭代策略。详见[共享作用域层存储 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)。

--- a/packages/core/scope/package.json
+++ b/packages/core/scope/package.json
@@ -21,9 +21,7 @@
  "files": [
    "lib/index.js",
    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/session/README.md
-README.md: 892be8237d008b85418d8b815325a970b140a163
+README.md: 6b1fa9f15b26c87dde9ed7bc356154f2fcc59b42
 README.zh.md: 031239faf0fd14d582988f05590816cd17c329b6
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -35,7 +35,7 @@ The store pairs announced creation with disposal, publishes post-commit append n

 ### Class: `Session`

-Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
+Plain class (not a Cordis Service). Create live sessions through `ctx.sessions.create()` and detached replay or inspection sessions through `Session.create()`; the detached factory does not publish lifecycle events or bind the session to a fiber.

 - `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, complete replacement coverage, and content-only single-result `tool/result` rewrites, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
 - `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over the complete identified, frozen messages stored by those entries. Assistant messages preserve provider/model provenance and adapter-private replay state in their model source. A surface rewrite rebuilds the projection; there is no raw-log fallback.
@@ -49,6 +49,8 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.

 Durable values need one accepted representation, not a check followed by a second read. `isJsonValue(value)` is the boolean predicate; `snapshotJsonValue(value)` iteratively validates and copies a plain value in one pass, returning `undefined` for invalid input and propagating a throwing getter. The snapshot helper accepts finite JSON numbers except `-0` (JSON rewrites it to `0`), dense ordinary arrays, and plain or null-prototype objects; it rejects cycles, unsupported scalars, and exotic prototypes before normalization without imposing a call-stack depth limit.

+Session-event import separates ownership from message validation. `snapshotSessionEvent(event)` clones a borrowed event before validating and freezing its identified message. `adoptSessionEvent(event)` performs the same message work in place and returns the original event; callers may use it only when they transfer an exclusively owned object graph with no mutable child shared with another event.
+
 ### Chunk-row storage codec (`chunk-rows.ts`)

 Providers stream token-sized deltas, so a raw log stores hundreds of `assistant/chunk` lines whose JSON envelopes dwarf their payloads. `packChunkRuns(events)` packs each run of ≥3 consecutive same-block delta chunks into one storage row — `text-chunks`, `reasoning-chunks`, or `tool-call-chunks` (bare slash-less tags: storage vocabulary, not `SessionEventMap` members) — and `decodeStorageRecord(value)` expands a parsed line back into its exact events (`seq0`/`time0` + per-member `dt` gaps reconstruct every `seq`/`time`). The encoder whitelists exact shapes and stores anything unrecognized verbatim; the decoder validates row-tagged values and throws on malformation. Owned here so the JSONL backend and the fixture readers (`dsh-llm-replay`, `dsh-acp-snapshot`) share one codec; the backend's default-enabled `packChunks` config controls writes only.
--- a/packages/core/session/package.json
+++ b/packages/core/session/package.json
@@ -30,9 +30,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/types/**/*.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -103,17 +103,12 @@ declare module 'cordis' {
  }
 }

-/** Detach, validate, and freeze the creation metadata published by a session. */
-function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHeader {
-  const input: unknown = source === undefined
-    ? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
-    : source
-  const snapshot = snapshotJsonValue(input)
-  if (snapshot === undefined) throw new Error('session header is not losslessly JSON-serializable')
-  if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+/** Validate and freeze one detached creation header in place. */
+function validateSessionHeader(id: SessionId, input: unknown): SessionHeader {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
    throw new Error('session header is not a plain JSON record')
  }
-  const record = snapshot as Record<string, unknown>
+  const record = input as Record<string, unknown>
  if (record.version !== SESSION_FORMAT_VERSION) {
    throw new Error(`session header version must be ${SESSION_FORMAT_VERSION}, got ${String(record.version)}`)
  }
@@ -148,31 +143,52 @@ function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHe
  return deepFreeze(record as unknown as SessionHeader)
 }

+/** Detach, validate, and freeze the creation metadata published by a session. */
+function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHeader {
+  const input: unknown = source === undefined
+    ? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
+    : source
+  const snapshot = snapshotJsonValue(input)
+  if (snapshot === undefined) throw new Error('session header is not losslessly JSON-serializable')
+  return validateSessionHeader(id, snapshot)
+}
+
+/**
+ * Validate an exclusively owned event and deeply freeze its identified message
+ * without copying the event. The caller transfers an object graph that no
+ * producer retains and that shares no mutable children with another event.
+ * Use {@link snapshotSessionEvent} when exclusive ownership is not guaranteed.
+ * @param event - exclusively owned event imported across a trusted boundary.
+ * @returns the same event object with a validated, deeply frozen message.
+ */
+export function adoptSessionEvent<T extends SessionEvent>(event: T): T {
+  assertMessageEventShape(
+    event,
+    `session event at seq ${event.seq}`,
+  )
+  switch (event.type) {
+    case 'user/message':
+      deepFreeze(event.data)
+      break
+    case 'assistant/message':
+    case 'tool/result':
+    case 'steering/message':
+      deepFreeze(event.data.message)
+      break
+    default:
+      // SessionEventMap is merge-extensible; plugin-owned events carry no core message.
+      break
+  }
+  return event
+}
+
 /**
 * Detach one event while preserving deep immutability for its identified message.
 * @param event - event imported across a query or persistence boundary.
 * @returns a detached event snapshot with a validated, deeply frozen message.
 */
 export function snapshotSessionEvent<T extends SessionEvent>(event: T): T {
-  const snapshot = structuredClone(event)
-  assertMessageEventShape(
-    snapshot,
-    `session event at seq ${snapshot.seq}`,
-  )
-  switch (snapshot.type) {
-    case 'user/message':
-      deepFreeze(snapshot.data)
-      break
-    case 'assistant/message':
-    case 'tool/result':
-    case 'steering/message':
-      deepFreeze(snapshot.data.message)
-      break
-    default:
-      // SessionEventMap is merge-extensible; plugin-owned events carry no core message.
-      break
-  }
-  return snapshot
+  return adoptSessionEvent(structuredClone(event))
 }

 /** Validate the fixed event envelope after one-pass JSON materialization. */
@@ -378,7 +394,8 @@ const attachments = new WeakMap<Session, SessionEntry>()
 /**
 * An event-sourced session: an append-only log of {@link SessionEvent}s.
 *
- * Plain class (not a Service) — create instances via `ctx.sessions.create()`.
+ * Plain class (not a Service) — create live instances via
+ * `ctx.sessions.create()` and detached instances via {@link create}.
 * Seeding with an existing event log replays/forks a session.
 * @typert object
 */
@@ -433,7 +450,19 @@ export class Session {
   */
  readonly firstLiveSeq: number

-  constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader) {
+  /**
+   * Create a detached session by validating and snapshotting borrowed seed
+   * events and storage metadata.
+   * @param id - session identity.
+   * @param seed - optional borrowed replay or fork events.
+   * @param header - optional borrowed storage metadata.
+   * @returns a detached session.
+   */
+  static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session {
+    return new Session(id, seed, header)
+  }
+
+  private constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader) {
    if (seed !== undefined) {
      // Validate the seed to the SAME invariants `append` enforces, so a
      // replay/fork (`ctx.sessions.create(id, { seed })`) cannot construct a
@@ -843,7 +872,7 @@ export class SessionStore extends Service {
      ...meta?.origin === undefined ? {} : { origin: meta.origin },
      ...meta?.delegationDepth === undefined ? {} : { delegationDepth: meta.delegationDepth },
    }
-    return new Session(sessionId, seed, header)
+    return Session.create(sessionId, seed, header)
  }

  /**
--- a/packages/core/session/tests/derived-cache.spec.ts
+++ b/packages/core/session/tests/derived-cache.spec.ts
@@ -16,12 +16,12 @@ function userText(session: Session, text: string): void {

 /** From-scratch oracle: replay the log into a fresh session and derive. */
 function scratch(session: Session): unknown {
-  return new Session(SessionId(`${session.id}-scratch-${session.seq}`), [...session.events]).deriveMessages()
+  return Session.create(SessionId(`${session.id}-scratch-${session.seq}`), [...session.events]).deriveMessages()
 }

 describe('derived-message cache', () => {
  it('stays deep-equal to a from-scratch replay derivation as the log grows', () => {
-    const session = new Session(SessionId('cache-grow'))
+    const session = Session.create(SessionId('cache-grow'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    userText(session, 'one')
    expect(session.deriveMessages()).toEqual(scratch(session))
@@ -54,7 +54,7 @@ describe('derived-message cache', () => {
  })

  it('rebuilds on a surface replace and still matches scratch', () => {
-    const session = new Session(SessionId('cache-replace'))
+    const session = Session.create(SessionId('cache-replace'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    userText(session, 'one')
    userText(session, 'two')
@@ -72,7 +72,7 @@ describe('derived-message cache', () => {
  })

  it('returns a fresh array per call: later appends never grow a held snapshot', () => {
-    const session = new Session(SessionId('cache-snapshot'))
+    const session = Session.create(SessionId('cache-snapshot'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    userText(session, 'one')
    const first = session.deriveMessages()
@@ -89,7 +89,7 @@ describe('derived-message cache', () => {

 describe('Session.deriveEventMessage — the per-event projection', () => {
  it('projects one appended event exactly as the full derivation projects its node', () => {
-    const session = new Session(SessionId('per-event'))
+    const session = Session.create(SessionId('per-event'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    const event = session.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
@@ -99,7 +99,7 @@ describe('Session.deriveEventMessage — the per-event projection', () => {
  })

  it('reuses the logged event\'s already frozen content', () => {
-    const session = new Session(SessionId('per-event-clone'))
+    const session = Session.create(SessionId('per-event-clone'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    const event = session.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'orig' }], source: { kind: 'user' },
@@ -113,7 +113,7 @@ describe('Session.deriveEventMessage — the per-event projection', () => {
  })

  it('projects null for events that produce no message (boundaries, empty assistant)', () => {
-    const session = new Session(SessionId('per-event-null'))
+    const session = Session.create(SessionId('per-event-null'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    const boundary = session.append('step/start', { turn: 1, step: 1 })
    expect(session.deriveEventMessage(boundary)).toBeNull()
--- a/packages/core/session/tests/fork.spec.ts
+++ b/packages/core/session/tests/fork.spec.ts
@@ -217,7 +217,7 @@ describe('SessionStore.fork', () => {

  it('rejects a detached Session object that is not live in ctx.sessions', async () => {
    const { sessions } = await setup()
-    const detached = new Session(SessionId('detached'))
+    const detached = Session.create(SessionId('detached'))

    expect(() => sessions.fork(detached))
      .toThrow(new SessionForkError('session "detached" not found', 'SESSION_NOT_FOUND'))
@@ -226,7 +226,7 @@ describe('SessionStore.fork', () => {
  it('rejects a stale Session object whose id is live on a different instance', async () => {
    const { ctx, sessions } = await setup()
    ctx.sessions.create(SessionId('same-id'))
-    const stale = new Session(SessionId('same-id'))
+    const stale = Session.create(SessionId('same-id'))

    expect(() => sessions.fork(stale))
      .toThrow(new SessionForkError('session "same-id" is not the live store instance', 'SESSION_NOT_LIVE'))
--- a/packages/core/session/tests/properties.spec.ts
+++ b/packages/core/session/tests/properties.spec.ts
@@ -82,7 +82,7 @@ const logArb = fc.array(anyEventArb, { maxLength: 25 })

 let counter = 0
 function build(events: Appendable[]): Session {
-  const session = new Session(SessionId(`prop-${counter++}`))
+  const session = Session.create(SessionId(`prop-${counter++}`))
  for (const e of events) {
    // Forward the generated intent verbatim; non-surface events carry none.
    if (e.intent !== undefined) session.append(e.type, e.data, e.intent)
@@ -110,7 +110,7 @@ describe('Session properties', () => {
  it('replay-from-seed reproduces the derivation identically', () => {
    fc.assert(fc.property(logArb, (events) => {
      const original = build(events)
-      const replayed = new Session(SessionId(`replay-${counter++}`), [...original.events])
+      const replayed = Session.create(SessionId(`replay-${counter++}`), [...original.events])
      expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
      // Every explicit replay grows by exactly one log-only boundary.
      expect(replayed.events.slice(0, original.seq)).toEqual(original.events)
@@ -121,8 +121,8 @@ describe('Session properties', () => {
  it('replaying a log that already ends in end-seed adds no further marker', () => {
    fc.assert(fc.property(logArb, (events) => {
      const original = build(events)
-      const once = new Session(SessionId(`idem-a-${counter++}`), [...original.events])
-      const twice = new Session(SessionId(`idem-b-${counter++}`), [...once.events])
+      const once = Session.create(SessionId(`idem-a-${counter++}`), [...original.events])
+      const twice = Session.create(SessionId(`idem-b-${counter++}`), [...once.events])
      // Lazy resume makes browsing a pickup, so this must not grow per open.
      expect(twice.events).toEqual(once.events)
    }))
--- a/packages/core/session/tests/request-header.spec.ts
+++ b/packages/core/session/tests/request-header.spec.ts
@@ -75,7 +75,7 @@ describe('foldRequestHeader', () => {
  })

  it('takes the latest full snapshot and skips unrelated events', () => {
-    const session = new Session(SessionId('fold'))
+    const session = Session.create(SessionId('fold'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    session.append('request/header', { header: { config: CONFIG, system: 'first' }, reason: 'initial' })
    session.append('user/message', createUserMessage({
@@ -91,9 +91,9 @@ describe('legacy request-header format', () => {
    const legacy = [{
      type: 'request/header-delta', seq: 0, time: 1, data: { config: CONFIG },
    }] as unknown as SessionEvent[]
-    expect(() => new Session(SessionId('legacy'), legacy)).toThrow(/unsupported legacy request\/header-delta/)
+    expect(() => Session.create(SessionId('legacy'), legacy)).toThrow(/unsupported legacy request\/header-delta/)

-    const session = new Session(SessionId('legacy-append-delta'))
+    const session = Session.create(SessionId('legacy-append-delta'))
    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
    expect(() => appendLegacy('request/header-delta', { config: CONFIG }))
      .toThrow(/unsupported legacy request\/header-delta/)
@@ -104,10 +104,10 @@ describe('legacy request-header format', () => {
    const legacy = [{
      type: 'request/header', seq: 0, time: 1, data: { header: { config: CONFIG }, reason: 'fallback' },
    }] as unknown as SessionEvent[]
-    expect(() => new Session(SessionId('legacy-seed-reason'), legacy))
+    expect(() => Session.create(SessionId('legacy-seed-reason'), legacy))
      .toThrow('unsupported legacy request/header reason "fallback"')

-    const session = new Session(SessionId('legacy-append-reason'))
+    const session = Session.create(SessionId('legacy-append-reason'))
    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
    expect(() => appendLegacy('request/header', { header: { config: CONFIG }, reason: 'fallback' }))
      .toThrow('unsupported legacy request/header reason "fallback"')
@@ -130,13 +130,13 @@ describe('Session.requestContext', () => {
  }

  it('reads undefined before any record exists', () => {
-    expect(new Session(SessionId('no-capacity')).requestContext()).toBeUndefined()
+    expect(Session.create(SessionId('no-capacity')).requestContext()).toBeUndefined()
  })

  it('folds a seeded log on first read, taking the last record', () => {
    // The fold watermark starts at 0 with the seed already in the log, so the
    // first read must consume the whole seed rather than skip it.
-    const session = new Session(SessionId('seeded-capacity'), seedWith(
+    const session = Session.create(SessionId('seeded-capacity'), seedWith(
      CAPACITY,
      { ...CAPACITY, model: 'later', contextWindow: 256_000 },
    ))
@@ -144,7 +144,7 @@ describe('Session.requestContext', () => {
  })

  it('advances incrementally across appends and skips unrelated events', () => {
-    const session = new Session(SessionId('incremental-capacity'), seedWith(CAPACITY))
+    const session = Session.create(SessionId('incremental-capacity'), seedWith(CAPACITY))
    expect(session.requestContext()).toEqual(CAPACITY)
    session.append('todo/write', { todos: [] })
    expect(session.requestContext()).toEqual(CAPACITY)
@@ -155,7 +155,7 @@ describe('Session.requestContext', () => {
  })

  it('folds a batch appended between two reads', () => {
-    const session = new Session(SessionId('batched-capacity'), seedWith(CAPACITY))
+    const session = Session.create(SessionId('batched-capacity'), seedWith(CAPACITY))
    expect(session.requestContext()).toEqual(CAPACITY)
    session.append('request/context', { ...CAPACITY, contextWindow: 200_000 })
    session.append('todo/write', { todos: [] })
@@ -164,7 +164,7 @@ describe('Session.requestContext', () => {
  })

  it('exposes a frozen record so a reader cannot desync later comparisons', () => {
-    const session = new Session(SessionId('frozen-capacity'), seedWith(CAPACITY))
+    const session = Session.create(SessionId('frozen-capacity'), seedWith(CAPACITY))
    const held = session.requestContext()
    if (held === undefined) throw new Error('expected a folded capacity record')
    expect(Object.isFrozen(held)).toBe(true)
--- a/packages/core/session/tests/session.spec.ts
+++ b/packages/core/session/tests/session.spec.ts
@@ -2,6 +2,7 @@ import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { createUserMessage, CallId, createMessage, createToolResultMessage, MessageId, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import SessionStore, {
+  adoptSessionEvent,
  findLastMessageTurnEnd,
  SESSION_FORMAT_VERSION,
  Session,
@@ -13,7 +14,7 @@ import type { CreateSessionOptions, SessionEventType, SessionHeader, SessionSurf

 describe('Session', () => {
  it('exposes one stable readonly surface view', () => {
-    const session = new Session(SessionId('surface-view'))
+    const session = Session.create(SessionId('surface-view'))
    const surface = session.surface

    expectTypeOf(surface).toEqualTypeOf<SessionSurface>()
@@ -21,7 +22,7 @@ describe('Session', () => {
  })

  it('derives message history from the event log', () => {
-    const session = new Session(SessionId('s1'))
+    const session = Session.create(SessionId('s1'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    session.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' },
@@ -61,7 +62,7 @@ describe('Session', () => {
  it('accepts and round-trips a max-tokens turn/end reason', () => {
    // The max-tokens TurnEndReason variant carries no extra data, so it must
    // append and persist like any other reason (JSON-serializable, no fields).
-    const session = new Session(SessionId('s1'))
+    const session = Session.create(SessionId('s1'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    session.append('turn/end', { turn: 1, reason: { kind: 'max-tokens' } })

@@ -72,7 +73,7 @@ describe('Session', () => {
  })

  it('finds the latest message-turn outcome past later non-message turns', () => {
-    const session = new Session(SessionId('message-turn-outcome'))
+    const session = Session.create(SessionId('message-turn-outcome'))
    expect(findLastMessageTurnEnd(session.events)).toBeUndefined()
    session.append('turn/start', {
      turn: 1,
@@ -108,10 +109,10 @@ describe('Session', () => {
  })

  it('round-trips the coarse aborted turn outcome', () => {
-    const session = new Session(SessionId('aborted'))
+    const session = Session.create(SessionId('aborted'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } })
-    const replayed = new Session(SessionId('aborted-replay'), structuredClone(session.events))
+    const replayed = Session.create(SessionId('aborted-replay'), structuredClone(session.events))
    expect(replayed.events.slice(0, -1)).toEqual(session.events)
    const turnEnd = replayed.events.findLast(event => event.type === 'turn/end')
    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' })
@@ -129,12 +130,12 @@ describe('Session', () => {
      },
    ] as unknown as SessionEvent[]

-    expect(() => new Session(SessionId('legacy-aborted'), legacy))
+    expect(() => Session.create(SessionId('legacy-aborted'), legacy))
      .toThrow('seed turn/end at index 1 uses unsupported reason-bearing aborted format')
  })

  it('renders injected-context and steering messages as plain user content', () => {
-    const session = new Session(SessionId('s2'))
+    const session = Session.create(SessionId('s2'))
    session.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'file changed: a.ts' }],
      source: { kind: 'plugin', plugin: 'watcher' },
@@ -155,7 +156,7 @@ describe('Session', () => {
  })

  it('keeps the exact identified context message in durable history and projection', () => {
-    const session = new Session(SessionId('s2-raw'))
+    const session = Session.create(SessionId('s2-raw'))
    const message = createUserMessage({
      content: [{ type: 'text', text: '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>' }],
      source: { kind: 'plugin', plugin: 'workspace-context' },
@@ -168,7 +169,7 @@ describe('Session', () => {
  })

  it('replays identically from a seeded event log', () => {
-    const original = new Session(SessionId('s3'))
+    const original = Session.create(SessionId('s3'))
    original.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    original.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'q' }], source: { kind: 'user' },
@@ -186,7 +187,7 @@ describe('Session', () => {
    }, { surfaceOp: 'append' })
    original.append('turn/end', { turn: 1, reason: { kind: 'completed' } })

-    const replayed = new Session(SessionId('s3-replay'), [...original.events])
+    const replayed = Session.create(SessionId('s3-replay'), [...original.events])
    expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
    // The seed verbatim, plus the end-seed event the constructor appends.
    expect(replayed.events.slice(0, original.seq)).toEqual(original.events)
@@ -195,16 +196,16 @@ describe('Session', () => {
  })

  it('marks an explicitly empty seed without marking a fresh session', () => {
-    const fresh = new Session(SessionId('fresh-empty'))
+    const fresh = Session.create(SessionId('fresh-empty'))
    expect(fresh.events).toEqual([])

-    const resumed = new Session(SessionId('resumed-empty'), [])
+    const resumed = Session.create(SessionId('resumed-empty'), [])
    expect(resumed.firstLiveSeq).toBe(0)
    expect(resumed.events).toMatchObject([
      { type: 'session/end-seed', seq: 0, data: {} },
    ])

-    const reopened = new Session(SessionId('reopened-empty'), resumed.events)
+    const reopened = Session.create(SessionId('reopened-empty'), resumed.events)
    expect(reopened.firstLiveSeq).toBe(1)
    expect(reopened.events).toEqual(resumed.events)
  })
@@ -214,7 +215,7 @@ describe('Session', () => {
      type: 'request/header', seq: 0, time: 1,
      data: { header: { config: { model: 'old-model' } }, reason: 'initial' },
    } as unknown as SessionEvent
-    expect(() => new Session(SessionId('old-header'), [requestHeader]))
+    expect(() => Session.create(SessionId('old-header'), [requestHeader]))
      .toThrow('seed request/header at index 0 lacks provider/model')

    const assistantMessage = {
@@ -222,20 +223,20 @@ describe('Session', () => {
      data: { turn: 1, step: 1, content: [{ type: 'text', text: 'old' }] },
      surfaceOp: 'append',
    } as unknown as SessionEvent
-    expect(() => new Session(SessionId('old-assistant'), [assistantMessage]))
+    expect(() => Session.create(SessionId('old-assistant'), [assistantMessage]))
      .toThrow('seed assistant/message at index 0 lacks an identified message')

    const malformedHeader = {
      type: 'request/header', seq: 0, time: 1,
      data: { header: 'old-header' },
    } as unknown as SessionEvent
-    expect(() => new Session(SessionId('malformed-header'), [malformedHeader]))
+    expect(() => Session.create(SessionId('malformed-header'), [malformedHeader]))
      .toThrow('seed request/header at index 0 lacks provider/model')

    const unrelatedPrimitiveData = {
      type: 'plugin/event', seq: 0, time: 1, data: null,
    } as unknown as SessionEvent
-    expect(new Session(SessionId('primitive-plugin-data'), [unrelatedPrimitiveData]).events.slice(0, 1))
+    expect(Session.create(SessionId('primitive-plugin-data'), [unrelatedPrimitiveData]).events.slice(0, 1))
      .toEqual([unrelatedPrimitiveData])
  })

@@ -353,7 +354,7 @@ describe('Session', () => {

    for (const { name, event, message } of invalid) {
      expect(
-        () => new Session(SessionId(`invalid-${name}`), [event as unknown as SessionEvent]),
+        () => Session.create(SessionId(`invalid-${name}`), [event as unknown as SessionEvent]),
        name,
      ).toThrow(message)
    }
@@ -389,6 +390,45 @@ describe('Session', () => {
      .toEqual([{ type: 'plugin-block', value: 1 }])
  })

+  it('adopts exclusively owned messages in place and keeps snapshots detached', () => {
+    const owned = {
+      type: 'user/message',
+      seq: 0,
+      time: 1,
+      surfaceOp: 'append',
+      data: {
+        id: 'owned-message',
+        role: 'user',
+        content: [{ type: 'text', text: 'owned' }],
+        source: { kind: 'user' },
+      },
+    } as SessionEvent<'user/message'>
+    expect(adoptSessionEvent(owned)).toBe(owned)
+    expect(Object.isFrozen(owned.data)).toBe(true)
+    expect(Object.isFrozen(owned.data.content)).toBe(true)
+
+    const source = structuredClone(owned)
+    const snapshot = snapshotSessionEvent(source)
+    expect(snapshot).not.toBe(source)
+    expect(snapshot.data).not.toBe(source.data)
+    expect(snapshot.data.content).not.toBe(source.data.content)
+  })
+
+  it('validates message shape before adopting ownership', () => {
+    const malformed = {
+      type: 'user/message',
+      seq: 0,
+      time: 1,
+      data: {
+        id: 'wrong-role',
+        role: 'assistant',
+        content: [],
+        source: { kind: 'user' },
+      },
+    } as unknown as SessionEvent
+    expect(() => adoptSessionEvent(malformed)).toThrow('message must have role "user"')
+  })
+
  it('round-trips a non-empty reasoning effort and rejects invalid durable values', () => {
    const valid = {
      type: 'request/header',
@@ -405,7 +445,7 @@ describe('Session', () => {
        reason: 'initial',
      },
    } as const
-    expect(new Session(SessionId('reasoning-effort'), [valid]).events[0])
+    expect(Session.create(SessionId('reasoning-effort'), [valid]).events[0])
      .toEqual(valid)

    for (const reasoningEffort of ['', 1]) {
@@ -413,7 +453,7 @@ describe('Session', () => {
      if (invalid.type !== 'request/header') throw new Error('test fixture must be a request header')
      const config = invalid.data.header.config as unknown as Record<string, unknown>
      config.reasoningEffort = reasoningEffort
-      expect(() => new Session(SessionId('invalid-reasoning-effort'), [invalid]))
+      expect(() => Session.create(SessionId('invalid-reasoning-effort'), [invalid]))
        .toThrow('seed request/header at index 0 has an invalid reasoningEffort')
    }
  })
@@ -435,7 +475,7 @@ describe('Session', () => {
        reason: 'initial',
      },
    } as const
-    expect(new Session(SessionId('adapter-defaults'), [valid]).events[0]).toEqual(valid)
+    expect(Session.create(SessionId('adapter-defaults'), [valid]).events[0]).toEqual(valid)

    for (const adapterDefaults of [
      null,
@@ -447,13 +487,13 @@ describe('Session', () => {
      const invalid = structuredClone(valid) as unknown as SessionEvent
      if (invalid.type !== 'request/header') throw new Error('test fixture must be a request header')
      invalid.data.header.adapterDefaults = adapterDefaults as never
-      expect(() => new Session(SessionId('invalid-adapter-defaults'), [invalid]))
+      expect(() => Session.create(SessionId('invalid-adapter-defaults'), [invalid]))
        .toThrow('seed request/header at index 0 has invalid adapterDefaults')
    }
  })

  it('isolates the log from mutation through a derived message (append-only contract)', () => {
-    const session = new Session(SessionId('s4'))
+    const session = Session.create(SessionId('s4'))
    session.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'original' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })
@@ -487,7 +527,7 @@ describe('Session', () => {
  })

  it('rejects non-JSON-serializable event data at the source (incl. sparse arrays)', () => {
-    const session = new Session(SessionId('s5'))
+    const session = Session.create(SessionId('s5'))
    const bad = (extra: unknown) => () => session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra } as never, { surfaceOp: 'append' })
    expect(bad(1n)).toThrow(/non-JSON-serializable/)
    expect(bad(() => 0)).toThrow(/non-JSON-serializable/)
@@ -514,7 +554,7 @@ describe('Session', () => {
  })

  it('rejects a surface-eligible append with no surfaceOp marker (runtime guard for the union-widening loophole)', () => {
-    const session = new Session(SessionId('s5b'))
+    const session = Session.create(SessionId('s5b'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    // A widened SessionEventType bypasses the overload's conditional requirement,
    // so the runtime guard must still reject the missing surface marker.
@@ -528,7 +568,7 @@ describe('Session', () => {
  })

  it('accepts dense arrays and nested plain objects', () => {
-    const session = new Session(SessionId('s6'))
+    const session = Session.create(SessionId('s6'))
    expect(() => session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra: [1, 2, [3, { a: null, b: true }]] } as never, { surfaceOp: 'append' })).not.toThrow()
    expect(session.events).toHaveLength(1)
  })
@@ -539,7 +579,7 @@ describe('Session', () => {
    const badSeed = [
      { type: 'user/message' as const, seq: 0, time: 1, data: { content: [{ type: 'text' as const, text: 'x' }], source: { kind: 'user' as const }, bad: 1n } },
    ] as unknown as SessionEvent[]
-    expect(() => new Session(SessionId('seed-bad'), badSeed)).toThrow(/losslessly JSON-serializable/)
+    expect(() => Session.create(SessionId('seed-bad'), badSeed)).toThrow(/losslessly JSON-serializable/)
  })

  it('validates seed events: rejects a non-contiguous seq', () => {
@@ -547,7 +587,7 @@ describe('Session', () => {
      { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
      { type: 'turn/end' as const, seq: 5, time: 2, data: { turn: 1, reason: { kind: 'completed' as const } } }, // gap: expected seq 1
    ] as SessionEvent[]
-    expect(() => new Session(SessionId('seed-gap'), gapSeed)).toThrow(/contiguous|seq/)
+    expect(() => Session.create(SessionId('seed-gap'), gapSeed)).toThrow(/contiguous|seq/)
  })

  it('validates seed events: rejects a surface-eligible event missing its surfaceOp marker', () => {
@@ -562,7 +602,7 @@ describe('Session', () => {
      }) },
      { type: 'turn/end' as const, seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' as const } } },
    ] as SessionEvent[]
-    expect(() => new Session(SessionId('seed-no-marker'), markerlessSeed)).toThrow(/requires a surfaceOp marker/)
+    expect(() => Session.create(SessionId('seed-no-marker'), markerlessSeed)).toThrow(/requires a surfaceOp marker/)
  })

  it('accepts a well-formed contiguous serializable seed', () => {
@@ -573,7 +613,7 @@ describe('Session', () => {
      }), surfaceOp: 'append' as const },
      { type: 'turn/end' as const, seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' as const } } },
    ] as SessionEvent[]
-    const session = new Session(SessionId('seed-ok'), goodSeed)
+    const session = Session.create(SessionId('seed-ok'), goodSeed)
    expect(session.events.slice(0, 3)).toEqual(goodSeed)
    expect(session.firstLiveSeq).toBe(3)
  })
@@ -596,7 +636,7 @@ describe('Session', () => {
      },
    })

-    const session = new Session(SessionId('seed-entry-snapshot'), seed)
+    const session = Session.create(SessionId('seed-entry-snapshot'), seed)

    expect(reads).toBe(1)
    expect(session.events.slice(0, 1)).toEqual([accepted])
@@ -613,7 +653,7 @@ describe('Session', () => {
    })
    const seed = [{ type: 'test/unstable', seq: 0, time: 1, data }] as unknown as SessionEvent[]

-    const session = new Session(SessionId('seed-nested-drift'), seed)
+    const session = Session.create(SessionId('seed-nested-drift'), seed)

    expect(reads).toBe(1)
    expect(session.events[0]!.data).toEqual({ value: 'accepted' })
@@ -630,7 +670,7 @@ describe('Session', () => {
      surfaceOp: { op: 'replace', start: 1n, end: 2 },
    }] as unknown as SessionEvent[]

-    expect(() => new Session(SessionId('seed-bad-metadata'), seed))
+    expect(() => Session.create(SessionId('seed-bad-metadata'), seed))
      .toThrow(/losslessly JSON-serializable/)
  })

@@ -650,7 +690,7 @@ describe('Session', () => {
      surfaceOp: new ReplaceOp(),
    }] as unknown as SessionEvent[]

-    expect(() => new Session(SessionId('seed-exotic-metadata'), seed))
+    expect(() => Session.create(SessionId('seed-exotic-metadata'), seed))
      .toThrow(/losslessly JSON-serializable/)
  })

@@ -663,7 +703,7 @@ describe('Session', () => {
    }
    const seed: SessionEvent[] = [new SeedEvent()]

-    expect(() => new Session(SessionId('seed-exotic-shell'), seed))
+    expect(() => Session.create(SessionId('seed-exotic-shell'), seed))
      .toThrow(/not losslessly JSON-serializable/)
  })

@@ -675,7 +715,7 @@ describe('Session', () => {
      data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } },
    }) as unknown as SessionEvent

-    const session = new Session(SessionId('seed-null-prototype'), [event])
+    const session = Session.create(SessionId('seed-null-prototype'), [event])

    expect(session.events.slice(0, 1)).toEqual([{ ...event }])
  })
@@ -708,7 +748,7 @@ describe('Session', () => {
      sourceEventSeqs: [0],
    }] as unknown as SessionEvent[]

-    const session = new Session(SessionId('seed-unstable-metadata'), seed)
+    const session = Session.create(SessionId('seed-unstable-metadata'), seed)
    const event = session.events[1]!
    if (event.type !== 'user/message') throw new Error('test fixture must remain a user/message')

@@ -745,7 +785,7 @@ describe('Session', () => {
    }] as unknown as SessionEvent[]

    try {
-      expect(() => new Session(SessionId('seed-non-error-metadata-failure'), seed))
+      expect(() => Session.create(SessionId('seed-non-error-metadata-failure'), seed))
        .toThrow(`invalid seed event at index 1: ${expected}`)
    } finally {
      hasOwn.mockRestore()
@@ -762,7 +802,7 @@ describe('Session', () => {
      }, surfaceOp: 'append' as const },
      { type: 'turn/end' as const, seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' as const } } },
    ] as SessionEvent[]
-    const session = new Session(SessionId('seed-snapshot'), seed)
+    const session = Session.create(SessionId('seed-snapshot'), seed)
    // Mutate the ORIGINAL seed objects after construction: a shared reference
    // would let this rewrite the forked log (or reintroduce non-serializable
    // data past validation). The snapshot must shield session.events.
@@ -775,7 +815,7 @@ describe('Session', () => {
  })

  it('snapshots append data: mutating the passed object after append does not affect session.events', () => {
-    const session = new Session(SessionId('append-snapshot'))
+    const session = Session.create(SessionId('append-snapshot'))
    const data = {
      id: MessageId('append-input'),
      role: 'user' as const,
@@ -795,7 +835,7 @@ describe('Session', () => {
  })

  it('reads a nested append-data getter once and stores its first JSON value', () => {
-    const session = new Session(SessionId('append-nested-drift'))
+    const session = Session.create(SessionId('append-nested-drift'))
    let reads = 0
    const data = Object.defineProperty({}, 'value', {
      enumerable: true,
@@ -813,7 +853,7 @@ describe('Session', () => {
  })

  it('rejects non-JSON surface metadata before appending the event', () => {
-    const session = new Session(SessionId('append-bad-metadata'))
+    const session = Session.create(SessionId('append-bad-metadata'))

    expect(() => session.append(
      'user/message',
@@ -831,7 +871,7 @@ describe('Session', () => {
      readonly start = 0
      readonly end = 0
    }
-    const session = new Session(SessionId('append-exotic-metadata'))
+    const session = Session.create(SessionId('append-exotic-metadata'))

    expect(() => session.append(
      'user/message',
@@ -844,7 +884,7 @@ describe('Session', () => {
  })

  it('reads a nested append-metadata getter once and stores its first JSON value', () => {
-    const session = new Session(SessionId('append-unstable-metadata'))
+    const session = Session.create(SessionId('append-unstable-metadata'))
    const source = session.append(
      'user/message',
      createUserMessage({
@@ -875,7 +915,7 @@ describe('Session', () => {
  })

  it('rejects invalid plain surface metadata shapes at append', () => {
-    const session = new Session(SessionId('append-invalid-surface-shape'))
+    const session = Session.create(SessionId('append-invalid-surface-shape'))
    const appendRaw = session.append.bind(session) as unknown as (
      type: SessionEventType,
      data: unknown,
@@ -896,7 +936,7 @@ describe('Session', () => {
  })

  it('rejects surface metadata on non-surface append and seed events', () => {
-    const session = new Session(SessionId('non-surface-metadata'))
+    const session = Session.create(SessionId('non-surface-metadata'))
    const appendRaw = session.append.bind(session) as unknown as (
      type: SessionEventType,
      data: unknown,
@@ -908,7 +948,7 @@ describe('Session', () => {
      { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
      { surfaceOp: 'append' },
    )).toThrow(/not surface-eligible and cannot carry surfaceOp/)
-    expect(() => new Session(SessionId('non-surface-metadata-seed'), [{
+    expect(() => Session.create(SessionId('non-surface-metadata-seed'), [{
      type: 'turn/start',
      seq: 0,
      time: 1,
@@ -919,7 +959,7 @@ describe('Session', () => {
  })

  it('deep-freezes seeded and appended event snapshots', () => {
-    const seeded = new Session(SessionId('seed-frozen'), [{
+    const seeded = Session.create(SessionId('seed-frozen'), [{
      type: 'turn/start',
      seq: 0,
      time: 1,
@@ -932,7 +972,7 @@ describe('Session', () => {
    expect(Object.isFrozen(seededEvent.data.trigger)).toBe(true)
    expect(() => { seededEvent.data.turn = 99 }).toThrow(TypeError)

-    const appended = new Session(SessionId('append-frozen'))
+    const appended = Session.create(SessionId('append-frozen'))
    const appendedEvent = appended.append('todo/write', {
      todos: [{ content: 'first', status: 'pending' }],
    })
@@ -944,7 +984,7 @@ describe('Session', () => {
  })

  it('returns cached frozen event-array snapshots that do not grow after append', () => {
-    const session = new Session(SessionId('events-snapshot'))
+    const session = Session.create(SessionId('events-snapshot'))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    const before = session.events
    const beforeEvent = before[0]!
@@ -973,7 +1013,7 @@ describe('Session', () => {
      seedLength: 2,
    }

-    const session = new Session(SessionId('header-owned'), undefined, input)
+    const session = Session.create(SessionId('header-owned'), undefined, input)
    input.cwd = '/caller-mutated'

    expect(session.header).toEqual({
@@ -998,15 +1038,15 @@ describe('Session', () => {
      readonly createdAt = 123
    }

-    expect(() => new Session(SessionId('header-invalid'), undefined, new ExoticHeader()))
+    expect(() => Session.create(SessionId('header-invalid'), undefined, new ExoticHeader()))
      .toThrow(/not losslessly JSON-serializable/)
-    expect(() => new Session(SessionId('header-invalid'), undefined, {
+    expect(() => Session.create(SessionId('header-invalid'), undefined, {
      version: SESSION_FORMAT_VERSION,
      id: SessionId('header-invalid'),
      createdAt: 123,
      parentSession: 1n,
    } as unknown as SessionHeader)).toThrow(/not losslessly JSON-serializable/)
-    expect(() => new Session(SessionId('header-invalid'), undefined, {
+    expect(() => Session.create(SessionId('header-invalid'), undefined, {
      version: SESSION_FORMAT_VERSION,
      id: SessionId('other'),
      createdAt: 123,
@@ -1033,7 +1073,7 @@ describe('Session', () => {
    ]

    for (const { header, error } of cases) {
-      expect(() => new Session(SessionId('header-shape'), undefined, header as SessionHeader)).toThrow(error)
+      expect(() => Session.create(SessionId('header-shape'), undefined, header as SessionHeader)).toThrow(error)
    }
  })

@@ -1057,7 +1097,7 @@ describe('Session', () => {
    ]

    for (const [index, event] of cases.entries()) {
-      expect(() => new Session(SessionId(`bad-envelope-${index}`), [event as SessionEvent]))
+      expect(() => Session.create(SessionId(`bad-envelope-${index}`), [event as SessionEvent]))
        .toThrow(/invalid event envelope/)
    }
  })
@@ -1145,7 +1185,7 @@ describe('SessionStore', () => {
    const secondCtx = new Context()
    await firstCtx.plugin(SessionStore)
    await secondCtx.plugin(SessionStore)
-    const session = new Session(SessionId('owned-key'))
+    const session = Session.create(SessionId('owned-key'))
    const detachFirst = firstCtx.sessions.enter(session)

    expect(() => secondCtx.sessions.enter(session)).toThrow(/already attached to a store/)
@@ -1302,7 +1342,7 @@ describe('SessionStore', () => {
  })

  it('a bare Session() constructed without the store still exposes a current-version header', () => {
-    const session = new Session(SessionId('bare'))
+    const session = Session.create(SessionId('bare'))
    expect(session.header).toMatchObject({ version: SESSION_FORMAT_VERSION, id: 'bare' })
    expect(typeof session.header.createdAt).toBe('number')
  })
@@ -1626,7 +1666,7 @@ describe('SessionStore', () => {
  it('does not let internal dispatch replace the disposed callback tuple', async () => {
    const ctx = new Context()
    await ctx.plugin(SessionStore)
-    const replacement = new Session(SessionId('replacement-disposed'))
+    const replacement = Session.create(SessionId('replacement-disposed'))
    const heard: Session[] = []
    ctx.on('internal/dispatch', (_mode, name, args) => {
      if (name === 'session/disposed') args[0] = replacement
@@ -1644,7 +1684,7 @@ describe('SessionStore', () => {

 describe('todo/write event', () => {
  it('appends the whole-list snapshot and isolates the log from later mutation', () => {
-    const session = new Session(SessionId('t1'))
+    const session = Session.create(SessionId('t1'))
    const todos: TodoItem[] = [
      { content: 'plan the work', status: 'in_progress' },
      { content: 'write the code', status: 'pending' },
@@ -1666,7 +1706,7 @@ describe('todo/write event', () => {
  })

  it('is last-write-wins: the current list is the most recent todo/write', () => {
-    const session = new Session(SessionId('t2'))
+    const session = Session.create(SessionId('t2'))
    session.append('todo/write', { todos: [{ content: 'first', status: 'pending' }] })
    session.append('todo/write', { todos: [
      { content: 'first', status: 'completed' },
@@ -1681,7 +1721,7 @@ describe('todo/write event', () => {
  })

  it('is NOT a surface event: it produces no derived message and joins no surface node', () => {
-    const session = new Session(SessionId('t3'))
+    const session = Session.create(SessionId('t3'))
    session.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'q' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })
@@ -1694,12 +1734,12 @@ describe('todo/write event', () => {
  })

  it('round-trips through a seeded replay identically (durable, no surfaceOp needed)', () => {
-    const original = new Session(SessionId('t4'))
+    const original = Session.create(SessionId('t4'))
    original.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    original.append('todo/write', { todos: [{ content: 'only', status: 'completed' }] })
    original.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
    // Seeding a non-surface event with no surfaceOp must not throw.
-    const replayed = new Session(SessionId('t4-replay'), [...original.events])
+    const replayed = Session.create(SessionId('t4-replay'), [...original.events])
    expect(replayed.events.findLast(e => e.type === 'todo/write')!.data.todos)
      .toEqual([{ content: 'only', status: 'completed' }])
    expect(replayed.events.slice(0, original.seq)).toEqual(original.events)
--- a/packages/core/session/tests/surface.spec.ts
+++ b/packages/core/session/tests/surface.spec.ts
@@ -21,7 +21,7 @@ import {

 /** Build a minimal session with turn boundaries and a single user message. */
 function surfaceSession(): Session {
-  const s = new Session(SessionId('ss'))
+  const s = Session.create(SessionId('ss'))
  s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
  s.append('user/message', createUserMessage({
    content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' },
@@ -288,7 +288,7 @@ describe('SurfaceManager', () => {
  })

  it('shares ordered entries and nested replacement ranges with foldSurface', () => {
-    const s = new Session(SessionId('shared-fold'))
+    const s = Session.create(SessionId('shared-fold'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })
@@ -332,7 +332,7 @@ describe('SurfaceManager', () => {
  })

  it('does not retain fold-only replacement history in incremental state', () => {
-    const s = new Session(SessionId('incremental-state'))
+    const s = Session.create(SessionId('incremental-state'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })
@@ -363,12 +363,12 @@ describe('SurfaceManager', () => {
    ] as SessionEvent[]

    expect(() => foldSurface(events)).toThrow(/start seq 42 not found/)
-    expect(() => new Session(SessionId('shared-fold-invalid'), events))
+    expect(() => Session.create(SessionId('shared-fold-invalid'), events))
      .toThrow(/start seq 42 not found/)
  })

  it('leaves incremental state unchanged when candidate validation fails', () => {
-    const s = new Session(SessionId('atomic-validation'))
+    const s = Session.create(SessionId('atomic-validation'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })
@@ -445,7 +445,7 @@ describe('SurfaceManager', () => {
  })

  it('empty surface yields empty nodes', () => {
-    const s = new Session(SessionId('empty'))
+    const s = Session.create(SessionId('empty'))
    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    s.append('step/start', { turn: 1, step: 1 })
    s.append('step/end', { turn: 1, step: 1 })
@@ -479,7 +479,7 @@ describe('SurfaceManager', () => {
        isError: false,
      }),
    }, { surfaceOp: 'append' })
-    const replayed = new Session(SessionId('replay'), [...original.events])
+    const replayed = Session.create(SessionId('replay'), [...original.events])
    expect(replayed.surface.nodes).toEqual([1, 2, 4])
    expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
  })
@@ -504,7 +504,7 @@ describe('SurfaceManager', () => {
  })

  it('replace with both ends at real nodes splices only the range', () => {
-    const s = new Session(SessionId('range'))
+    const s = Session.create(SessionId('range'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' }) // seq 0
@@ -533,7 +533,7 @@ describe('SurfaceManager', () => {
  })

  it('single-node replacement (start === end)', () => {
-    const s = new Session(SessionId('single'))
+    const s = Session.create(SessionId('single'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' }) // seq 0
@@ -559,7 +559,7 @@ describe('SurfaceManager', () => {
  })

  it('throws when replace start is not found', () => {
-    const s = new Session(SessionId('bad-start'))
+    const s = Session.create(SessionId('bad-start'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' }) // seq 0
@@ -580,7 +580,7 @@ describe('SurfaceManager', () => {
  })

  it('throws when replace end is not found', () => {
-    const s = new Session(SessionId('bad-end'))
+    const s = Session.create(SessionId('bad-end'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' }) // seq 0
@@ -601,7 +601,7 @@ describe('SurfaceManager', () => {
  })

  it('throws when start is after end', () => {
-    const s = new Session(SessionId('reversed'))
+    const s = Session.create(SessionId('reversed'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' }) // seq 0
@@ -626,7 +626,7 @@ describe('SurfaceManager', () => {
  })

  it('sourceEventSeqs is snapshot so caller mutation does not affect logged event', () => {
-    const s = new Session(SessionId('immutable'))
+    const s = Session.create(SessionId('immutable'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'source' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })
@@ -650,7 +650,7 @@ describe('SurfaceManager', () => {
  })

  it('replace starting at non-head position preserves surrounding order', () => {
-    const s = new Session(SessionId('mid-replace'))
+    const s = Session.create(SessionId('mid-replace'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' }) // seq 0
@@ -679,7 +679,7 @@ describe('SurfaceManager', () => {
  })

  it('surfaceOp replace object is snapshot so caller mutation is isolated', () => {
-    const s = new Session(SessionId('immutable-op'))
+    const s = Session.create(SessionId('immutable-op'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })
@@ -714,7 +714,7 @@ describe('deriveMessages with surface', () => {
  })

  it('surface path skips non-surface events (chunks, boundaries)', () => {
-    const s = new Session(SessionId('filter'))
+    const s = Session.create(SessionId('filter'))
    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } })
    s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 1, text: 'i' } })
@@ -738,7 +738,7 @@ describe('deriveMessages with surface', () => {
  })

  it('deriveMessages via surface respects replace (shadowed nodes are excluded)', () => {
-    const s = new Session(SessionId('compacted'))
+    const s = Session.create(SessionId('compacted'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'original' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })
@@ -760,7 +760,7 @@ describe('deriveMessages with surface', () => {
  })

  it('injected-context and steering/message appear on surface', () => {
-    const s = new Session(SessionId('ctx'))
+    const s = Session.create(SessionId('ctx'))
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'file changed' }], source: { kind: 'plugin', plugin: 'watcher' },
    }), { surfaceOp: 'append' })
@@ -780,7 +780,7 @@ describe('deriveMessages with surface', () => {

 describe('Session.append surface opts', () => {
  it('records sourceEventSeqs and surfaceOp on the event', () => {
-    const s = new Session(SessionId('opts'))
+    const s = Session.create(SessionId('opts'))
    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    s.append('step/start', { turn: 1, step: 1 })
    const event = s.append('assistant/message',
@@ -825,20 +825,20 @@ describe('Session.append surface opts', () => {
      { type: 'step/end', seq: 3, time: 4, data: { turn: 1, step: 1 } },
      { type: 'turn/end', seq: 4, time: 5, data: { turn: 1, reason: { kind: 'completed' } } },
    ]
-    const s = new Session(SessionId('nomessage'), seed)
+    const s = Session.create(SessionId('nomessage'), seed)
    // The empty assistant/message is on the surface but _deriveOneMessage returns null for it.
    expect(s.deriveMessages()).toHaveLength(0)
  })

  it('a non-surface event carries no surface fields', () => {
-    const s = new Session(SessionId('noopts'))
+    const s = Session.create(SessionId('noopts'))
    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    expect((s.events[0] as SessionEvent<SurfaceEventType>).sourceEventSeqs).toBeUndefined()
    expect((s.events[0] as SessionEvent<SurfaceEventType>).surfaceOp).toBeUndefined()
  })

  it('surfaceOp primitives are not cloned (they are immutable)', () => {
-    const s = new Session(SessionId('prim'))
+    const s = Session.create(SessionId('prim'))
    const event = s.append('assistant/message', {
      turn: 1, step: 1,
      message: createMessage({
@@ -949,7 +949,7 @@ describe('surface type guards', () => {

 describe('SurfaceManager.replaceGeneration', () => {
  it('folds the pending log delta on access and counts replaces', () => {
-    const s = new Session(SessionId('gen'))
+    const s = Session.create(SessionId('gen'))
    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    s.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'one' }], source: { kind: 'user' },
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
 README.md: d4e0f69323b7326fc7575834bf48a5aeeec0777e
-README.zh.md: 47290335d725083fc46ef4f2ee09b09263276788
+README.zh.md: 2b96c6baa612d760b3497d5b9fe01b26c6a9dd91
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -39,13 +39,13 @@

 ### 扩展点

- 段提供方：工具包（package）拥有跨调用引导（`tool:bash`、`tool:read` 等）；此插件拥有 `harness:identity` 与 `deployment:persona`。
+- 段提供方：工具包拥有跨调用引导（`tool:bash`、`tool:read` 等）；此插件拥有 `harness:identity` 与 `deployment:persona`。
 - 上下文提供方：策略及其他变化状态的归属方贡献完整的当前事实，而不改变稳定的系统提示词。
 - 变量提供方：agent loop 注册 `model` 与 `cwd`；任何插件都可以注册自己拥有的事实（未来的 `date`、git 状态等）。
 - 工具 schema 提供方：`ToolRegistry` 自动将自身注册为工具提供方。
 - [`system-prompt/assemble` waterfall](#live-events)：按调用方协作式修改或替换组装结果。

-设计原理：[提示词变量 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)。
+设计原理：[提示词变量 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)。

 ## 模型体验

--- a/packages/core/system-prompt/package.json
+++ b/packages/core/system-prompt/package.json
@@ -21,9 +21,7 @@
  "files": [
    "lib/index.js",
    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
 README.md: 80ea3cc93437d48a7ea0ffba0ff4d2ef2407755f
-README.zh.md: 1f0791c5df7afd4a3479afdd827c4fc148cf8883
+README.zh.md: 691d2f2fcccdaa1bcab5343b2fce661d9c99e8ad
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -17,10 +17,10 @@ tools:

 ### 公开 API

- `ctx.tools.register(definition: ToolDefinition): () => void`：注册一个受信任、带类型的同进程定义，其中必须包含规范的 `output` 声明。所在层由调用上下文的作用域决定：普通插件上下文会全局注册；agent 的 `agent.ctx` 只为该 agent 注册，并在此处遮蔽同名全局工具。同一层内名称重复会抛出；非原生模式还会拒绝保留的 `run_code` 传输名称。缺失或不受支持的输出声明，以及非正数或非有限的 `timeoutMs`，都会使注册失败。可选的同步 `finalizeContent` 回调会在调用开始时创建快照；在所有流水线结果规范化之后，它只能替换最终面向模型的内容，包括实体化其他结果字段时发现的错误。随调用 fiber dispose（释放资源）。
+- `ctx.tools.register(definition: ToolDefinition): () => void`：注册一个受信任、带类型的同进程定义，其中必须包含规范的 `output` 声明。所在层由调用上下文的作用域决定：普通插件上下文会全局注册；agent 的 `agent.ctx` 只为该 agent 注册，并在此处遮蔽同名全局工具。同一层内名称重复会抛出；非原生模式还会拒绝保留的 `run_code` 传输名称。缺失或不受支持的输出声明，以及非正数或非有限的 `timeoutMs`，都会使注册失败。可选的同步 `finalizeContent` 回调会在调用开始时创建快照；在所有流水线结果规范化之后，它只能替换最终面向模型的内容，包括实体化其他结果字段时发现的错误。随调用 fiber dispose（资源释放）。
 - `ctx.tools.restrict(filter)`：对全局工具应用 agent 作用域的允许／拒绝掩码；从普通上下文调用会抛出。筛选器在注册时创建快照；多个掩码取交集，随后再合并作用域本地工具。拒绝掩码会接纳后来出现且未点名的全局工具，而允许掩码会排除后来出现的名称。未知、本地或保留名称以及空筛选器都会被拒绝。这是实时可见性组合，不是权限边界；参见[作用域安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined`：按某个作用域所见的结果解析（应用遮蔽；被限制掉的全局工具视为不存在）。呈现器会传入发起调用的 agent，使卡片与实际执行内容一致。
- `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]`：返回该作用域可见的所有 schema（不含 `execute` 函数）。已交付工具的 schema 收录在 [docs/tool-catalog.md](../../../docs/tool-catalog.md) 中；该目录通过启动每个工具插件并采集此方法的结果生成（参见[工具 schema 目录 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)）。
+- `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]`：返回该作用域可见的所有 schema（不含 `execute` 函数）。已交付工具的 schema 收录在 [docs/tool-catalog.md](../../../docs/tool-catalog.md) 中；该目录通过启动每个工具插件并采集此方法的结果生成（参见[工具 schema 目录 Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)）。
 - `ctx.tools.guard(guard: ToolGuard): () => void`：在 `tools/pre-execute` 之后注册单调同步执行守卫：返回理由会拒绝调用，返回 `undefined` 则保持原决定。普通上下文守卫全局生效；`agent.ctx` 守卫只对该 agent 生效。后续 waterfall（瀑布式事件）监听器无法将守卫的拒绝重新变为允许。随调用 fiber dispose。
 - `ctx.tools.execute(exec)`：以无损方式快照并冻结参数，分配不透明 token，运行完整的策略／分发／结果流水线，然后在最终观测前独立快照权威结果。无效参数会进入同一结果路径，但不会到达策略或工具主体。环绕包装层只能替换 `signal`；注册表会在调用主体前立即重新融合调用方的原始信号。
 - `ctx.tools.executionMode(exec)`：返回 `parallel` 的唯一条件是可见定义的 `isConcurrencySafe(exec.arguments)` 分类器恰好返回 `true`；未知、隐藏、未声明、无效或抛出异常的分类结果均为独占。
@@ -61,7 +61,7 @@ tools:

 ### 类型化工具参数 schema

-第一方插件作者可以使用本包（package）导出的 `defineTool()` 辅助函数定义类型化工具参数 schema：
+第一方插件作者可以使用本包导出的 `defineTool()` 辅助函数定义类型化工具参数 schema：

 ```ts
 import { readFile } from 'node:fs/promises'
@@ -131,7 +131,7 @@ agent loop 将连续的 `parallel` 调用归入有界滚动池，并把每个 `e

 #### 模型看到的内容

-在普通模式下，模型会看到每个可见定义的确切名称、描述和 JSON schema；已交付定义记录在生成的[工具包映射和 schema 章节](../../../docs/tool-catalog.md#tool-package-map)中。agent 作用域的限制、遮蔽和扩展注册会改变该 agent 的最终工具集合。
+在普通模式下，模型会看到每个可见定义的确切名称、描述和 JSON Schema；已交付定义记录在生成的[工具包映射和 schema 章节](../../../docs/tool-catalog.md#tool-package-map)中。agent 作用域的限制、遮蔽和扩展注册会改变该 agent 的最终工具集合。

 #### Token 影响

@@ -182,7 +182,7 @@ The available tools:

 #### KV Cache 影响

-仅追加；新的可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+仅追加；新的可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。

 ## 已知限制与暂缓事项

--- a/packages/core/tools/package.json
+++ b/packages/core/tools/package.json
@@ -26,9 +26,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/types/**/*.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
--- a/packages/core/tools/tests/code-mode.spec.ts
+++ b/packages/core/tools/tests/code-mode.spec.ts
@@ -1278,7 +1278,7 @@ describe('the run_code dispatch bridge', () => {
        return Promise.resolve(observedDepth)
      },
    }))
-    const session = new Session(SessionId('deep-code-arguments'))
+    const session = Session.create(SessionId('deep-code-arguments'))
    const agent = { session } as Agent
    runtime.behavior = async (request) => {
      let nested: JsonValue = 'leaf'
@@ -1441,7 +1441,7 @@ describe('the run_code dispatch bridge', () => {
  })

  it('a tool/code-dispatch event never derives a model message', () => {
-    const session = new Session(SessionId('code-mode-derive'))
+    const session = Session.create(SessionId('code-mode-derive'))
    session.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
    }), { surfaceOp: 'append' })