From 7020c7e122190a2c164910f0847c53749995f369 Mon Sep 17 00:00:00 2001
From: "yx.zhang" <yx.zhang@yxzhangdeMacBook-Pro.local>
Date: Tue, 1 Sep 2026 18:25:20 +0800
Subject: [PATCH 01/37] feat(web): superellipse corners and hairline elevation
 strokes

Apply global visual polish across the web client: corner-shape:
superellipse(1.5) with corner-shape: round pairing for full circles,
elevation tokens that draw 0.5px stroke outlines inside box-shadow for
floating surfaces, 0.5px hairline borders and divider lines for
neutral-token strokes, and tuned stroke contrast plus larger radii for
menus, settings panels, and cards. Stylesheet-scan specs in ui-theme
reject unpaired circles, border+shadow mixes, and 1px neutral hairlines
repo-wide.

Closes #3287
---
 ...-01-web-elevation-stroke-shadows.i18n.yaml |   6 +
 ...2026-09-01-web-elevation-stroke-shadows.md |  42 +++++++
 ...6-09-01-web-elevation-stroke-shadows.zh.md |  42 +++++++
 ...eb-superellipse-corner-smoothing.i18n.yaml |   6 +
 ...09-01-web-superellipse-corner-smoothing.md |  34 ++++++
 ...01-web-superellipse-corner-smoothing.zh.md |  34 ++++++
 docs/web-styling.i18n.yaml                    |   4 +-
 docs/web-styling.md                           |   3 +
 docs/web-styling.zh.md                        |   3 +
 .../locale/src/client/LanguageRow.module.css  |   2 +-
 .../src/client/AgentPresetSection.module.css  |  30 +++--
 .../src/client/ApprovalPanel.module.css       |   1 +
 .../src/AttachmentRail.module.css             |   9 +-
 .../src/ImageLightbox.module.css              |   3 +-
 .../ui-attachment/src/MessageImage.module.css |   4 +-
 .../src/client/chat/ChatView.module.css       |   6 +-
 .../src/client/chat/ContextBody.module.css    |   2 +-
 .../client/chat/GenericCommandCard.module.css |   2 +-
 .../src/client/chat/TurnNavigator.module.css  |   4 +-
 .../chat/TurnProcessNodeView.module.css       |   2 +-
 .../src/client/chat/TurnUsagePanel.module.css |   9 +-
 .../client/details/DetailsPanel.module.css    |   5 +-
 .../settings/TranscriptViewRow.module.css     |   2 +-
 .../src/client/PopupSelectView.module.css     |  13 +-
 .../src/client/queue/QueueDock.module.css     |   7 +-
 .../settings/EnterBehaviorRow.module.css      |   2 +-
 .../client/skeleton/ContextMeter.module.css   |   9 +-
 .../skeleton/ConversationRoot.module.css      |   4 +-
 .../src/client/skeleton/HeroShell.module.css  |   4 +-
 .../src/client/skeleton/InputBar.module.css   |  16 ++-
 .../src/client/skeleton/TodoPanel.module.css  |   2 +-
 .../src/client/DirectoryBrowser.module.css    |   8 +-
 .../ui-goal/src/client/GoalBar.module.css     |   5 +-
 .../src/client/MenuView.module.css            |   9 +-
 .../src/client/JobListAction.module.css       |   7 +-
 .../ui-layout/src/client/AppFrame.module.css  |   6 +-
 .../client/MessageFeedbackActions.module.css  |   7 +-
 .../src/client/ModelSelect.module.css         |   7 +-
 .../src/client/PermissionRow.module.css       |   2 +-
 .../src/client/PlanModeControl.module.css     |   1 +
 .../ui-primitives/src/Button.module.css       |   2 +-
 .../client/ui-primitives/src/Input.module.css |   2 +-
 .../client/ui-primitives/src/Menu.module.css  |  13 +-
 .../client/ui-primitives/src/Modal.module.css |   6 +-
 .../ui-primitives/src/StateDot.module.css     |   2 +
 .../src/TerminalBlock.module.css              |   2 +-
 .../src/markdown/JsonBlock.module.css         |   2 +-
 .../src/markdown/MarkdownText.module.css      |   6 +-
 .../client/ScheduleCatalogAction.module.css   |   8 +-
 .../src/client/SettingsRoot.module.css        |   9 +-
 .../src/client/ModelsSection.module.css       |  23 ++--
 .../PluginInventorySettingsTab.module.css     |  20 ++--
 .../src/client/PluginCard.module.css          |   9 +-
 .../client/PluginsSettingsSection.module.css  |   2 +-
 .../SubagentModelSelectionCard.module.css     |   5 +-
 .../src/client/fields.module.css              |   6 +-
 .../src/client/SidebarRoot.module.css         |   3 +-
 .../ui-skill/src/client/SkillRow.module.css   |   7 +-
 .../client/SubagentHeaderLineage.module.css   |   9 +-
 .../SubagentReadOnlyComposer.module.css       |   2 +-
 packages/client/ui-theme/README.i18n.yaml     |   4 +-
 packages/client/ui-theme/README.md            |   6 +-
 packages/client/ui-theme/README.zh.md         |   6 +-
 .../src/client/AppearanceRow.module.css       |   6 +-
 .../src/client/FontSizeRow.module.css         |   2 +-
 packages/client/ui-theme/src/client/styles.ts |   2 +
 .../ui-theme/src/styles/corner-shape.css      |  26 ++++
 .../src/styles/gradient-shadow-text.css       |  14 +++
 .../tests/client-styles.client.spec.ts        |   1 +
 .../tests/corner-shape-styles.client.spec.ts  |  80 +++++++++++++
 .../tests/elevation-styles.client.spec.ts     | 112 ++++++++++++++++++
 .../tests/scrollbar-styles.client.spec.ts     |  86 +-------------
 .../client/ui-theme/tests/stylesheet-scan.ts  |  91 ++++++++++++++
 .../src/client/tool/ToolCallTree.module.css   |   2 +-
 .../components/AskQuestionCard.module.css     |   2 +-
 .../client/tool/components/ToolRow.module.css |   9 +-
 .../tool/toolviews/bash-sample.module.css     |   9 +-
 .../src/client/TrajectoryCell.module.css      |   2 +-
 .../src/client/TrajectoryTable.module.css     |  23 ++--
 .../src/client/TrajectoryTimeline.module.css  |   6 +-
 .../src/client/TrajectoryToolbar.module.css   |   5 +-
 .../src/client/PlanReviewPanel.module.css     |   1 +
 .../src/client/QuestionComposer.module.css    |  10 +-
 .../src/client/WorkflowRunPanel.module.css    |   1 +
 .../src/client/rows/Rows.module.css           |   2 +-
 .../client/rows/WorkspaceBrowser.module.css   |   8 +-
 packages/client/web/src/boot-page.module.css  |   1 +
 .../src/client/TeamAction.module.css          |  11 +-
 .../src/client/CordisDefineRow.module.css     |   7 +-
 .../src/client/CordisPanel.module.css         |  14 ++-
 .../src/client/CordisRunRow.module.css        |   6 +-
 .../src/client/HeaderAction.module.css        |   2 +-
 92 files changed, 772 insertions(+), 287 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
 create mode 100644 .agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
 create mode 100644 .agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md
 create mode 100644 .agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md
 create mode 100644 packages/client/ui-theme/src/styles/corner-shape.css
 create mode 100644 packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts
 create mode 100644 packages/client/ui-theme/tests/elevation-styles.client.spec.ts
 create mode 100644 packages/client/ui-theme/tests/stylesheet-scan.ts

diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
new file mode 100644
index 0000000000..04bab8384f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
+2026-09-01-web-elevation-stroke-shadows.md: 9d5789038267d4fc5693cc46bb8870a4410ce080
+2026-09-01-web-elevation-stroke-shadows.zh.md: 9ad34a6f15098710ee4cee34142c95c4c60e27fe
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
new file mode 100644
index 0000000000..9d57890382
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
@@ -0,0 +1,42 @@
+# Agent Note: Web elevation — hairline stroke drawn in shadow
+
+Status: implemented
+
+English | [中文](2026-09-01-web-elevation-stroke-shadows.zh.md)
+
+## Problem
+
+Elevated web-client surfaces — menus, popovers, modals, panels, floating buttons, the composer — each paired a real `border: 1px solid <neutral token>` with a `--dsw-shadow-lv2`/`lv3` shadow. The border consumes layout (1px per side, and it is the UA-default replacement on `<button>` elements), the light theme drew most floats with no stroke at all (`--dsw-alias-border-inverted` is transparent in light) while `lv3` faked one with a blurred 1px ring, and the composer wore a broad soft `lv2` patch that read as a smudge rather than a lifted surface. The unpacked ChatGPT desktop (Codex) UI instead draws elevation as one `box-shadow` list: a 0.5px hairline stroke plus two faint soft layers (`--elevation-stroke`/`--elevation-sidebar`/`--elevation-prominent`), with `border: 0` on the surface.
+
+## Decision
+
+`gradient-shadow-text.css` (the ui-theme shadow owner) defines the elevation tokens beside the `--dsw-shadow-lv*` scale:
+
+- `--dsw-elevation-stroke-color` — the hairline color, defaulting to `--dsw-alias-border-l4` (black 16% light, white 20% dark); components rebind it per surface or state, and every menu-fill surface (`--dsw-specific-menu` background) rebinds the lighter `--dsw-alias-border-l2` so dropdown menus keep a quieter stroke than panels and buttons.
+- `--dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color)` — the stroke alone, used standalone by inline cards that want only an outline (the plugin-inventory card).
+- `--dsw-elevation-panel` / `--dsw-elevation-prominent` — the stroke plus two faint soft layers (3px directional + 16/20px glow at 2–5% black), panel for small floating widgets and cards, prominent for floats, and soft — larger blur at lower alpha — for the composer.
+
+Converted surfaces set `border: 0` and one elevation shadow: every `--dsw-shadow-lv3` float (Menu, Modal, popup selects, model select, usage/context popovers, feedback actions, schedule/job popovers, subagent lineage, settings panel, cordis panel, experimental team panel) takes prominent, and the lv2 surfaces (scroll-to-bottom button, turn-preview card, attachment-rail arrows, question composer, trajectory tooltip) take panel. The composer card takes the soft tier with the l1 stroke rebind, and its workspace-trigger state sets the stroke color `transparent` instead of the former `border-color: transparent`. Dark theme needs no shadow overrides: the soft layers are near-invisible there and the stroke carries the separation, as in Codex.
+
+`packages/client/ui-theme/tests/elevation-styles.client.spec.ts` pins the token composition and scans every stylesheet under `packages/`: a rule pairing an lv/elevation `box-shadow` with a `--dsw-alias-border-*` border fails, and every `solid` border on a neutral `--dsw-alias-border-*` token must be `0.5px` wide. Deliberate keeps: Toast and HoverCard (inverted fills where a theme-following stroke is meaningless), ImageLightbox (bare image), and the warn-bordered approval/plan panels, whose state-colored borders stay real borders and pass the scan.
+
+Flat widgets keep real borders at hairline width: every neutral-token `1px solid` border — buttons (the shared outline variant, add/retry/inspect buttons), inputs, inline cards, code blocks, and the settings row separators — is `0.5px solid`, with full-box strokes deepened to `--dsw-alias-border-l4` (buttons one step lighter at `--dsw-alias-border-l3`) while row separators keep `--dsw-alias-border-l2`; state logic (`border-color` swaps on focus/hover) is unchanged. Separators drawn as filled boxes take the same weight: the 1px-tall or 1px-wide lines with a border-token background (menu separators, the conversation header seam, markdown `hr`, the tool IO dividers, the trajectory rail, the directory-browser divider) are 0.5px, and the context-injection divider that read the never-defined `--dsw-alias-line-secondary` (so it never rendered) now draws `0.5px solid var(--dsw-alias-border-l2)`. Chromium paints sub-device-pixel borders as one device pixel, so 1x displays render exactly the former line and 2x displays get the hairline. Dashed affordances stay 1px (a 0.5px dash pattern degrades), and the two border-drawn spinner rings keep their track width through the spec's explicit allowlist.
+
+## Alternatives considered
+
+**Keeping 1px real borders and only softening the shadows.** Leaves the layout-consuming border, the light-theme stroke gap on `border-inverted` floats, and the double outline wherever both existed; the stroke-in-shadow form is what produces the crisp Codex edge.
+
+**A 1px stroke instead of 0.5px.** The Codex elevation stroke is 0.5px; at 2x displays it renders one physical pixel, and on 1x it blends lighter, which is the intended hairline. 1px reads as the old border.
+
+**Drawing flat-widget hairlines as box-shadow strokes too.** Buttons and inputs swap `border-color` on hover and focus and several pair a box-shadow focus ring; moving their stroke into `box-shadow` would collide with those rings (one property) and rewrite every state rule, while `0.5px solid` keeps the whole state logic and changes only the weight.
+
+**Suppressing the composer trigger stroke with `box-shadow: none`.** Also drops the soft layers the trigger state keeps today; rebinding `--dsw-elevation-stroke-color: transparent` removes exactly the stroke.
+
+**Converting Toast/HoverCard too.** Their fills are inverted relative to the theme, so the theme-following stroke color is invisible-or-wrong on them; they keep `lv3` until an inverted-surface stroke token exists.
+
+## Consequences
+
+- Every converted surface gains a hairline outline in the light theme (most floats previously had none) and loses 1px of border from its box; the visual size change is at most 2px on small buttons and imperceptible on panels.
+- The neutral-border-plus-shadow pairing is now rejected by the ui-theme elevation spec, so a new elevated surface must choose the elevation tokens; the rule lives in [docs/web-styling.md](../../../../docs/web-styling.md).
+- The composer's broad `lv2` patch becomes stroke + tight glow; its dark stroke keeps the figma one-notch-weaker value through the rebind.
+- `--dsw-shadow-lv1`/`lv1-blur` currently have no consumer and `lv2`/`lv3` remain only on the deliberate keeps; the scale stays for inverted and bespoke surfaces.
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
new file mode 100644
index 0000000000..9ad34a6f15
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: Web elevation — hairline stroke drawn in shadow
+
+Status: implemented
+
+[English](2026-09-01-web-elevation-stroke-shadows.md) | 中文
+
+## Problem
+
+Web 客户端的高层级表面——菜单、浮层、对话框、面板、悬浮按钮、输入框——原先都把真 `border: 1px solid <中性 token>` 与 `--dsw-shadow-lv2`/`lv3` 投影配对。border 占布局（每侧 1px，且在 `<button>` 上是对 UA 默认边框的替换）；浅色主题下多数浮层实际没有描边（`--dsw-alias-border-inverted` 在浅色下是透明的），靠 `lv3` 里模糊的 1px 环冒充；输入框则披着一大片柔和的 `lv2` 投影，读起来更像污渍而非悬浮表面。解包的 ChatGPT 桌面端（Codex）UI 改用单个 `box-shadow` 列表绘制 elevation：0.5px 发丝描边加两层极淡柔光（`--elevation-stroke`/`--elevation-sidebar`/`--elevation-prominent`），表面本身 `border: 0`。
+
+## Decision
+
+`gradient-shadow-text.css`（ui-theme 的阴影归属地）在 `--dsw-shadow-lv*` 阶旁定义 elevation token：
+
+- `--dsw-elevation-stroke-color`——发丝描边颜色，默认 `--dsw-alias-border-l4`（浅色黑 16%、深色白 20%）；组件可按表面或状态重绑：所有菜单面（`--dsw-specific-menu` 背景）与输入框重绑最浅的 `--dsw-alias-border-l1`，两者都比面板与按钮安静。
+- `--dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color)`——单独的描边，供只要轮廓的行内卡片独立使用（插件清单卡片）。
+- `--dsw-elevation-panel` / `--dsw-elevation-prominent`——描边加两层极淡柔光（3px 方向光 + 16/20px 辉光，黑 2–5%），panel 用于小型悬浮部件与卡片，prominent 用于浮层，soft——更大模糊、更低透明度——用于输入框。
+
+被转换的表面设 `border: 0` 加一个 elevation 投影：所有 `--dsw-shadow-lv3` 浮层（Menu、Modal、弹出选择、模型选择、用量/上下文浮层、反馈操作条、日程/任务浮层、子代理谱系、设置面板、cordis 面板、实验性 team 面板）取 prominent；lv2 表面（回到底部按钮、回合预览卡、附件栏箭头、问题 composer、轨迹 tooltip）取 panel。输入框卡片取 soft 档并重绑 l1 描边，其 workspace-trigger 态把描边色设为 `transparent`，替代原先的 `border-color: transparent`。深色主题无需投影覆盖：柔光在深色下几乎不可见，分离由描边承担，与 Codex 相同。
+
+`packages/client/ui-theme/tests/elevation-styles.client.spec.ts` 钉住 token 组成并扫描 `packages/` 下全部样式表：lv/elevation `box-shadow` 与 `--dsw-alias-border-*` border 配对的规则即失败；中性 `--dsw-alias-border-*` token 上的每个 `solid` border 必须为 `0.5px` 宽。有意保留：Toast 与 HoverCard（反色填充，跟随主题的描边色在其上无意义）、ImageLightbox（裸图片）、warn 描边的审批/计划面板——状态色 border 保持真 border，扫描放行。
+
+平面部件保留真 border 但取发丝线宽度：所有中性 token 的 `1px solid` border——按钮（共享 outline 变体、添加/重试/inspect 按钮）、输入框、行内卡片、代码块与设置行分割线——改为 `0.5px solid`，整框描边加深为 `--dsw-alias-border-l4`（按钮浅一档取 `--dsw-alias-border-l3`），行分割线保持 `--dsw-alias-border-l2`；状态逻辑（focus/hover 换 `border-color`）不变。以填充盒绘制的分隔线取同一粗细：高或宽为 1px、背景用 border token 的线（菜单分隔、对话标题栏接缝、markdown `hr`、工具 IO 分隔、轨迹竖轨、目录浏览器分隔）改为 0.5px；上下文注入分隔线原先读取从未定义的 `--dsw-alias-line-secondary`（因此从未渲染），现在绘制 `0.5px solid var(--dsw-alias-border-l2)`。Chromium 把亚设备像素 border 绘制为一个设备像素，因此 1x 屏与原先渲染完全一致，2x 屏得到发丝线。dashed 记号保持 1px（0.5px 虚线图案会退化），两个用 border 画的 spinner 圆环经 spec 显式豁免保留轨道宽度。
+
+## Alternatives considered
+
+**保留 1px 真 border、只调柔投影。** 留下占布局的 border、浅色主题 `border-inverted` 浮层的描边缺口，以及两者并存处的双轮廓；描边入投影正是产生 Codex 式锐利边缘的形式。
+
+**用 1px 而非 0.5px 描边。** Codex 的 elevation 描边是 0.5px；2x 屏渲染为一物理像素，1x 屏混合得更浅，正是发丝线意图。1px 读起来就是原来的 border。
+
+**平面部件的发丝线也用 box-shadow 描边画。** 按钮与输入框在 hover/focus 时切换 `border-color`，多处还配 box-shadow 焦点环；把描边挪进 `box-shadow`（单一属性）会与焦点环冲突并重写全部状态规则，而 `0.5px solid` 保留整套状态逻辑，只改粗细。
+
+**composer trigger 态用 `box-shadow: none` 抑制描边。** 会连带丢掉该状态今天保留的柔光；重绑 `--dsw-elevation-stroke-color: transparent` 恰好只去掉描边。
+
+**Toast/HoverCard 一并转换。** 其填充相对主题反色，跟随主题的描边色在其上不可见或错误；在出现反色表面描边 token 之前保留 `lv3`。
+
+## Consequences
+
+- 每个被转换表面在浅色主题下获得发丝轮廓（多数浮层此前没有），盒子少了 1px border；视觉尺寸变化在小按钮上至多 2px，面板上不可察觉。
+- 中性 border 加投影的配对现被 ui-theme elevation spec 拒绝，新的高层级表面必须选用 elevation token；规则记录于 [docs/web-styling.md](../../../../docs/web-styling.zh.md)。
+- 输入框的大片 `lv2` 变为描边加收紧的辉光；深色描边经重绑保留 figma 低一档取值。
+- `--dsw-shadow-lv1`/`lv1-blur` 目前无消费方，`lv2`/`lv3` 只剩有意保留者；该阶为反色与定制表面继续存在。
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.i18n.yaml b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.i18n.yaml
new file mode 100644
index 0000000000..5a179791e3
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md
+2026-09-01-web-superellipse-corner-smoothing.md: 1da15664d4c4d92476d7f9414b27c0812665bd60
+2026-09-01-web-superellipse-corner-smoothing.zh.md: f2ff1690511fa530b66c53b4e62a53d1af0283ff
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md
new file mode 100644
index 0000000000..1da15664d4
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md
@@ -0,0 +1,34 @@
+# Agent Note: Web superellipse corner smoothing
+
+Status: implemented
+
+English | [中文](2026-09-01-web-superellipse-corner-smoothing.zh.md)
+
+## Problem
+
+Every rounded surface in the web client — cards, composer, buttons, popovers — draws its corners as plain circular arcs, which read as visibly harder than the smooth (squircle-like) corners current desktop chat UIs ship. An unpacked-`app.asar` survey of the ChatGPT desktop app's Codex UI found the smoothness comes from CSS `corner-shape: superellipse(1.5)` applied behind an `@supports` guard to every rounded-corner utility class except full-round (`rounded-full`), not from larger radii or masking tricks. This client has no utility classes: `border-radius` values are px literals spread across CSS Modules in every client package, so there is no single class list to attach the property to, and full-round shapes (`border-radius: 50%` circles, 999px pills) must keep circular arcs — a superellipse deforms a circle into a squircle, so a border-drawn spinner would visibly wobble, and it squares off capsule ends.
+
+## Decision
+
+`packages/client/ui-theme/src/styles/corner-shape.css` is a global sheet mounted by ui-theme's client entry (after `base.css`). Inside `@supports (corner-shape: superellipse(1.5))` it defines `--dsw-corner-shape: superellipse(1.5)` on `:root` and applies `corner-shape: var(--dsw-corner-shape)` through `*, *::before, *::after` — `corner-shape` does not inherit, so the universal selector is the mechanism that reaches every rounded surface without a utility-class system. Engines without `corner-shape` keep circular corners because both declarations live inside the guard. `superellipse(1.5)` sits between `round` (`superellipse(1)`) and `squircle` (`superellipse(2)`), matching the Codex UI's value.
+
+Full-round shapes opt back out at their declaration: every `border-radius` of `50%`, `100%`, or a pill radius (≥ 99px) pairs `corner-shape: round` in the same rule of its owning component sheet. The pairing is enforced by `packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts`, which scans every stylesheet under `packages/` (the shared scan helpers live in `tests/stylesheet-scan.ts`, extracted from the scrollbar spec); the same spec pins the guard and the universal application in `corner-shape.css`. Component-local radius indirections (`--dsl-*-radius`) all hold values far below the pill threshold, so the lexical scan covers current usage.
+
+The Codex UI also multiplies its radius tokens by 1.25 alongside the shape change; this client has no radius tokens (px literals per component), so radii are unchanged and only the corner curvature moves.
+
+## Alternatives considered
+
+**A radius token system first, then per-token application (the literal Codex structure).** Faithful, but converting ~130 px-literal radii across every client package into tokens is a large refactor serving no other current need; the universal selector reaches the same surfaces with one rule.
+
+**Applying superellipse to full-round shapes too (no opt-outs).** Fewer declarations, but spinners built from `border-radius: 50%` borders wobble when the rotating shape is not a circle, and capsule ends square off; the Codex UI equally excludes `rounded-full` from `corner-shape`.
+
+**Subtree opt-out via `--dsw-corner-shape: round` instead of per-declaration `corner-shape: round`.** The custom property inherits, so a pill's rounded descendants would silently lose smoothing; the explicit per-rule declaration keeps the opt-out exactly as wide as the full-round shape and is what the pairing spec can check.
+
+**Scaling radii by 1.25 like Codex.** Requires the token system above; the curvature change alone already delivers the smoothness, and radii stay as designed.
+
+## Consequences
+
+- On engines with `corner-shape` (Chromium ≥ 139 behind no flag), every rounded corner in the client curves along `superellipse(1.5)`; other engines render exactly as before, with no fallback code.
+- New full-round shapes must pair `corner-shape: round` or the ui-theme corner-shape spec fails; the rule is stated in [docs/web-styling.md](../../../../docs/web-styling.md) and costs one extra declaration per circle or pill.
+- The universal selector adds one non-inherited property to every element; the declaration is a constant and profiling concerns are theoretical at current tree sizes.
+- A rounded box whose radius equals half its height (an implicit pill under 99px) still receives the superellipse; the scan cannot see computed geometry, and such ends read as intentional smoothing rather than distortion.
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md
new file mode 100644
index 0000000000..f2ff169051
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md
@@ -0,0 +1,34 @@
+# Agent Note: Web superellipse corner smoothing
+
+Status: implemented
+
+[English](2026-09-01-web-superellipse-corner-smoothing.md) | 中文
+
+## Problem
+
+Web 客户端里每个圆角表面——卡片、输入框、按钮、浮层——都以普通圆弧绘制圆角，观感明显硬于当前桌面聊天 UI 普遍采用的平滑（类 squircle）圆角。对 ChatGPT 桌面应用 Codex UI 解包 `app.asar` 的调研发现，其平滑感来自在 `@supports` 守卫内对除正圆（`rounded-full`）之外的所有圆角工具类应用 CSS `corner-shape: superellipse(1.5)`，而非更大的半径或遮罩技巧。本客户端没有工具类：`border-radius` 以 px 字面量散布在各客户端包的 CSS Modules 中，没有可以统一挂载该属性的类列表；而正圆形状（`border-radius: 50%` 的圆、999px 胶囊）必须保持圆弧——超级椭圆会把圆变形为 squircle，用 border 绘制的加载圈旋转时会明显晃动，胶囊两端也会变方。
+
+## Decision
+
+`packages/client/ui-theme/src/styles/corner-shape.css` 是由 ui-theme 客户端 entry 挂载的全局样式表（位于 `base.css` 之后）。它在 `@supports (corner-shape: superellipse(1.5))` 内于 `:root` 定义 `--dsw-corner-shape: superellipse(1.5)`，并通过 `*, *::before, *::after` 应用 `corner-shape: var(--dsw-corner-shape)`——`corner-shape` 不继承，通配选择器正是在没有工具类系统的前提下触达每个圆角表面的机制。两条声明都在守卫内，因此不支持 `corner-shape` 的引擎保持普通圆弧。`superellipse(1.5)` 介于 `round`（`superellipse(1)`）与 `squircle`（`superellipse(2)`）之间，与 Codex UI 取值一致。
+
+正圆形状在其声明处退出：每个取值为 `50%`、`100%` 或胶囊半径（≥ 99px）的 `border-radius`，都在所属组件样式表的同一规则内配对 `corner-shape: round`。该配对由 `packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts` 强制，它扫描 `packages/` 下的全部样式表（共享扫描辅助函数位于 `tests/stylesheet-scan.ts`，自 scrollbar spec 抽出）；同一 spec 也钉住 `corner-shape.css` 的守卫与通配应用。组件局部半径变量（`--dsl-*-radius`）取值都远低于胶囊阈值，因此词法扫描覆盖当前用法。
+
+Codex UI 在改变曲线的同时还把半径 token 乘以 1.25；本客户端没有半径 token（各组件 px 字面量），故半径不变，只改变圆角曲率。
+
+## Alternatives considered
+
+**先建半径 token 系统，再按 token 应用（照搬 Codex 结构）。** 更忠实，但把所有客户端包约 130 处 px 字面量半径改造成 token 是没有其他现实需求的大重构；通配选择器用一条规则触达同样的表面。
+
+**对正圆形状也应用超级椭圆（不设豁免）。** 声明更少，但用 `border-radius: 50%` border 绘制的加载圈在形状不是圆时旋转会晃动，胶囊两端会变方；Codex UI 同样把 `rounded-full` 排除在 `corner-shape` 之外。
+
+**用子树级 `--dsw-corner-shape: round` 替代逐声明 `corner-shape: round` 豁免。** 自定义属性会继承，胶囊的圆角后代会静默失去平滑；逐规则显式声明让豁免范围恰好等于正圆形状本身，也是配对 spec 能检查的形式。
+
+**像 Codex 一样把半径乘 1.25。** 需要上述 token 系统；仅曲率变化已带来平滑感，半径维持设计值。
+
+## Consequences
+
+- 在支持 `corner-shape` 的引擎（Chromium ≥ 139，无需 flag）上，客户端每个圆角都沿 `superellipse(1.5)` 弯曲；其他引擎渲染与之前完全一致，没有回退代码。
+- 新增正圆形状必须配对 `corner-shape: round`，否则 ui-theme 的 corner-shape spec 失败；该规则记录于 [docs/web-styling.md](../../../../docs/web-styling.zh.md)，每个圆或胶囊多付一条声明。
+- 通配选择器给每个元素增加一个不继承的属性；声明是常量，在当前树规模下性能顾虑属于理论层面。
+- 半径等于自身高度一半的圆角盒（低于 99px 的隐式胶囊）仍会得到超级椭圆；扫描看不到计算后几何，此类端部读作有意的平滑而非变形。
diff --git a/docs/web-styling.i18n.yaml b/docs/web-styling.i18n.yaml
index fac44882a4..536aabb6f9 100644
--- a/docs/web-styling.i18n.yaml
+++ b/docs/web-styling.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 docs/web-styling.md
-web-styling.md: 5296cc7f83f712532262eadda6da098ae9f63ec7
-web-styling.zh.md: a2ba074619a7e2737c7e9286d2aeaa90611ac633
+web-styling.md: 1fa79acba6289f7364846909a996f504785ff628
+web-styling.zh.md: 126011f0c8e4ff6832daa46e3c5096899a632171
diff --git a/docs/web-styling.md b/docs/web-styling.md
index 5296cc7f83..1fa79acba6 100644
--- a/docs/web-styling.md
+++ b/docs/web-styling.md
@@ -19,6 +19,9 @@ Global style sheets belong in `ui-theme/src/styles/`. Component styles live besi
 - Keep source text, terminal output, and diff lines unwrapped when their component contract requires column preservation; use the shared scrollbar styles rather than component-specific scrollbar selectors.
 - Put presentation in CSS. Inline React styles may pass component-local custom-property values but must not encode theme branches.
 - Preserve keyboard focus visibility and reduced-motion behavior when adding transitions or hover-only controls.
+- Rounded corners inherit the global superellipse smoothing from ui-theme's `corner-shape.css` on supporting engines. Pair `corner-shape: round` with every full-round `border-radius` (`50%`, `100%`, or a pill radius) so circles and capsules keep circular arcs; the ui-theme corner-shape spec enforces the pairing.
+- Elevated surfaces (menus, popovers, modals, panels, floating buttons, the composer) set `border: 0` and take `box-shadow: var(--dsw-elevation-panel)` or `var(--dsw-elevation-prominent)`: the 0.5px hairline stroke is the first shadow layer, and `--dsw-elevation-stroke-color` rebinds or suppresses it per surface or state. Never pair a `--dsw-alias-border-*` border with an lv/elevation shadow — the ui-theme elevation spec rejects the pairing; state-colored borders (warn panels) stay real borders.
+- Flat borders and separators that use a neutral `--dsw-alias-border-*` token draw at `0.5px` — buttons, inputs, cards, row dividers, and separators drawn as filled boxes (menu separators, the conversation header seam, markdown `hr`, vertical rails) share the hairline weight, which Chromium paints as one device pixel. Dashed affordances and state-colored borders keep 1px; spinner ring tracks keep their width through the spec's explicit allowlist. The ui-theme elevation spec rejects wider neutral solid borders.
 
 ## Changing the system
 
diff --git a/docs/web-styling.zh.md b/docs/web-styling.zh.md
index a2ba074619..126011f0c8 100644
--- a/docs/web-styling.zh.md
+++ b/docs/web-styling.zh.md
@@ -19,6 +19,9 @@
 - 当组件约定要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
 - 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
+- 支持的引擎上，圆角继承 ui-theme `corner-shape.css` 的全局超级椭圆平滑。每个正圆 `border-radius`（`50%`、`100%` 或胶囊半径）必须配对 `corner-shape: round`，使圆形与胶囊保持圆弧；ui-theme 的 corner-shape spec 强制这一配对。
+- 高层级表面（菜单、浮层、对话框、面板、悬浮按钮、输入框）设 `border: 0` 并使用 `box-shadow: var(--dsw-elevation-panel)` 或 `var(--dsw-elevation-prominent)`：0.5px 发丝描边是第一层投影，`--dsw-elevation-stroke-color` 可按表面或状态重绑或抑制描边。不得将 `--dsw-alias-border-*` border 与 lv/elevation 投影配对——ui-theme 的 elevation spec 会拒绝；状态色 border（warn 面板）保持真 border。
+- 使用中性 `--dsw-alias-border-*` token 的平面边框与分割线一律 `0.5px`——按钮、输入框、卡片、行分割线，以及以填充盒绘制的分隔线（菜单分隔、对话标题栏接缝、markdown `hr`、竖向轨道线）共用发丝线粗细，Chromium 将其绘制为一个设备像素。dashed 记号与状态色 border 保持 1px；spinner 圆环经 spec 的显式豁免保留原宽度。更宽的中性 solid border 会被 ui-theme elevation spec 拒绝。
 
 ## 变更系统
 
diff --git a/packages/client/locale/src/client/LanguageRow.module.css b/packages/client/locale/src/client/LanguageRow.module.css
index 57d975d9b7..3003c782b9 100644
--- a/packages/client/locale/src/client/LanguageRow.module.css
+++ b/packages/client/locale/src/client/LanguageRow.module.css
@@ -6,7 +6,7 @@
   align-items: center;
   gap: 8px;
   padding: 16px 0;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .rowText {
diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css b/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css
index 3d6043fdfe..d019c87964 100644
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css
@@ -54,23 +54,25 @@
 }
 
 .card {
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 12px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: 20px;
   display: flex;
   flex-direction: column;
-  background: var(--dsw-alias-bg-layer-3);
+  background: transparent;
   transition: border-color .16s, background .16s;
 }
 
 
 .card:hover:not(.cardActive) {
-  border-color: var(--dsw-alias-label-dimmed);
+  background: var(--dsw-alias-interactive-bg-hover);
 }
 
-/* The default preset reads as selected, not merely badged. */
+/* The default preset reads as selected exactly like the Appearance cubes:
+   platform fill + the bluish-400 border (static token — the bluish-400 step
+   has no alias-layer name). */
 .cardActive {
-  background: var(--dsw-alias-bg-layer-2);
-  border-color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-bg-module-platform);
+  border-color: var(--dsw-static-neutral-bluish-400);
 }
 
 /* A broken preset reads as damaged before anything else: the card cannot be
@@ -85,6 +87,7 @@
 
 .brokenBadge {
   border-radius: 999px;
+  corner-shape: round;
   padding: 1px 8px;
   font-size: 11px;
   line-height: 17px;
@@ -198,6 +201,7 @@
 .badge,
 .inUse {
   border-radius: 999px;
+  corner-shape: round;
   padding: 1px 8px;
   font-size: 11px;
   line-height: 17px;
@@ -206,7 +210,7 @@
 }
 
 .badge {
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   color: var(--dsw-alias-label-tertiary);
 }
 
@@ -240,7 +244,7 @@
   margin-top: auto;
   font-family: var(--dsw-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
-  color: var(--dsw-alias-label-dimmed);
+  color: var(--dsw-alias-label-tertiary);
 }
 
 .cardFoot {
@@ -248,7 +252,7 @@
   justify-content: flex-end;
   gap: 2px;
   padding: 6px 10px;
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 /* Icon-only actions: the label rides `title` so the row stays quiet until
@@ -368,7 +372,7 @@
 .input {
   box-sizing: border-box;
   padding: 9px 12px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 10px;
   font: inherit;
   font-size: 13px;
@@ -401,7 +405,7 @@
   padding: 12px;
   max-height: min(52vh, 480px);
   overflow: auto;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 10px;
   background: var(--dsw-alias-bg-layer-2);
   color: var(--dsw-alias-label-secondary);
@@ -445,7 +449,7 @@
   gap: 6px;
   height: 44px;
   border: 1px dashed var(--dsw-alias-border-l3);
-  border-radius: 12px;
+  border-radius: 20px;
   font: inherit;
   font-size: 14px;
   line-height: 22px;
diff --git a/packages/client/ui-approval/src/client/ApprovalPanel.module.css b/packages/client/ui-approval/src/client/ApprovalPanel.module.css
index 12ea9bb631..048eb3d2f4 100644
--- a/packages/client/ui-approval/src/client/ApprovalPanel.module.css
+++ b/packages/client/ui-approval/src/client/ApprovalPanel.module.css
@@ -32,6 +32,7 @@
   width: 8px;
   height: 8px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-state-warn-primary);
 }
 
diff --git a/packages/client/ui-attachment/src/AttachmentRail.module.css b/packages/client/ui-attachment/src/AttachmentRail.module.css
index f2624bdf7d..eb06d8d1df 100644
--- a/packages/client/ui-attachment/src/AttachmentRail.module.css
+++ b/packages/client/ui-attachment/src/AttachmentRail.module.css
@@ -33,7 +33,7 @@
   height: 64px;
   padding: 0;
   overflow: hidden;
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border: 0.5px solid var(--dsw-alias-border-l2-darkmode-thin);
   border-radius: 16px;
   background: var(--dsw-alias-interactive-bg-hover);
   cursor: zoom-in;
@@ -58,6 +58,7 @@
   padding: 0;
   border: none;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-button-contrast-fill);
   color: var(--dsw-alias-label-primary-inverted);
   cursor: pointer;
@@ -92,11 +93,13 @@
   width: 24px;
   height: 24px;
   padding: 0;
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border: 0;
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l2-darkmode-thin);
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-specific-input-major);
   color: var(--dsw-alias-label-secondary);
-  box-shadow: var(--dsw-shadow-lv2);
+  box-shadow: var(--dsw-elevation-panel);
   cursor: pointer;
   transform: translateY(-50%);
 }
diff --git a/packages/client/ui-attachment/src/ImageLightbox.module.css b/packages/client/ui-attachment/src/ImageLightbox.module.css
index a74bd1c103..dffba50e82 100644
--- a/packages/client/ui-attachment/src/ImageLightbox.module.css
+++ b/packages/client/ui-attachment/src/ImageLightbox.module.css
@@ -36,8 +36,9 @@
   place-items: center;
   width: 36px;
   height: 36px;
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border: 0.5px solid var(--dsw-alias-border-l2-darkmode-thin);
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-specific-input-major);
   color: var(--dsw-alias-label-primary);
   cursor: pointer;
diff --git a/packages/client/ui-attachment/src/MessageImage.module.css b/packages/client/ui-attachment/src/MessageImage.module.css
index e59640df92..6c691c20a1 100644
--- a/packages/client/ui-attachment/src/MessageImage.module.css
+++ b/packages/client/ui-attachment/src/MessageImage.module.css
@@ -23,7 +23,7 @@
   min-height: 44px;
   padding: 0;
   overflow: hidden;
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border: 0.5px solid var(--dsw-alias-border-l2-darkmode-thin);
   border-radius: 16px;
   background: var(--dsw-alias-interactive-bg-hover);
   cursor: zoom-in;
@@ -53,7 +53,7 @@
 .error {
   max-width: 240px;
   padding: 10px 12px;
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border: 0.5px solid var(--dsw-alias-border-l2-darkmode-thin);
   border-radius: 10px;
   background: var(--dsw-alias-interactive-bg-hover-danger);
   cursor: pointer;
diff --git a/packages/client/ui-chat/src/client/chat/ChatView.module.css b/packages/client/ui-chat/src/client/chat/ChatView.module.css
index 16090d200f..0b1487cefb 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.module.css
+++ b/packages/client/ui-chat/src/client/chat/ChatView.module.css
@@ -202,11 +202,13 @@
   height: 34px;
   margin-top: -34px;
   padding: 0;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0;
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l3);
   border-radius: 100px;
+  corner-shape: round;
   color: var(--dsw-alias-label-primary);
   background: var(--dsw-alias-button-floating-fill);
-  box-shadow: var(--dsw-shadow-lv2);
+  box-shadow: var(--dsw-elevation-panel);
   cursor: pointer;
   pointer-events: auto;
 }
diff --git a/packages/client/ui-chat/src/client/chat/ContextBody.module.css b/packages/client/ui-chat/src/client/chat/ContextBody.module.css
index 3ed07752bc..b9919c440b 100644
--- a/packages/client/ui-chat/src/client/chat/ContextBody.module.css
+++ b/packages/client/ui-chat/src/client/chat/ContextBody.module.css
@@ -16,7 +16,7 @@
   gap: 2px;
   margin: 8px 0 0;
   padding-top: 8px;
-  border-top: 1px solid var(--dsw-alias-line-secondary);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .field {
diff --git a/packages/client/ui-chat/src/client/chat/GenericCommandCard.module.css b/packages/client/ui-chat/src/client/chat/GenericCommandCard.module.css
index 49297685ae..513a826c46 100644
--- a/packages/client/ui-chat/src/client/chat/GenericCommandCard.module.css
+++ b/packages/client/ui-chat/src/client/chat/GenericCommandCard.module.css
@@ -71,7 +71,7 @@
   margin: 4px 0 4px 4px;
   padding: 12px 16px;
   overflow: auto;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 12px;
   background: var(--dsw-alias-markdown-code-block);
   color: var(--dsw-alias-label-primary);
diff --git a/packages/client/ui-chat/src/client/chat/TurnNavigator.module.css b/packages/client/ui-chat/src/client/chat/TurnNavigator.module.css
index 5e771e6727..98af075c3d 100644
--- a/packages/client/ui-chat/src/client/chat/TurnNavigator.module.css
+++ b/packages/client/ui-chat/src/client/chat/TurnNavigator.module.css
@@ -167,11 +167,11 @@
   max-height: var(--turn-preview-height);
   overflow: hidden;
   padding: 10px 12px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0;
   border-radius: 10px;
   color: var(--dsw-alias-label-primary);
   background: var(--dsw-alias-bg-layer-1);
-  box-shadow: var(--dsw-shadow-lv2);
+  box-shadow: var(--dsw-elevation-panel);
   pointer-events: none;
   animation: dsh-turn-preview-enter 120ms ease-out;
   transition: top 140ms cubic-bezier(0.2, 0.8, 0.2, 1);
diff --git a/packages/client/ui-chat/src/client/chat/TurnProcessNodeView.module.css b/packages/client/ui-chat/src/client/chat/TurnProcessNodeView.module.css
index d0e0cd92a0..7c6025ca87 100644
--- a/packages/client/ui-chat/src/client/chat/TurnProcessNodeView.module.css
+++ b/packages/client/ui-chat/src/client/chat/TurnProcessNodeView.module.css
@@ -7,7 +7,7 @@
   height: 33px;
   padding: 0 0 8px;
   border: none;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   background: none;
   color: var(--dsw-alias-label-secondary);
   cursor: pointer;
diff --git a/packages/client/ui-chat/src/client/chat/TurnUsagePanel.module.css b/packages/client/ui-chat/src/client/chat/TurnUsagePanel.module.css
index e655a36810..7cc7c639eb 100644
--- a/packages/client/ui-chat/src/client/chat/TurnUsagePanel.module.css
+++ b/packages/client/ui-chat/src/client/chat/TurnUsagePanel.module.css
@@ -1,5 +1,5 @@
 /* Icon-row Turn-usage pill (data icon + turn total) plus its click-open
-   Turn-details dialog (menu surface: r12, inverted hairline, shadow-lv3 —
+   Turn-details dialog (menu surface: r12, elevation-prominent —
    ContextMeter's panel skin). */
 
 .root {
@@ -90,10 +90,11 @@
   min-width: min(300px, calc(100vw - 24px));
   max-width: min(440px, calc(100vw - 24px));
   padding: 16px;
-  border: 1px solid var(--dsw-alias-border-inverted);
+  border: 0;
   border-radius: 12px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
   font-size: 12px;
   line-height: 18px;
   color: var(--dsw-alias-label-secondary);
@@ -114,7 +115,7 @@
 /* Rule under each section heading, above its rows. */
 .titleRule {
   margin-bottom: 10px;
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .titleValue {
diff --git a/packages/client/ui-chat/src/client/details/DetailsPanel.module.css b/packages/client/ui-chat/src/client/details/DetailsPanel.module.css
index cc5d732e45..85fdd8c0df 100644
--- a/packages/client/ui-chat/src/client/details/DetailsPanel.module.css
+++ b/packages/client/ui-chat/src/client/details/DetailsPanel.module.css
@@ -7,7 +7,7 @@
   flex-direction: column;
   height: 100%;
   min-width: 0;
-  border-left: 1px solid var(--dsw-alias-border-l2);
+  border-left: 0.5px solid var(--dsw-alias-border-l2);
   background: var(--dsw-alias-bg-base);
 }
 
@@ -18,7 +18,7 @@
   justify-content: space-between;
   gap: 8px;
   padding: 14px 12px 12px;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 /* figma I54:42735;43:41479: 14/20 wt500. */
@@ -40,6 +40,7 @@
   height: 28px;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: transparent;
   color: var(--dsw-alias-label-secondary);
   cursor: pointer;
diff --git a/packages/client/ui-chat/src/client/settings/TranscriptViewRow.module.css b/packages/client/ui-chat/src/client/settings/TranscriptViewRow.module.css
index 496e01add3..1ab93f1d52 100644
--- a/packages/client/ui-chat/src/client/settings/TranscriptViewRow.module.css
+++ b/packages/client/ui-chat/src/client/settings/TranscriptViewRow.module.css
@@ -5,7 +5,7 @@
   align-items: center;
   gap: 8px;
   padding: 16px 0;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .rowText {
diff --git a/packages/client/ui-commands/src/client/PopupSelectView.module.css b/packages/client/ui-commands/src/client/PopupSelectView.module.css
index cd457cc376..39ee045f16 100644
--- a/packages/client/ui-commands/src/client/PopupSelectView.module.css
+++ b/packages/client/ui-commands/src/client/PopupSelectView.module.css
@@ -1,6 +1,6 @@
 /* Official popupSelect shell card: menu-surface tokens (same family as
  * ui-primitives Menu.module.css — figma MenuDropdown r12 / hairline /
- * shadow-lv3), anchored by the conversation.input.overlay slot. */
+ * elevation-prominent), anchored by the conversation.input.overlay slot. */
 
 .card {
   /* The overlay anchor is a zero-height strip on the composer card's top
@@ -24,10 +24,11 @@
      (see ui-theme styles/scrollbar.css for the rebinding contract). */
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
-  border: 1px solid var(--dsw-alias-border-inverted);
-  border-radius: 12px;
+  border: 0;
+  border-radius: 16px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
   outline: none;
 }
 
@@ -84,7 +85,7 @@
 .search {
   margin: 2px 2px 4px;
   padding: 6px 8px;
-  border: 1px solid var(--dsw-alias-border-inverted);
+  border: 0.5px solid var(--dsw-alias-border-inverted);
   border-radius: 8px;
   background: transparent;
   font-size: 13px;
@@ -109,7 +110,7 @@
 
 .retry {
   padding: 2px 8px;
-  border: 1px solid var(--dsw-alias-border-inverted);
+  border: 0.5px solid var(--dsw-alias-border-inverted);
   border-radius: 6px;
   background: transparent;
   font-size: 12px;
diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.module.css b/packages/client/ui-conversation/src/client/queue/QueueDock.module.css
index 81ea205b5e..dd2cbc73ce 100644
--- a/packages/client/ui-conversation/src/client/queue/QueueDock.module.css
+++ b/packages/client/ui-conversation/src/client/queue/QueueDock.module.css
@@ -39,7 +39,7 @@
 .panel::after {
   position: absolute;
   inset: 0;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   /* The input card's own top border closes the shape below. */
   border-bottom: none;
   border-radius: inherit;
@@ -131,7 +131,7 @@
 .thumb {
   width: 24px;
   height: 24px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 4px;
   background: var(--dsw-alias-bg-base);
   object-fit: cover;
@@ -157,7 +157,7 @@
   box-sizing: border-box;
   height: 28px;
   padding: 0 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 6px;
   outline: none;
   background: var(--dsw-alias-bg-base);
@@ -184,6 +184,7 @@
   padding: 0;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: transparent;
   color: var(--dsw-alias-label-tertiary);
   cursor: pointer;
diff --git a/packages/client/ui-conversation/src/client/settings/EnterBehaviorRow.module.css b/packages/client/ui-conversation/src/client/settings/EnterBehaviorRow.module.css
index 9d8b3d7ceb..e06a9b949f 100644
--- a/packages/client/ui-conversation/src/client/settings/EnterBehaviorRow.module.css
+++ b/packages/client/ui-conversation/src/client/settings/EnterBehaviorRow.module.css
@@ -5,7 +5,7 @@
   align-items: center;
   gap: 8px;
   padding: 16px 0;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .rowText {
diff --git a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css
index 9eed743214..493738ae2d 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css
@@ -1,5 +1,5 @@
 /* Context-occupancy ring beside the send button plus its click-open breakdown
-   panel (menu surface: r12, inverted hairline, shadow-lv3). */
+   panel (menu surface: r12, elevation-prominent). */
 
 .root {
   position: relative;
@@ -15,6 +15,7 @@
   height: 28px;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: transparent;
   color: var(--dsw-alias-label-secondary);
   cursor: pointer;
@@ -45,10 +46,11 @@
   box-sizing: border-box;
   width: 264px;
   padding: 12px;
-  border: 1px solid var(--dsw-alias-border-inverted);
+  border: 0;
   border-radius: 12px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
   font-size: 12px;
   line-height: 20px;
   color: var(--dsw-alias-label-secondary);
@@ -89,6 +91,7 @@
   margin: 10px 0 12px;
   height: 4px;
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-alias-interactive-bg-hover);
   overflow: hidden;
 }
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
index 73c5fccb73..3e98b17b42 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
@@ -48,8 +48,8 @@
   bottom: 1px;
   left: 0;
   z-index: 0;
-  height: 1px;
-  background: var(--dsw-alias-border-l2);
+  height: 0.5px;
+  background: var(--dsw-alias-border-l3);
   pointer-events: none;
 }
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css b/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
index 983c168ec1..6c5053e9c6 100644
--- a/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
@@ -50,7 +50,7 @@
   margin-top: 2px;
   margin-left: -3px;
   padding: 1px 7px 0;
-  border: 1px solid var(--dsw-alias-interactive-bg-hover);
+  border: 0.5px solid var(--dsw-alias-interactive-bg-hover);
   border-radius: 24px;
   background: var(--dsw-alias-state-business-tertiary);
   color: var(--dsw-alias-label-primary-bluish);
@@ -185,7 +185,7 @@
   width: 100%;
   height: 44px;
   padding: 7px 14px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 22px;
   outline: none;
   background: transparent;
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index 6576608916..916039e3d0 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -40,13 +40,14 @@
   width: 100%;
   max-width: var(--dsh-composer-card-max-width);
   padding-top: 10px;
-  /* Input stroke: black/0.10 light, white/0.06 dark (figma darkmode note says
-     the input border is one notch weaker than buttons) — exactly the
-     l2-darkmode-thin pair. Fill: the input surface token (elevated in dark). */
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  /* Input stroke: the lightest neutral (l1), drawn as the elevation hairline
+     so it costs no layout; the shadow is the soft elevation tier. Fill: the
+     input surface token (elevated in dark). */
+  border: 0;
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
   border-radius: 22px;
   background: var(--dsw-specific-input-major);
-  box-shadow: var(--dsw-shadow-lv2);
+  box-shadow: var(--dsw-elevation-soft);
   /* The draft text follows the Settings font-size preference (the textarea,
      mirror, and backdrop all inherit from here, so the three layers stay in
      step); the line height keeps the default 10px leading via the shared px
@@ -69,7 +70,7 @@
    by an SVG dash ring (stroke-width 2 centered on the box edge = 1px visible
    inside), which keeps the 22px radius and both themes. */
 .cardWorkspaceTrigger {
-  border-color: transparent;
+  --dsw-elevation-stroke-color: transparent;
   cursor: pointer;
 }
 
@@ -141,6 +142,7 @@
   width: 8px;
   height: 8px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-state-business-primary);
   animation: input-pending 1s ease-in-out infinite alternate;
 }
@@ -266,6 +268,7 @@
   height: 28px;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-specific-selector);
   color: var(--dsw-alias-label-primary);
   cursor: pointer;
@@ -323,6 +326,7 @@
   height: 34px;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-alias-button-info-fill);
   /* Static white, not the foreground token: the arrow stays white on the blue
      fill in both themes (design 34:10465). */
diff --git a/packages/client/ui-conversation/src/client/skeleton/TodoPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/TodoPanel.module.css
index f39b10dae4..a115a897b6 100644
--- a/packages/client/ui-conversation/src/client/skeleton/TodoPanel.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/TodoPanel.module.css
@@ -19,7 +19,7 @@
     var(--dsh-composer-dock-inset) -
     var(--dsh-composer-dock-inset)
   );
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 12px;
   background: var(--dsw-specific-tip);
   /* Elevated surface: `--dsw-specific-tip` is the same dark rung as the menu
diff --git a/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.module.css
index 75f59b7cb9..5e3bbb3775 100644
--- a/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.module.css
+++ b/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.module.css
@@ -29,7 +29,7 @@
   gap: 8px;
   flex: none;
   padding: 16px 14px 8px 24px;
-  border-bottom: 1px solid var(--dsw-alias-border-l3);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l3);
 }
 
 .title {
@@ -215,7 +215,7 @@
 
 .divider {
   flex: none;
-  width: 1px;
+  width: 0.5px;
   background: var(--dsw-alias-border-l3);
 }
 
@@ -323,7 +323,7 @@
   gap: 8px;
   flex: none;
   padding: 16px 24px;
-  border-top: 1px solid var(--dsw-alias-border-l3);
+  border-top: 0.5px solid var(--dsw-alias-border-l3);
 }
 
 /* Show-hidden toggle: a subtle fixed-label text button left of the gap;
@@ -400,7 +400,7 @@
   width: 100%;
   height: 44px;
   padding: 7px 14px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 22px;
   outline: none;
   background: transparent;
diff --git a/packages/client/ui-goal/src/client/GoalBar.module.css b/packages/client/ui-goal/src/client/GoalBar.module.css
index ffc3149cce..31e78aecd1 100644
--- a/packages/client/ui-goal/src/client/GoalBar.module.css
+++ b/packages/client/ui-goal/src/client/GoalBar.module.css
@@ -26,7 +26,7 @@
   height: 36px;
   margin: 0 auto;
   padding: 4px 5px 4px 12px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 12px;
   background: var(--dsw-specific-tip);
 }
@@ -76,7 +76,7 @@
   min-width: 0;
   height: 26px;
   padding: 0 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 6px;
   background: var(--dsw-alias-bg-base);
   font-size: 13px;
@@ -111,6 +111,7 @@
   padding: 0;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: transparent;
   color: var(--dsw-alias-label-tertiary);
   cursor: pointer;
diff --git a/packages/client/ui-input-trigger/src/client/MenuView.module.css b/packages/client/ui-input-trigger/src/client/MenuView.module.css
index 42499397b8..4f6b5c4d18 100644
--- a/packages/client/ui-input-trigger/src/client/MenuView.module.css
+++ b/packages/client/ui-input-trigger/src/client/MenuView.module.css
@@ -17,10 +17,11 @@
   padding: 4px;
   display: flex;
   flex-direction: column;
-  border: 1px solid var(--dsw-alias-border-inverted);
-  border-radius: 12px;
+  border: 0;
+  border-radius: 16px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
 }
 
 .viewport {
@@ -198,7 +199,7 @@
   margin-bottom: 2px;
   /* l1, not border-inverted (the menu frame's dark-only stroke): the divider
      needs to survive light mode too; in dark both resolve to white/0.06. */
-  border-bottom: 1px solid var(--dsw-alias-border-l1);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l1);
 }
 /* Crumbs sit outside the listbox and take no keyboard highlight, so unlike
    .item they carry their own :hover tint with nothing to compete with. */
diff --git a/packages/client/ui-jobs/src/client/JobListAction.module.css b/packages/client/ui-jobs/src/client/JobListAction.module.css
index 2f475bd09c..56bf028248 100644
--- a/packages/client/ui-jobs/src/client/JobListAction.module.css
+++ b/packages/client/ui-jobs/src/client/JobListAction.module.css
@@ -54,12 +54,13 @@
   padding: 4px;
   overflow: auto;
   list-style: none;
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 12px;
+  border: 0;
+  border-radius: 16px;
   background: var(--dsw-specific-menu);
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
 }
 
 .row {
diff --git a/packages/client/ui-layout/src/client/AppFrame.module.css b/packages/client/ui-layout/src/client/AppFrame.module.css
index ae56780133..9ba4e82be6 100644
--- a/packages/client/ui-layout/src/client/AppFrame.module.css
+++ b/packages/client/ui-layout/src/client/AppFrame.module.css
@@ -26,7 +26,7 @@
   min-width: 0;
   overflow: hidden;
   background: var(--dsw-specific-sidebar-fill);
-  border-right: 1px solid var(--dsw-alias-border-l1);
+  border-right: 0.5px solid var(--dsw-alias-border-l3);
 }
 
 .centerCol {
@@ -39,7 +39,7 @@
 .detailsCol {
   min-width: 0;
   overflow: hidden;
-  border-left: 1px solid var(--dsw-alias-border-l2);
+  border-left: 0.5px solid var(--dsw-alias-border-l3);
 }
 
 /* The details subtree stays mounted at zero width, so its border must not paint
@@ -86,7 +86,7 @@
   border-radius: 10px;
   box-sizing: border-box;
   background: var(--dsw-alias-button-floating-fill);
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border: 0.5px solid var(--dsw-alias-border-l2-darkmode-thin);
   /* Hover affordance: the details pill hides until the pointer is over its
      column, the strip itself, or a drag. */
   opacity: 0;
diff --git a/packages/client/ui-message-feedback/src/client/MessageFeedbackActions.module.css b/packages/client/ui-message-feedback/src/client/MessageFeedbackActions.module.css
index f1050b6f2b..b629c317fa 100644
--- a/packages/client/ui-message-feedback/src/client/MessageFeedbackActions.module.css
+++ b/packages/client/ui-message-feedback/src/client/MessageFeedbackActions.module.css
@@ -78,10 +78,11 @@
   display: flex;
   flex-direction: column;
   gap: 8px;
-  border: 1px solid var(--dsw-alias-border-inverted);
+  border: 0;
   border-radius: 12px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
 }
@@ -90,7 +91,7 @@
   width: 100%;
   box-sizing: border-box;
   padding: 6px 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 8px;
   background: var(--dsw-alias-bg-layer-1);
   color: var(--dsw-alias-label-primary);
diff --git a/packages/client/ui-model-selection/src/client/ModelSelect.module.css b/packages/client/ui-model-selection/src/client/ModelSelect.module.css
index 492fb12f8c..2c19256a8e 100644
--- a/packages/client/ui-model-selection/src/client/ModelSelect.module.css
+++ b/packages/client/ui-model-selection/src/client/ModelSelect.module.css
@@ -82,10 +82,11 @@
   padding: 4px;
   /* Surface tokens match the Menu primitive card (ui-primitives
    * Menu.module.css) so every dropdown reads as the same material. */
-  border: 1px solid var(--dsw-alias-border-inverted);
-  border-radius: 12px;
+  border: 0;
+  border-radius: 16px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
   color: var(--dsw-alias-label-primary);
   /* Elevated surface: the scrollbar thumb takes the l2 elevation tokens.
      Declared here rather than on the scrolling `.groups` child so the
diff --git a/packages/client/ui-permission-presets/src/client/PermissionRow.module.css b/packages/client/ui-permission-presets/src/client/PermissionRow.module.css
index b7a11bed6a..9c64981afe 100644
--- a/packages/client/ui-permission-presets/src/client/PermissionRow.module.css
+++ b/packages/client/ui-permission-presets/src/client/PermissionRow.module.css
@@ -5,7 +5,7 @@
   align-items: center;
   gap: 8px;
   padding: 16px 0;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .rowText {
diff --git a/packages/client/ui-plan/src/client/PlanModeControl.module.css b/packages/client/ui-plan/src/client/PlanModeControl.module.css
index 46e893aee8..b4547e3b7f 100644
--- a/packages/client/ui-plan/src/client/PlanModeControl.module.css
+++ b/packages/client/ui-plan/src/client/PlanModeControl.module.css
@@ -14,6 +14,7 @@
   padding: 2px 8px;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-alias-state-warn-tertiary);
   color: var(--dsw-alias-state-warn-label);
   font-size: 13px;
diff --git a/packages/client/ui-primitives/src/Button.module.css b/packages/client/ui-primitives/src/Button.module.css
index b9384dd522..9fa1712a66 100644
--- a/packages/client/ui-primitives/src/Button.module.css
+++ b/packages/client/ui-primitives/src/Button.module.css
@@ -54,7 +54,7 @@
 
 /* Dialog Cancel (figma 451:18655): bordered capsule on transparent fill. */
 .outline {
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   background: transparent;
 }
 
diff --git a/packages/client/ui-primitives/src/Input.module.css b/packages/client/ui-primitives/src/Input.module.css
index 70258a3339..5102c3291f 100644
--- a/packages/client/ui-primitives/src/Input.module.css
+++ b/packages/client/ui-primitives/src/Input.module.css
@@ -4,7 +4,7 @@
   gap: 6px;
   height: 32px;
   padding: 0 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 8px;
   background: var(--dsw-alias-bg-layer-1);
 }
diff --git a/packages/client/ui-primitives/src/Menu.module.css b/packages/client/ui-primitives/src/Menu.module.css
index 7bc0c5aced..7c5d11f4bc 100644
--- a/packages/client/ui-primitives/src/Menu.module.css
+++ b/packages/client/ui-primitives/src/Menu.module.css
@@ -4,7 +4,7 @@
 }
 
 /* Dropdown card (figma MenuDropdown 122:9481 / 419:16920): menu surface,
- * r12, inverted hairline border, shadow-lv3, 4px inset padding. */
+ * r12, elevation-prominent (hairline stroke in shadow), 4px inset padding. */
 .list,
 .submenu {
   /* min-widths below are the design's outer card widths — include the pad. */
@@ -13,10 +13,11 @@
   display: flex;
   flex-direction: column;
   gap: 0;
-  border: 1px solid var(--dsw-alias-border-inverted);
-  border-radius: 12px;
+  border: 0;
+  border-radius: 16px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
   /* Elevated surface: the scrollbar thumb takes the l2 elevation tokens. The
      declaration sits on the card rather than on `.scrollable .viewport`
      because the elevation is a property of this surface, and the custom
@@ -85,7 +86,7 @@
   flex-direction: column;
   margin-top: 4px;
   padding-top: 4px;
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .itemWrap {
@@ -212,7 +213,7 @@
 
 /* Separator cell (figma 122:9481): py 4 / px 2 around the hairline. */
 .separator {
-  height: 1px;
+  height: 0.5px;
   margin: 4px 2px;
   background: var(--dsw-alias-border-l1);
 }
diff --git a/packages/client/ui-primitives/src/Modal.module.css b/packages/client/ui-primitives/src/Modal.module.css
index 0c6d68e5fa..44ec4b7d93 100644
--- a/packages/client/ui-primitives/src/Modal.module.css
+++ b/packages/client/ui-primitives/src/Modal.module.css
@@ -18,7 +18,7 @@
   backdrop-filter: var(--dsw-mask-blur);
 }
 
-/* Dialog card: r24, shadow-lv3, layer-2 fill, inverted border, pb 24. */
+/* Dialog card: r24, elevation-prominent, layer-2 fill, pb 24. */
 .dialog {
   position: relative;
   z-index: 1;
@@ -28,10 +28,10 @@
   width: min(380px, 100%);
   padding: 0 0 24px;
   overflow: hidden;
-  border: 1px solid var(--dsw-alias-border-inverted);
+  border: 0;
   border-radius: 24px;
   background: var(--dsw-alias-bg-layer-2);
-  box-shadow: var(--dsw-shadow-lv3);
+  box-shadow: var(--dsw-elevation-prominent);
 }
 
 .content {
diff --git a/packages/client/ui-primitives/src/StateDot.module.css b/packages/client/ui-primitives/src/StateDot.module.css
index e9442f46bb..7faf3ad25f 100644
--- a/packages/client/ui-primitives/src/StateDot.module.css
+++ b/packages/client/ui-primitives/src/StateDot.module.css
@@ -18,6 +18,7 @@
   position: absolute;
   inset: 0;
   border-radius: 50%;
+  corner-shape: round;
   background: currentColor;
   opacity: 0.1;
 }
@@ -27,6 +28,7 @@
   position: absolute;
   inset: 20%;
   border-radius: 50%;
+  corner-shape: round;
   background: currentColor;
 }
 
diff --git a/packages/client/ui-primitives/src/TerminalBlock.module.css b/packages/client/ui-primitives/src/TerminalBlock.module.css
index 7a74327c74..5198a5148a 100644
--- a/packages/client/ui-primitives/src/TerminalBlock.module.css
+++ b/packages/client/ui-primitives/src/TerminalBlock.module.css
@@ -62,7 +62,7 @@
    divider the IN/OUT card draws between its sections. A running card is
    banner-only, so it draws none. */
 .block:not([data-running]) .header {
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 /* One row per command line. The prompt column is the only element allowed to
diff --git a/packages/client/ui-primitives/src/markdown/JsonBlock.module.css b/packages/client/ui-primitives/src/markdown/JsonBlock.module.css
index 7a967146e6..b2852e3242 100644
--- a/packages/client/ui-primitives/src/markdown/JsonBlock.module.css
+++ b/packages/client/ui-primitives/src/markdown/JsonBlock.module.css
@@ -23,7 +23,7 @@
   max-height: 200px;
   overflow: auto;
   background: var(--dsw-alias-markdown-code-block);
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 6px;
   font-family: var(--ds-font-family-code);
   font-size: 11px;
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
index dafe49616c..0d46ab172a 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -126,7 +126,7 @@
 .markdown hr {
   display: block;
   border: none;
-  height: 1px;
+  height: 0.5px;
   margin: 32px 0;
   background: var(--dsw-alias-border-l2);
 }
@@ -225,7 +225,7 @@
 .tableScroll th {
   text-align: start;
   padding: 10px 16px;
-  border-bottom: 1px solid var(--dsw-alias-border-l3);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l3);
   border-top: none;
   font: var(--dsw-font-markdown-table-head);
   max-width: 320px;
@@ -235,7 +235,7 @@
 
 .tableScroll td {
   padding: 10px 16px;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   font: var(--dsw-font-markdown-table);
   max-width: 320px;
   max-width: min(30vw, 320px);
diff --git a/packages/client/ui-schedule/src/client/ScheduleCatalogAction.module.css b/packages/client/ui-schedule/src/client/ScheduleCatalogAction.module.css
index 82c10bcfb7..5319887ae0 100644
--- a/packages/client/ui-schedule/src/client/ScheduleCatalogAction.module.css
+++ b/packages/client/ui-schedule/src/client/ScheduleCatalogAction.module.css
@@ -52,12 +52,13 @@
   padding: 4px;
   overflow: auto;
   list-style: none;
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 12px;
+  border: 0;
+  border-radius: 16px;
   background: var(--dsw-specific-menu);
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
 }
 
 .row {
@@ -91,6 +92,7 @@
   height: 8px;
   flex: none;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-state-business-primary);
 }
 
diff --git a/packages/client/ui-settings-general/src/client/SettingsRoot.module.css b/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
index f68b7a5d4e..95de406381 100644
--- a/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
+++ b/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
@@ -48,6 +48,7 @@
   gap: 0;
   padding: 0;
   border-radius: 50%;
+  corner-shape: round;
 }
 
 .triggerLabel {
@@ -73,8 +74,8 @@
   backdrop-filter: var(--dsw-mask-blur);
 }
 
-/* Panel (figma Settings 501:29947): r24, white, lv3 shadow (figma effects
-   match --dsw-shadow-lv3 exactly); figma's 1080x700 is shrunk to 800 wide.
+/* Panel (figma Settings 501:29947): r24, white; the figma lv3 effects are
+   superseded by the shared elevation treatment; figma's 1080x700 is shrunk to 800 wide.
    One height for every section, taken from the viewport rather than the
    content: sections differ by hundreds of pixels (a settings list against the
    composition editor), and a content-sized panel would resize under the
@@ -86,10 +87,10 @@
   width: 800px;
   height: min(800px, calc(100vh - 48px));
   max-width: calc(100vw - 48px);
-  border-radius: 24px;
+  border-radius: 32px;
   overflow: hidden;
   background: var(--dsw-alias-bg-layer-2);
-  box-shadow: var(--dsw-shadow-lv3);
+  box-shadow: var(--dsw-elevation-prominent);
   /* Elevated surface: the scrollbar thumb takes the l2 elevation tokens.
      Declared on the panel rather than the scrolling `.options` child so the
      elevation choice sits with the surface; the custom properties inherit
diff --git a/packages/client/ui-settings-models/src/client/ModelsSection.module.css b/packages/client/ui-settings-models/src/client/ModelsSection.module.css
index fe2fe87d3a..dbba1a1f9b 100644
--- a/packages/client/ui-settings-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-settings-models/src/client/ModelsSection.module.css
@@ -53,8 +53,8 @@
 /* A configured provider: outlined on the panel fill, so the filled editor
    card it expands into reads as the nested object. */
 .rowCard {
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 12px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: 16px;
   padding: 12px 14px;
   display: flex;
   flex-direction: column;
@@ -88,7 +88,7 @@
 .rowTag {
   flex: none;
   padding: 1px 6px;
-  border: 1px solid var(--dsw-alias-border-l3);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   border-radius: 4px;
   font-size: 11px;
   line-height: 16px;
@@ -102,6 +102,7 @@
   width: 8px;
   height: 8px;
   border-radius: 50%;
+  corner-shape: round;
 }
 
 .credentialDotConfigured {
@@ -151,7 +152,7 @@
 
 .secondaryButton,
 .addButton {
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   background: transparent;
   color: var(--dsw-alias-label-primary);
 }
@@ -323,7 +324,7 @@
   gap: 6px;
   height: 44px;
   border: 1px dashed var(--dsw-alias-border-l3);
-  border-radius: 12px;
+  border-radius: 16px;
 }
 
 .addCard,
@@ -345,7 +346,7 @@
 }
 
 .customized {
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
   padding-top: 10px;
 }
 
@@ -406,7 +407,7 @@
   flex-direction: column;
   gap: 10px;
   padding-top: 12px;
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .modelCatalogHeading {
@@ -450,8 +451,8 @@
 }
 
 .modelEntry {
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 8px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: 10px;
   padding: 6px;
 }
 
@@ -528,7 +529,7 @@
   gap: 4px;
   height: 28px;
   padding: 0 10px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   border-radius: 14px;
   background: transparent;
   color: var(--dsw-alias-label-primary);
@@ -547,7 +548,7 @@
   width: 100%;
   height: 32px;
   padding: 0 10px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 8px;
   font: inherit;
   font-size: 14px;
diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css
index 3a1626a4f0..7bc8daf3df 100644
--- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css
+++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css
@@ -28,7 +28,7 @@
 }
 
 .failure button {
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   border-radius: 6px;
   padding: 4px 10px;
   background: transparent;
@@ -60,8 +60,8 @@
 .search input {
   width: 100%;
   height: 36px;
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 8px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: 10px;
   padding: 0 34px 0 36px;
   outline: none;
   background: var(--dsw-alias-bg-layer-1);
@@ -112,14 +112,15 @@
 .card {
   min-width: 0;
   overflow: hidden;
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 10px;
+  border: 0;
+  box-shadow: var(--dsw-elevation-stroke);
+  border-radius: 14px;
   background: var(--dsw-alias-bg-layer-3);
 }
 
 .card[data-open='true'] {
-  border-color: var(--dsw-alias-border-l1);
-  box-shadow: var(--dsw-shadow-lv1);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-panel);
 }
 
 .cardContent {
@@ -173,6 +174,7 @@
   height: 7px;
   flex: none;
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-alias-label-tertiary);
 }
 
@@ -235,7 +237,7 @@
 }
 
 .group + .group {
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
   padding-top: 14px;
 }
 
@@ -393,7 +395,7 @@
 }
 
 .cardDetails {
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
   padding: 10px 14px 12px;
   background: var(--dsw-alias-bg-module-platform);
 }
diff --git a/packages/client/ui-settings-plugins/src/client/PluginCard.module.css b/packages/client/ui-settings-plugins/src/client/PluginCard.module.css
index 091273cd5b..d98d43ebc2 100644
--- a/packages/client/ui-settings-plugins/src/client/PluginCard.module.css
+++ b/packages/client/ui-settings-plugins/src/client/PluginCard.module.css
@@ -2,8 +2,8 @@
 
 .card {
   list-style: none;
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 12px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: 16px;
   background: var(--dsw-alias-bg-layer-3);
   transition: border-color .16s, background .16s;
 }
@@ -73,7 +73,7 @@
 }
 
 .body {
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
   margin: 0 16px;
   padding-bottom: 8px;
 }
@@ -89,6 +89,7 @@
 .pending {
   flex: none;
   border-radius: 999px;
+  corner-shape: round;
   padding: 1px 8px;
   font-size: 11px;
   line-height: 17px;
@@ -104,7 +105,7 @@
   justify-content: flex-end;
   gap: 8px;
   padding: 12px 0 4px;
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .failed {
diff --git a/packages/client/ui-settings-plugins/src/client/PluginsSettingsSection.module.css b/packages/client/ui-settings-plugins/src/client/PluginsSettingsSection.module.css
index 5760403c4a..0bd1beb9bf 100644
--- a/packages/client/ui-settings-plugins/src/client/PluginsSettingsSection.module.css
+++ b/packages/client/ui-settings-plugins/src/client/PluginsSettingsSection.module.css
@@ -24,7 +24,7 @@
   display: flex;
   align-items: flex-end;
   gap: 22px;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   margin-top: 2px;
 }
 
diff --git a/packages/client/ui-settings-plugins/src/client/SubagentModelSelectionCard.module.css b/packages/client/ui-settings-plugins/src/client/SubagentModelSelectionCard.module.css
index 4139daea2a..580dfa6bc2 100644
--- a/packages/client/ui-settings-plugins/src/client/SubagentModelSelectionCard.module.css
+++ b/packages/client/ui-settings-plugins/src/client/SubagentModelSelectionCard.module.css
@@ -51,6 +51,7 @@
   width: 16px;
   height: 16px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-label-primary-foreground);
   transition: transform 120ms ease;
 }
@@ -108,7 +109,7 @@
   margin: 0;
   padding: 10px;
   overflow: auto;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 8px;
 }
 
@@ -126,7 +127,7 @@
 .modelGroup + .modelGroup {
   margin-top: 4px;
   padding-top: 10px;
-  border-top: 1px solid var(--dsw-alias-border-l3);
+  border-top: 0.5px solid var(--dsw-alias-border-l3);
 }
 
 .providerName {
diff --git a/packages/client/ui-settings-plugins/src/client/fields.module.css b/packages/client/ui-settings-plugins/src/client/fields.module.css
index 261dcb0fe9..b0ab9eaef9 100644
--- a/packages/client/ui-settings-plugins/src/client/fields.module.css
+++ b/packages/client/ui-settings-plugins/src/client/fields.module.css
@@ -8,7 +8,7 @@
 }
 
 .field + .field {
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .head {
@@ -34,6 +34,7 @@
 
 .badge {
   border-radius: 999px;
+  corner-shape: round;
   padding: 1px 8px;
   font-size: 11px;
   line-height: 17px;
@@ -45,6 +46,7 @@
 
 .badgeMuted {
   border-radius: 999px;
+  corner-shape: round;
   padding: 1px 8px;
   font-size: 11px;
   line-height: 17px;
@@ -74,7 +76,7 @@
 .input {
   height: 34px;
   padding: 0 12px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 8px;
   background: var(--dsw-alias-bg-layer-3);
   font: inherit;
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
index d472581e43..4ea10606e1 100644
--- a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
@@ -185,6 +185,7 @@
   height: 28px;
   border: none;
   border-radius: 50%;
+  corner-shape: round;
   padding: 0;
   background: transparent;
   cursor: pointer;
@@ -255,7 +256,7 @@
   padding: 8px 16px;
   margin: 0 2px 8px;
   box-sizing: border-box;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   border-radius: 12px;
   background: var(--dsw-alias-button-elevated-fill);
   color: var(--dsw-alias-label-primary);
diff --git a/packages/client/ui-skill/src/client/SkillRow.module.css b/packages/client/ui-skill/src/client/SkillRow.module.css
index 05c3388aa9..4dd75f8498 100644
--- a/packages/client/ui-skill/src/client/SkillRow.module.css
+++ b/packages/client/ui-skill/src/client/SkillRow.module.css
@@ -118,7 +118,7 @@
   max-height: 260px;
   margin: 4px 0 4px 4px;
   overflow: hidden;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 12px;
   background: var(--dsw-alias-markdown-code-block);
 }
@@ -126,7 +126,7 @@
 .instructionsHeader {
   flex: none;
   padding: 8px 12px;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   background: var(--dsw-alias-markdown-code-block-banner);
   font-size: 11px;
   font-weight: 500;
@@ -168,8 +168,9 @@
   gap: 4px;
   margin: 4px 0 2px 4px;
   padding: 2px 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-alias-bg-base);
   color: var(--dsw-alias-label-secondary);
   font-size: 11px;
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
index 68b16940d9..86e6dcf9b5 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
@@ -103,11 +103,12 @@
   max-height: min(560px, calc(100vh - 140px));
   padding: 4px;
   overflow: auto;
-  border-radius: 12px;
+  border-radius: 16px;
   background: var(--dsw-specific-menu);
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
 }
 
 .node {
@@ -260,7 +261,7 @@
   content: '';
   position: absolute;
   left: 0;
-  border-left: 1px solid var(--dsw-alias-border-l2);
+  border-left: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .children::before {
@@ -289,7 +290,7 @@
   top: 16px;
   left: -4px;
   width: 14px;
-  border-top: 1px solid var(--dsw-alias-border-l2);
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .notice,
diff --git a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.module.css b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.module.css
index d409d416fe..cd6a0a0a3c 100644
--- a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.module.css
+++ b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.module.css
@@ -6,7 +6,7 @@
   margin: 0 24px 20px;
   min-height: 54px;
   padding: 10px 16px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 14px;
   background: var(--dsw-alias-bg-layer-1);
   color: var(--dsw-alias-label-tertiary);
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index fdce69f55a..23b6f81209 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/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/client/ui-theme/README.md
-README.md: 8d635f4523fe89c9c6d711f32f8d9cf6e4cfb627
-README.zh.md: dec856fde15aae690096bdb52fc84c00c66336ab
+README.md: 756175ba1208cdca4c92c73885bad3c7d11e0065
+README.zh.md: 29a901020dd96c5b75e5bd1b486e4167e7d49b08
diff --git a/packages/client/ui-theme/README.md b/packages/client/ui-theme/README.md
index 8d635f4523..756175ba12 100644
--- a/packages/client/ui-theme/README.md
+++ b/packages/client/ui-theme/README.md
@@ -51,9 +51,11 @@ The service owns theme and font-size state and publishes snapshots. The ui-layou
 
 ### Stylesheets
 
-`src/styles/` holds five sheets imported in order by ui-theme's dynamic client entry: `base.css`, `design-platform.css`, `scrollbar.css`, `gradient-shadow-text.css`, and `shiki.css`. The client bundle compiles and injects them as plugin-owned global styles, so unload and HMR remove them with ui-theme. `scrollbar.css` is the sole consumer of the `--dsw-alias-scrollbar-*` tokens and must follow `design-platform.css`, which declares them.
+`src/styles/` holds six sheets imported in order by ui-theme's dynamic client entry: `base.css`, `corner-shape.css`, `design-platform.css`, `scrollbar.css`, `gradient-shadow-text.css`, and `shiki.css`. The client bundle compiles and injects them as plugin-owned global styles, so unload and HMR remove them with ui-theme. `scrollbar.css` is the sole consumer of the `--dsw-alias-scrollbar-*` tokens and must follow `design-platform.css`, which declares them.
 
-`gradient-shadow-text.css` derives `--dsh-content-font-delta` from `--dsh-content-font-size` and shifts the Markdown heading and base-text ladder by that increment. It also derives the secondary tier `--dsh-content-font-size-secondary` (setting −1 at ≤14, setting −2 above; 13px at the default) with its own `--dsh-content-font-delta-secondary` for the table variants and the flow rows one step under the body. Dense small and code variants stay fixed. Outside the ladder, the user bubble and composer draft read the body pair directly, and flow-row titles and summaries read the secondary pair.
+`corner-shape.css` smooths every rounded corner: inside `@supports (corner-shape: superellipse(1.5))` it defines `--dsw-corner-shape` and applies it to all elements and their `::before`/`::after` through the universal selector, so engines without `corner-shape` keep circular corners. Full-round shapes — `border-radius: 50%` circles and pill radii — pair `corner-shape: round` with their radius in the owning component sheet because a superellipse deforms them; the corner-shape stylesheet spec enforces that pairing across every package stylesheet ([corner-smoothing note](../../../.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md)).
+
+`gradient-shadow-text.css` derives `--dsh-content-font-delta` from `--dsh-content-font-size` and shifts the Markdown heading and base-text ladder by that increment. It also derives the secondary tier `--dsh-content-font-size-secondary` (setting −1 at ≤14, setting −2 above; 13px at the default) with its own `--dsh-content-font-delta-secondary` for the table variants and the flow rows one step under the body. Dense small and code variants stay fixed. Outside the ladder, the user bubble and composer draft read the body pair directly, and flow-row titles and summaries read the secondary pair. The sheet also owns the shadow scale (`--dsw-shadow-lv*`) and the elevation tokens: `--dsw-elevation-stroke` draws a 0.5px hairline through the rebindable `--dsw-elevation-stroke-color`, and `--dsw-elevation-panel`/`--dsw-elevation-prominent` layer two faint soft shadows over that stroke, so elevated surfaces set `border: 0` and carry no layout-consuming outline ([elevation note](../../../.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md)).
 
 ### Scrollbar rebinding
 
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index dec856fde1..29a901020d 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -51,9 +51,11 @@ kind: "package-reference"
 
 ### 样式表
 
-`src/styles/` 下有五张样式表，由 ui-theme 的动态客户端 entry 依次导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。客户端 bundle 将其编译并注入为插件持有的全局样式，因此卸载与 HMR 会随 ui-theme 一同移除。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
+`src/styles/` 下有六张样式表，由 ui-theme 的动态客户端 entry 依次导入：`base.css`、`corner-shape.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。客户端 bundle 将其编译并注入为插件持有的全局样式，因此卸载与 HMR 会随 ui-theme 一同移除。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
 
-`gradient-shadow-text.css` 从 `--dsh-content-font-size` 派生 `--dsh-content-font-delta`，并以该增量移动 Markdown 标题与基础文本阶梯。它同时派生低一档变量 `--dsh-content-font-size-secondary`（设置 ≤14 时为设置值 −1，>14 时为设置值 −2；默认设置下为 13px）及配套的 `--dsh-content-font-delta-secondary`，供表格变体与比正文低一档的流内行使用。紧凑的小号文本与代码变体保持固定字号。阶梯之外，用户气泡与 composer 草稿直接读取正文档变量对，流内行的标题及摘要读取低一档变量对。
+`corner-shape.css` 平滑所有圆角：在 `@supports (corner-shape: superellipse(1.5))` 内定义 `--dsw-corner-shape`，并通过通配选择器应用到所有元素及其 `::before`/`::after`，因此不支持 `corner-shape` 的引擎保持普通圆弧。正圆形状——`border-radius: 50%` 的圆与胶囊半径——因超级椭圆会使其变形，须在所属组件样式表中把 `corner-shape: round` 与半径声明配对；corner-shape 样式表 spec 跨全部包样式表强制这一配对（[圆角平滑笔记](../../../.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md)）。
+
+`gradient-shadow-text.css` 从 `--dsh-content-font-size` 派生 `--dsh-content-font-delta`，并以该增量移动 Markdown 标题与基础文本阶梯。它同时派生低一档变量 `--dsh-content-font-size-secondary`（设置 ≤14 时为设置值 −1，>14 时为设置值 −2；默认设置下为 13px）及配套的 `--dsh-content-font-delta-secondary`，供表格变体与比正文低一档的流内行使用。紧凑的小号文本与代码变体保持固定字号。阶梯之外，用户气泡与 composer 草稿直接读取正文档变量对，流内行的标题及摘要读取低一档变量对。该表还持有阴影阶（`--dsw-shadow-lv*`）与 elevation token：`--dsw-elevation-stroke` 经可重绑的 `--dsw-elevation-stroke-color` 画 0.5px 发丝描边，`--dsw-elevation-panel`/`--dsw-elevation-prominent` 在描边之上叠两层极淡柔光，因此高层级表面设 `border: 0`，不再有占布局的轮廓（[elevation 笔记](../../../.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md)）。
 
 ### 滚动条重新绑定
 
diff --git a/packages/client/ui-theme/src/client/AppearanceRow.module.css b/packages/client/ui-theme/src/client/AppearanceRow.module.css
index 6c5354b0ac..0055a43c37 100644
--- a/packages/client/ui-theme/src/client/AppearanceRow.module.css
+++ b/packages/client/ui-theme/src/client/AppearanceRow.module.css
@@ -6,7 +6,7 @@
   flex-direction: column;
   gap: 8px;
   padding: 16px 0;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .title {
@@ -35,8 +35,8 @@
   justify-content: center;
   gap: 4px;
   padding: 20px 32px;
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 16px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: 20px;
   background: transparent;
   font: inherit;
   font-size: 14px;
diff --git a/packages/client/ui-theme/src/client/FontSizeRow.module.css b/packages/client/ui-theme/src/client/FontSizeRow.module.css
index f580667f4f..238ae91c6e 100644
--- a/packages/client/ui-theme/src/client/FontSizeRow.module.css
+++ b/packages/client/ui-theme/src/client/FontSizeRow.module.css
@@ -7,7 +7,7 @@
   align-items: center;
   gap: 8px;
   padding: 16px 0;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .rowText {
diff --git a/packages/client/ui-theme/src/client/styles.ts b/packages/client/ui-theme/src/client/styles.ts
index 88e4074bc1..2f7c97fd4b 100644
--- a/packages/client/ui-theme/src/client/styles.ts
+++ b/packages/client/ui-theme/src/client/styles.ts
@@ -1,5 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis'
 import base from '../styles/base.css?inline'
+import cornerShape from '../styles/corner-shape.css?inline'
 import designPlatform from '../styles/design-platform.css?inline'
 import scrollbar from '../styles/scrollbar.css?inline'
 import gradientShadowText from '../styles/gradient-shadow-text.css?inline'
@@ -9,6 +10,7 @@ const PLUGIN_ID = '@deepseek-ai/dsh-client-ui-theme'
 
 const STYLES = [
   ['base.css', base],
+  ['corner-shape.css', cornerShape],
   ['design-platform.css', designPlatform],
   ['scrollbar.css', scrollbar],
   ['gradient-shadow-text.css', gradientShadowText],
diff --git a/packages/client/ui-theme/src/styles/corner-shape.css b/packages/client/ui-theme/src/styles/corner-shape.css
new file mode 100644
index 0000000000..70197aa6a3
--- /dev/null
+++ b/packages/client/ui-theme/src/styles/corner-shape.css
@@ -0,0 +1,26 @@
+/* Smooth corner curvature for every rounded surface. Inside the support
+ * guard, all corners curve along superellipse(1.5) — between a circular arc
+ * (round = superellipse(1)) and a squircle (superellipse(2)) — instead of the
+ * default arc; engines without corner-shape keep circular corners because the
+ * token and the rule exist only inside the guard.
+ *
+ * corner-shape does not inherit, so the universal selector applies the token
+ * to elements and their ::before/::after; other pseudo-elements (for example
+ * the ::-webkit-scrollbar parts) stay circular.
+ *
+ * Full-round shapes opt out where they are declared: a superellipse deforms a
+ * circle into a squircle and squares off capsule ends, so every effectively
+ * uncapped radius (50%, 100%, or a pill radius far above the box size) pairs
+ * `corner-shape: round` with its `border-radius` in the owning component
+ * sheet. The corner-shape stylesheet spec enforces that pairing. */
+@supports (corner-shape: superellipse(1.5)) {
+  :root {
+    --dsw-corner-shape: superellipse(1.5);
+  }
+
+  *,
+  *::before,
+  *::after {
+    corner-shape: var(--dsw-corner-shape);
+  }
+}
diff --git a/packages/client/ui-theme/src/styles/gradient-shadow-text.css b/packages/client/ui-theme/src/styles/gradient-shadow-text.css
index a2d2597d89..b9e6eb25cd 100644
--- a/packages/client/ui-theme/src/styles/gradient-shadow-text.css
+++ b/packages/client/ui-theme/src/styles/gradient-shadow-text.css
@@ -7,6 +7,20 @@ body {
   --dsw-shadow-lv2: 0 4px 12px 0 rgba(0, 0, 0, 0.02), 0 2px 8px 0 rgba(0, 0, 0, 0.04);
   --dsw-shadow-lv3:
     0 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 4px 0 rgba(0, 0, 0, 0.02), 0 12px 32px 0 rgba(0, 0, 0, 0.08);
+  /* Elevation：浮层/面板/面型按钮的描边+投影三件套。0.5px 发丝描边画在
+     box-shadow 里（组件配 border: 0，不占布局），叠两层极淡柔光；深色主题下
+     柔光几乎不可见，由描边承担分离。描边颜色经 --dsw-elevation-stroke-color
+     间接，组件可重绑（菜单面与输入框重绑最浅的 l1，输入框的
+     workspace-trigger 态置 transparent 只保留柔光）。soft 供输入框：更大
+     模糊、更低透明度的柔光。 */
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l4);
+  --dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color);
+  --dsw-elevation-panel:
+    var(--dsw-elevation-stroke), 0 3px 8px 0 rgba(0, 0, 0, 0.03), 0 0 16px 0 rgba(0, 0, 0, 0.02);
+  --dsw-elevation-prominent:
+    var(--dsw-elevation-stroke), 0 3px 8px 0 rgba(0, 0, 0, 0.04), 0 0 20px 0 rgba(0, 0, 0, 0.05);
+  --dsw-elevation-soft:
+    var(--dsw-elevation-stroke), 0 4px 16px 0 rgba(0, 0, 0, 0.03), 0 0 24px 0 rgba(0, 0, 0, 0.03);
   /* blur filter */
   --dsw-mask-blur: blur(2px);
 }
diff --git a/packages/client/ui-theme/tests/client-styles.client.spec.ts b/packages/client/ui-theme/tests/client-styles.client.spec.ts
index b5d07e7bad..9e5cb8a7bd 100644
--- a/packages/client/ui-theme/tests/client-styles.client.spec.ts
+++ b/packages/client/ui-theme/tests/client-styles.client.spec.ts
@@ -21,6 +21,7 @@ describe('ui-theme client styles', () => {
     const styles = [...document.head.querySelectorAll<HTMLStyleElement>(`style[data-plugin="${PLUGIN_ID}"]`)]
     expect(styles.map(style => style.dataset.pluginCss)).toEqual([
       `${PLUGIN_ID}/base.css`,
+      `${PLUGIN_ID}/corner-shape.css`,
       `${PLUGIN_ID}/design-platform.css`,
       `${PLUGIN_ID}/scrollbar.css`,
       `${PLUGIN_ID}/gradient-shadow-text.css`,
diff --git a/packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts b/packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts
new file mode 100644
index 0000000000..b4569aeff8
--- /dev/null
+++ b/packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts
@@ -0,0 +1,80 @@
+/**
+ * Corner-shape stylesheet contract, asserted against the CSS text on disk:
+ * corner-shape.css smooths every rounded corner to the superellipse token
+ * strictly inside a `@supports` guard, and every effectively full-round radius
+ * in any package stylesheet pairs `corner-shape: round` in the same rule,
+ * because a superellipse deforms a circle into a squircle (a spinner would
+ * visibly wobble) and squares off capsule ends.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { atRuleBlock, packageStylesheets, parseRules } from './stylesheet-scan.ts'
+
+/** The support guard prelude, spelled exactly as the sheet must spell it. */
+const GUARD = '@supports (corner-shape: superellipse(1.5))'
+/** The smoothing token corner-shape.css owns. */
+const TOKEN = '--dsw-corner-shape'
+
+const sheetPath = fileURLToPath(new URL('../src/styles/corner-shape.css', import.meta.url))
+const sheetCss = readFileSync(sheetPath, 'utf8')
+
+/**
+ * Whether a border-radius value makes the element full-round: an uncapped
+ * fraction of the box (50%/100%) or a pill radius far above any box size.
+ * Component-local radius indirections stay below the pill threshold, so the
+ * check is lexical over literal components.
+ * @param value - a border-radius declaration value.
+ * @returns true when some component is full-round.
+ */
+function isFullRound(value: string): boolean {
+  return value.split(/\s+/).some(part =>
+    part === '50%' || part === '100%' || (part.endsWith('px') && Number.parseFloat(part) >= 99))
+}
+
+describe('corner-shape.css smoothing', () => {
+  const withoutComments = sheetCss.replace(/\/\*[\s\S]*?\*\//g, ' ')
+  const guard = atRuleBlock(withoutComments, GUARD)
+
+  it('declares the token and its application only inside the support guard', () => {
+    // Outside the guard the declarations would be dropped as invalid anyway,
+    // but only on engines without corner-shape; keeping everything inside the
+    // guard states that unsupporting engines keep plain circular corners.
+    expect(guard, GUARD).toBeDefined()
+    const before = withoutComments.slice(0, withoutComments.indexOf(GUARD))
+    const after = withoutComments.slice(guard!.end + 1)
+    expect(before.trim(), `content before ${GUARD}`).toBe('')
+    expect(after.trim(), `content after ${GUARD}`).toBe('')
+  })
+
+  it('defines the superellipse token on :root and applies it universally', () => {
+    // corner-shape does not inherit, so only the universal selector (with the
+    // generated ::before/::after) reaches every rounded surface.
+    const rules = parseRules(withoutComments.slice(guard!.start + 1, guard!.end))
+    const root = rules.find(rule => rule.selectors.includes(':root'))
+    expect(root?.declarations).toContainEqual([TOKEN, 'superellipse(1.5)'])
+    const universal = rules.find(rule => rule.selectors.includes('*'))
+    expect(universal?.selectors).toEqual(['*', '*::before', '*::after'])
+    expect(universal?.declarations).toContainEqual(['corner-shape', `var(${TOKEN})`])
+  })
+})
+
+describe('full-round radii keep circular corners', () => {
+  it('pairs corner-shape: round with every full-round border-radius under packages/', () => {
+    // The universal superellipse reaches every element, so each circle and
+    // pill states its own arc back; a new one without the pairing regresses
+    // silently on supporting engines only, which no jsdom test renders.
+    const unpaired: string[] = []
+    for (const file of packageStylesheets()) {
+      for (const rule of parseRules(readFileSync(file, 'utf8'))) {
+        const fullRound = rule.declarations
+          .some(([property, value]) => property === 'border-radius' && isFullRound(value))
+        if (!fullRound) continue
+        const paired = rule.declarations
+          .some(([property, value]) => property === 'corner-shape' && value === 'round')
+        if (!paired) unpaired.push(`${file} ${rule.selectors.join(', ')}`)
+      }
+    }
+    expect(unpaired).toEqual([])
+  })
+})
diff --git a/packages/client/ui-theme/tests/elevation-styles.client.spec.ts b/packages/client/ui-theme/tests/elevation-styles.client.spec.ts
new file mode 100644
index 0000000000..d70b265a00
--- /dev/null
+++ b/packages/client/ui-theme/tests/elevation-styles.client.spec.ts
@@ -0,0 +1,112 @@
+/**
+ * Elevation stylesheet contract, asserted against the CSS text on disk:
+ * gradient-shadow-text.css composes the elevation tokens from a rebindable
+ * 0.5px hairline stroke plus soft layers, and no package rule pairs an
+ * lv/elevation box-shadow with a neutral-border-token border — elevated
+ * surfaces draw their neutral stroke inside the elevation shadow (border: 0),
+ * never as a layout-consuming border beside it. State-colored borders (for
+ * example the warn approval panels) stay real borders and are out of scope.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { packageStylesheets, parseRules } from './stylesheet-scan.ts'
+
+/** Stroke-color indirection components may rebind per surface or state. */
+const STROKE_COLOR = '--dsw-elevation-stroke-color'
+/** Shadow-token references that mark a rule as an elevated surface. */
+const ELEVATED_SHADOW = /--dsw-(?:shadow-lv|elevation-)/
+/** Neutral border tokens; the state palette (--dsw-alias-state-*) stays allowed. */
+const NEUTRAL_BORDER = /--dsw-alias-border-/
+
+const sheetCss = readFileSync(
+  fileURLToPath(new URL('../src/styles/gradient-shadow-text.css', import.meta.url)), 'utf8')
+
+describe('elevation tokens', () => {
+  const declarations = new Map(parseRules(sheetCss)
+    .filter(rule => rule.selectors.includes('body'))
+    .flatMap(rule => rule.declarations))
+
+  it('draws the hairline stroke at 0.5px through the rebindable color indirection', () => {
+    expect(declarations.get(STROKE_COLOR)).toBe('var(--dsw-alias-border-l4)')
+    expect(declarations.get('--dsw-elevation-stroke')).toBe(`0 0 0 0.5px var(${STROKE_COLOR})`)
+  })
+
+  it('layers panel and prominent on top of the stroke', () => {
+    for (const name of ['--dsw-elevation-panel', '--dsw-elevation-prominent', '--dsw-elevation-soft']) {
+      expect(declarations.get(name), name).toMatch(/^var\(--dsw-elevation-stroke\), 0 /)
+    }
+  })
+})
+
+describe('elevated surfaces carry no neutral border', () => {
+  it('never pairs an lv/elevation shadow with a neutral border token under packages/', () => {
+    // A 1px border beside the elevation stroke double-draws the outline and
+    // shifts layout by the border width; the hairline belongs to the shadow.
+    const paired: string[] = []
+    for (const file of packageStylesheets()) {
+      for (const rule of parseRules(readFileSync(file, 'utf8'))) {
+        const elevated = rule.declarations
+          .some(([property, value]) => property === 'box-shadow' && ELEVATED_SHADOW.test(value))
+        if (!elevated) continue
+        const neutralBorder = rule.declarations.some(([property, value]) =>
+          property.startsWith('border') && !property.startsWith('border-radius') && NEUTRAL_BORDER.test(value))
+        if (neutralBorder) paired.push(`${file} ${rule.selectors.join(', ')}`)
+      }
+    }
+    expect(paired).toEqual([])
+  })
+})
+
+describe('neutral solid borders are hairlines', () => {
+  /** Border properties that carry a width in their shorthand. */
+  const BORDER_EDGE = /^border(?:-top|-bottom|-left|-right)?$/
+  /**
+   * Spinner ring tracks, keyed `<basename> <selector>`: the border is the
+   * drawn graphic (a rotating ring), not an outline, so it keeps its width.
+   */
+  const RING_TRACKS = new Set([
+    'boot-page.module.css .spinner',
+    'TrajectoryTable.module.css .historyLoadingSpinner',
+  ])
+
+  it('draws every solid neutral-token border at 0.5px under packages/', () => {
+    // Buttons, inputs, cards, and separators share the hairline weight;
+    // dashed affordances and state-colored borders are out of scope.
+    const wide: string[] = []
+    for (const file of packageStylesheets()) {
+      const base = file.slice(file.lastIndexOf('/') + 1)
+      for (const rule of parseRules(readFileSync(file, 'utf8'))) {
+        for (const [property, value] of rule.declarations) {
+          if (!BORDER_EDGE.test(property)) continue
+          if (!value.includes('solid') || !NEUTRAL_BORDER.test(value)) continue
+          if (value.startsWith('0.5px ')) continue
+          if (rule.selectors.some(selector => RING_TRACKS.has(`${base} ${selector}`))) continue
+          wide.push(`${file} ${rule.selectors.join(', ')} ${property}: ${value}`)
+        }
+      }
+    }
+    expect(wide).toEqual([])
+  })
+
+  it('draws every filled divider line at 0.5px under packages/', () => {
+    // A separator drawn as a filled box — 1px tall or wide with a border-token
+    // background (menu separators, the conversation header seam, markdown hr,
+    // vertical rails) — is the same hairline as a border. Visually-hidden 1px
+    // clip boxes carry no border-token background and stay exempt.
+    const wide: string[] = []
+    for (const file of packageStylesheets()) {
+      for (const rule of parseRules(readFileSync(file, 'utf8'))) {
+        const paintsLine = rule.declarations.some(([property, value]) =>
+          (property === 'background' || property === 'background-color') && NEUTRAL_BORDER.test(value))
+        if (!paintsLine) continue
+        for (const [property, value] of rule.declarations) {
+          if ((property === 'height' || property === 'width') && value === '1px') {
+            wide.push(`${file} ${rule.selectors.join(', ')} ${property}: ${value}`)
+          }
+        }
+      }
+    }
+    expect(wide).toEqual([])
+  })
+})
diff --git a/packages/client/ui-theme/tests/scrollbar-styles.client.spec.ts b/packages/client/ui-theme/tests/scrollbar-styles.client.spec.ts
index e9234846eb..c772bc92d5 100644
--- a/packages/client/ui-theme/tests/scrollbar-styles.client.spec.ts
+++ b/packages/client/ui-theme/tests/scrollbar-styles.client.spec.ts
@@ -8,19 +8,12 @@
  * design-platform.css, so adding, renaming, or dropping a scrollbar token
  * moves these assertions with it.
  */
-import { readdirSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
-
-/** One flattened CSS rule: its comma-separated selector parts and its declarations in source order. */
-interface CssRule {
-  selectors: string[]
-  declarations: [property: string, value: string][]
-}
+import { atRuleBlock, type CssRule, packageStylesheets, parseRules, varReferences } from './stylesheet-scan.ts'
 
 const STYLES = new URL('../src/styles/', import.meta.url)
-const PACKAGES_DIR = fileURLToPath(new URL('../../../', import.meta.url))
 const read = (name: string): string => readFileSync(fileURLToPath(new URL(name, STYLES)), 'utf8')
 
 const platformCss = read('design-platform.css')
@@ -40,81 +33,6 @@ const ELEVATED_REBIND = new Map([
   ['--dsh-scrollbar-thumb-hover', '--dsw-alias-scrollbar-hover-l2'],
 ].map(([property, token]) => [property!, `var(${token!})`]))
 
-/**
- * Flatten a stylesheet into rules. Whitespace, declaration order, and trailing
- * semicolons are normalized away; nesting and at-rules are not handled, which
- * no sheet under test uses for scrollbar declarations.
- * @param css - stylesheet text.
- * @returns one entry per rule, in source order.
- */
-function parseRules(css: string): CssRule[] {
-  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, ' ')
-  const rules: CssRule[] = []
-  // Destructuring defaults only satisfy noUncheckedIndexedAccess; both groups
-  // are unconditional in the pattern.
-  for (const [, selector = '', body = ''] of withoutComments.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
-    const declarations = body
-      .split(';')
-      .map(part => part.trim())
-      .filter(part => part.includes(':'))
-      .map((part): [string, string] => {
-        const colon = part.indexOf(':')
-        return [part.slice(0, colon).trim(), part.slice(colon + 1).trim()]
-      })
-    rules.push({ selectors: selector.split(',').map(part => part.trim()), declarations })
-  }
-  return rules
-}
-
-/**
- * Half-open source span of one at-rule's block, excluding its prelude.
- * @param css - stylesheet text.
- * @param prelude - exact at-rule prelude to locate, without the opening brace.
- * @returns the block's brace offsets, or undefined when the prelude is absent.
- */
-function atRuleBlock(css: string, prelude: string): { start: number; end: number } | undefined {
-  const opening = css.indexOf(`${prelude} {`)
-  if (opening === -1) return undefined
-  const start = css.indexOf('{', opening)
-  let depth = 0
-  for (let index = start; index < css.length; index += 1) {
-    if (css[index] === '{') depth += 1
-    else if (css[index] === '}') {
-      depth -= 1
-      if (depth === 0) return { start, end: index }
-    }
-  }
-  throw new Error(`unbalanced braces after ${prelude}`)
-}
-
-/**
- * Custom-property names a value reads.
- * @param value - declaration value, possibly with nested var() calls.
- * @returns every referenced custom-property name, in source order.
- */
-function varReferences(value: string): string[] {
-  return [...value.matchAll(/var\(\s*(--[\w-]+)/g)].map(([, name = '']) => name)
-}
-
-/**
- * Every CSS file shipped as package source, excluding build output and
- * installed dependencies.
- * @returns absolute paths of the stylesheets under packages/.
- */
-function packageStylesheets(): string[] {
-  const found: string[] = []
-  const walk = (dir: string): void => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const path = join(dir, entry.name)
-      if (entry.isDirectory()) {
-        if (entry.name !== 'node_modules' && entry.name !== 'lib' && entry.name !== 'dist') walk(path)
-      } else if (entry.name.endsWith('.css')) found.push(path)
-    }
-  }
-  walk(PACKAGES_DIR)
-  return found
-}
-
 /**
  * Tokens a stylesheet reads through its rendering declarations, following its
  * own custom-property definitions transitively so a token reached only through
diff --git a/packages/client/ui-theme/tests/stylesheet-scan.ts b/packages/client/ui-theme/tests/stylesheet-scan.ts
new file mode 100644
index 0000000000..d91e308889
--- /dev/null
+++ b/packages/client/ui-theme/tests/stylesheet-scan.ts
@@ -0,0 +1,91 @@
+/**
+ * Shared helpers for stylesheet-contract specs: flatten CSS text on disk into
+ * rules and enumerate the package stylesheets those contracts range over.
+ */
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** One flattened CSS rule: its comma-separated selector parts and its declarations in source order. */
+export interface CssRule {
+  selectors: string[]
+  declarations: [property: string, value: string][]
+}
+
+/** Root the package-wide stylesheet scans walk. */
+const PACKAGES_DIR = fileURLToPath(new URL('../../../', import.meta.url))
+
+/**
+ * Flatten a stylesheet into rules. Whitespace, declaration order, and trailing
+ * semicolons are normalized away; nesting is not handled, which no sheet under
+ * test uses, and at-rule preludes surface as selector-less rule boundaries.
+ * @param css - stylesheet text.
+ * @returns one entry per rule, in source order.
+ */
+export function parseRules(css: string): CssRule[] {
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, ' ')
+  const rules: CssRule[] = []
+  // Destructuring defaults only satisfy noUncheckedIndexedAccess; both groups
+  // are unconditional in the pattern.
+  for (const [, selector = '', body = ''] of withoutComments.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    const declarations = body
+      .split(';')
+      .map(part => part.trim())
+      .filter(part => part.includes(':'))
+      .map((part): [string, string] => {
+        const colon = part.indexOf(':')
+        return [part.slice(0, colon).trim(), part.slice(colon + 1).trim()]
+      })
+    rules.push({ selectors: selector.split(',').map(part => part.trim()), declarations })
+  }
+  return rules
+}
+
+/**
+ * Half-open source span of one at-rule's block, excluding its prelude.
+ * @param css - stylesheet text.
+ * @param prelude - exact at-rule prelude to locate, without the opening brace.
+ * @returns the block's brace offsets, or undefined when the prelude is absent.
+ */
+export function atRuleBlock(css: string, prelude: string): { start: number; end: number } | undefined {
+  const opening = css.indexOf(`${prelude} {`)
+  if (opening === -1) return undefined
+  const start = css.indexOf('{', opening)
+  let depth = 0
+  for (let index = start; index < css.length; index += 1) {
+    if (css[index] === '{') depth += 1
+    else if (css[index] === '}') {
+      depth -= 1
+      if (depth === 0) return { start, end: index }
+    }
+  }
+  throw new Error(`unbalanced braces after ${prelude}`)
+}
+
+/**
+ * Custom-property names a value reads.
+ * @param value - declaration value, possibly with nested var() calls.
+ * @returns every referenced custom-property name, in source order.
+ */
+export function varReferences(value: string): string[] {
+  return [...value.matchAll(/var\(\s*(--[\w-]+)/g)].map(([, name = '']) => name)
+}
+
+/**
+ * Every CSS file shipped as package source, excluding build output and
+ * installed dependencies.
+ * @returns absolute paths of the stylesheets under packages/.
+ */
+export function packageStylesheets(): string[] {
+  const found: string[] = []
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name !== 'node_modules' && entry.name !== 'lib' && entry.name !== 'dist') walk(path)
+      } else if (entry.name.endsWith('.css')) found.push(path)
+    }
+  }
+  walk(PACKAGES_DIR)
+  return found
+}
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css b/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css
index b33fb477c1..ed3e1cc942 100644
--- a/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css
@@ -8,5 +8,5 @@
   gap: 4px;
   margin: 4px 0 2px 22px;
   padding-left: 8px;
-  border-left: 1px solid var(--dsw-alias-border-l2);
+  border-left: 0.5px solid var(--dsw-alias-border-l2);
 }
diff --git a/packages/client/ui-tool/src/client/tool/components/AskQuestionCard.module.css b/packages/client/ui-tool/src/client/tool/components/AskQuestionCard.module.css
index 1c84154c42..71afa52c87 100644
--- a/packages/client/ui-tool/src/client/tool/components/AskQuestionCard.module.css
+++ b/packages/client/ui-tool/src/client/tool/components/AskQuestionCard.module.css
@@ -6,7 +6,7 @@
   margin: 4px 0 4px 4px;
   padding: 16px 20px;
   overflow-y: auto;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 12px;
   background: var(--dsw-alias-bg-base);
 }
diff --git a/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css b/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
index 2f344ac0dd..0fbe27ff10 100644
--- a/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
+++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
@@ -172,8 +172,9 @@
   gap: 4px;
   margin: 4px 0 2px 4px;
   padding: 2px 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   border-radius: 999px;
+  corner-shape: round;
   /* Base background, not bg-overlay: the overlay token is a raised dark
      surface and reads too heavy for a quiet in-flow affordance. */
   background: var(--dsw-alias-bg-base);
@@ -212,7 +213,7 @@
   display: flex;
   flex-direction: column;
   margin: 4px 0 4px 4px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 12px;
   background: var(--dsw-alias-markdown-code-block);
   font: var(--dsw-font-markdown-code-block-small);
@@ -260,7 +261,7 @@
    (it sits between the padded sections, not inside their grid). */
 .ioDivider {
   flex: none;
-  height: 1px;
+  height: 0.5px;
   background: var(--dsw-alias-border-l2);
 }
 
@@ -317,7 +318,7 @@
   --dsl-terminal-font: var(--dsw-font-markdown-code-block-small);
   --dsl-terminal-line-height: 18px;
   --dsl-terminal-output-max-height: 224px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
 }
 
 /* Visually hidden run-state label for assistive technology: the StateDot and
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css
index 4c1d7b18b0..ab93cbbaeb 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css
+++ b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css
@@ -17,7 +17,7 @@
   --dsl-terminal-line-height: 18px;
   --dsl-terminal-output-max-height: 224px;
   margin: 4px 0 4px 4px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
 }
 
 /* A bash execution error can settle without terminal-card material (for
@@ -27,7 +27,7 @@
   display: flex;
   flex-direction: column;
   margin: 4px 0 4px 4px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 12px;
   background: var(--dsw-alias-markdown-code-block);
   font: var(--dsw-font-markdown-code-block-small);
@@ -62,7 +62,7 @@
 
 .ioDivider {
   flex: none;
-  height: 1px;
+  height: 0.5px;
   background: var(--dsw-alias-border-l2);
 }
 
@@ -216,8 +216,9 @@
   gap: 4px;
   margin: 4px 0 2px 4px;
   padding: 2px 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 999px;
+  corner-shape: round;
   /* Base background, not bg-overlay: the overlay token reads too heavy. */
   background: var(--dsw-alias-bg-base);
   color: var(--dsw-alias-label-secondary);
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryCell.module.css b/packages/client/ui-trajectory/src/client/TrajectoryCell.module.css
index 013b1fd222..a0d270a303 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryCell.module.css
+++ b/packages/client/ui-trajectory/src/client/TrajectoryCell.module.css
@@ -9,7 +9,7 @@
   padding: 0 8px 0 20px;
   gap: 24px;
   border-radius: 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   background: var(--dsw-alias-bg-layer-3);
   min-width: 0;
 }
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryTable.module.css b/packages/client/ui-trajectory/src/client/TrajectoryTable.module.css
index 4602f925af..35266eed00 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryTable.module.css
+++ b/packages/client/ui-trajectory/src/client/TrajectoryTable.module.css
@@ -39,7 +39,7 @@
   justify-content: center;
   gap: 6px;
   box-sizing: border-box;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   background: var(--dsw-alias-bg-layer-1);
   color: var(--dsw-alias-label-secondary);
   font: var(--dsw-font-xxs-12);
@@ -52,6 +52,7 @@
   border: 1.5px solid var(--dsw-alias-border-l2);
   border-top-color: var(--dsw-alias-state-business-primary);
   border-radius: 50%;
+  corner-shape: round;
   animation: history-loading-spin 700ms linear infinite;
 }
 
@@ -148,7 +149,7 @@
   height: 30px;
   padding: 0 8px;
   overflow: hidden;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   color: var(--dsw-alias-label-tertiary);
   background: var(--dsw-specific-sidebar-fill);
   font: var(--dsw-font-xxs-12);
@@ -169,7 +170,7 @@
   height: 30px;
   padding: 0 8px;
   overflow: hidden;
-  border-bottom: 1px solid var(--dsw-alias-border-l1);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l1);
   text-overflow: ellipsis;
   white-space: nowrap;
 }
@@ -251,6 +252,7 @@
   width: 5px;
   height: 5px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-label-caption);
   box-shadow:
     0 0 0 2px var(--dsw-alias-bg-layer-1),
@@ -267,7 +269,7 @@
   left: 17px;
   width: max-content;
   padding: 0 4px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 2px;
   color: var(--dsw-alias-label-secondary);
   background: var(--dsw-alias-bg-layer-1);
@@ -447,9 +449,9 @@
 }
 
 .kindSlot :global([role='tooltip']) {
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0;
   background: var(--dsw-alias-bg-layer-2);
-  box-shadow: var(--dsw-shadow-lv2);
+  box-shadow: var(--dsw-elevation-panel);
   color: var(--dsw-alias-label-primary);
 }
 
@@ -870,7 +872,7 @@
   max-width: calc(100% - 280px);
   min-width: 0;
   min-height: 0;
-  border-left: 1px solid var(--dsw-alias-border-l2);
+  border-left: 0.5px solid var(--dsw-alias-border-l2);
   background: var(--dsw-alias-bg-layer-1);
 }
 
@@ -901,7 +903,7 @@
   box-sizing: border-box;
   height: 42px;
   padding: 0 8px 0 12px;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .detailsTitle {
@@ -917,6 +919,7 @@
   width: 5px;
   height: 5px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-label-secondary);
 }
 
@@ -968,7 +971,7 @@
   overflow-x: auto;
   overflow-y: hidden;
   gap: 1px;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   overscroll-behavior-x: contain;
   scrollbar-width: none;
   white-space: nowrap;
@@ -1644,7 +1647,7 @@
 }
 
 .toolCatalogItem {
-  border-bottom: 1px solid var(--dsw-alias-border-l1);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l1);
 }
 
 .toolCatalogSummary {
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryTimeline.module.css b/packages/client/ui-trajectory/src/client/TrajectoryTimeline.module.css
index 4d51548ff3..a10fffb9d1 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryTimeline.module.css
+++ b/packages/client/ui-trajectory/src/client/TrajectoryTimeline.module.css
@@ -3,7 +3,7 @@
   z-index: 1;
   isolation: isolate;
   flex: none;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   user-select: none;
 }
 
@@ -21,7 +21,7 @@
 
 .labels {
   position: relative;
-  border-right: 1px solid var(--dsw-alias-border-l1);
+  border-right: 0.5px solid var(--dsw-alias-border-l1);
   color: var(--dsw-alias-label-caption);
   font: var(--dsw-font-xs-13);
   font-size: 10px;
@@ -146,7 +146,7 @@
   top: 0;
   bottom: 0;
   left: var(--trajectory-turn-left);
-  width: 1px;
+  width: 0.5px;
   background: var(--dsw-alias-border-l2);
 }
 
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryToolbar.module.css b/packages/client/ui-trajectory/src/client/TrajectoryToolbar.module.css
index aa38650411..c286665666 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryToolbar.module.css
+++ b/packages/client/ui-trajectory/src/client/TrajectoryToolbar.module.css
@@ -5,7 +5,7 @@
   box-sizing: border-box;
   width: 100%;
   height: var(--dsh-trajectory-toolbar-height);
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
   background: var(--dsw-alias-bg-layer-1);
 }
 
@@ -122,6 +122,7 @@
   width: 6px;
   height: 6px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-bg-layer-1);
   transition: transform 120ms var(--ds-ease-in-out);
 }
@@ -173,7 +174,7 @@
   margin-left: auto;
   padding: 0 6px;
   gap: 4px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 4px;
   color: var(--dsw-alias-label-caption);
   background: var(--dsw-alias-bg-layer-2);
diff --git a/packages/client/ui-user-questions/src/client/PlanReviewPanel.module.css b/packages/client/ui-user-questions/src/client/PlanReviewPanel.module.css
index 6c97273755..bbe543610c 100644
--- a/packages/client/ui-user-questions/src/client/PlanReviewPanel.module.css
+++ b/packages/client/ui-user-questions/src/client/PlanReviewPanel.module.css
@@ -50,6 +50,7 @@
   width: 8px;
   height: 8px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-state-warn-primary);
 }
 
diff --git a/packages/client/ui-user-questions/src/client/QuestionComposer.module.css b/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
index 3c554e22dc..10d108d3df 100644
--- a/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
+++ b/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
@@ -19,10 +19,11 @@
      so header and footer actions stay reachable on long batches. */
   max-height: min(60vh, 520px);
   padding: 0 0 10px;
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border: 0;
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l2-darkmode-thin);
   border-radius: 20px;
   background: var(--dsw-specific-input-major);
-  box-shadow: var(--dsw-shadow-lv2);
+  box-shadow: var(--dsw-elevation-panel);
   color: var(--dsw-alias-label-primary);
   overflow: hidden;
   /* Elevated surface in dark, same as the menus: the body inside scrolls
@@ -128,6 +129,7 @@
   padding: 0;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: transparent;
   color: var(--dsw-alias-label-tertiary);
   cursor: pointer;
@@ -236,7 +238,7 @@
   grid-area: 1 / 1;
   width: 14px;
   height: 14px;
-  border: 1px solid var(--dsw-alias-border-l4);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 4px;
   transition: background-color 120ms ease, border-color 120ms ease;
 }
@@ -388,7 +390,7 @@
   min-height: 64px;
   flex-shrink: 0;
   margin: 0 12px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 10px;
   background: var(--dsw-alias-bg-module-platform);
   --dsh-answer-field-padding: 8px 12px;
diff --git a/packages/client/ui-workflow-run/src/client/WorkflowRunPanel.module.css b/packages/client/ui-workflow-run/src/client/WorkflowRunPanel.module.css
index aa4ff56a3d..f2d1489bd9 100644
--- a/packages/client/ui-workflow-run/src/client/WorkflowRunPanel.module.css
+++ b/packages/client/ui-workflow-run/src/client/WorkflowRunPanel.module.css
@@ -138,6 +138,7 @@
   width: 2px;
   height: 2px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-label-tertiary);
 }
 
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.module.css b/packages/client/ui-workspace/src/client/rows/Rows.module.css
index dd41b87b37..7208d4d4b1 100644
--- a/packages/client/ui-workspace/src/client/rows/Rows.module.css
+++ b/packages/client/ui-workspace/src/client/rows/Rows.module.css
@@ -181,7 +181,7 @@
   font-size: 14px;
   line-height: 20px;
   padding: 0 2px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 4px;
   background: var(--dsw-alias-button-elevated-fill);
   color: inherit;
diff --git a/packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.module.css b/packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.module.css
index dd9ee488bf..1ce0f8e1b2 100644
--- a/packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.module.css
+++ b/packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.module.css
@@ -23,6 +23,7 @@
   height: 28px;
   border: none;
   border-radius: 50%;
+  corner-shape: round;
   padding: 0;
   background: transparent;
   cursor: pointer;
@@ -139,6 +140,7 @@
   box-sizing: border-box;
   border: none;
   border-radius: 50%;
+  corner-shape: round;
   background: transparent;
   cursor: text;
   color: var(--dsw-alias-label-secondary);
@@ -155,7 +157,7 @@
   height: 30px;
   margin-inline: -2px;
   padding: 0 4px 0 0;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 10px;
   background: transparent;
   color: var(--dsw-alias-label-caption);
@@ -170,6 +172,7 @@
   height: 28px;
   border: none;
   border-radius: 50%;
+  corner-shape: round;
   padding: 0;
   background: transparent;
   cursor: pointer;
@@ -223,6 +226,7 @@
   height: 24px;
   border: none;
   border-radius: 50%;
+  corner-shape: round;
   padding: 0;
   background: transparent;
   cursor: pointer;
@@ -455,7 +459,7 @@
   width: 100%;
   height: 44px;
   padding: 7px 14px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 22px;
   outline: none;
   background: transparent;
diff --git a/packages/client/web/src/boot-page.module.css b/packages/client/web/src/boot-page.module.css
index 13a7064c49..2a8bf33c79 100644
--- a/packages/client/web/src/boot-page.module.css
+++ b/packages/client/web/src/boot-page.module.css
@@ -49,6 +49,7 @@
   width: 20px;
   height: 20px;
   border-radius: 50%;
+  corner-shape: round;
   border: 2px solid var(--dsw-alias-border-l2, var(--dsh-boot-border));
   animation: spin 0.8s linear infinite;
 }
diff --git a/packages/experimental/client-ui-agent-team/src/client/TeamAction.module.css b/packages/experimental/client-ui-agent-team/src/client/TeamAction.module.css
index 8de88e2e33..bd9f75be52 100644
--- a/packages/experimental/client-ui-agent-team/src/client/TeamAction.module.css
+++ b/packages/experimental/client-ui-agent-team/src/client/TeamAction.module.css
@@ -52,10 +52,11 @@
   max-height: min(680px, calc(100vh - 120px));
   padding: 10px;
   overflow: auto;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0;
   border-radius: 12px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
 }
 
 .toolbar,
@@ -103,7 +104,7 @@
   gap: 8px;
   min-width: 0;
   padding: 8px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 8px;
   background: transparent;
   color: var(--dsw-alias-label-primary);
@@ -151,7 +152,7 @@
 .task,
 .form {
   padding: 9px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 9px;
   background: var(--dsw-alias-bg-base);
 }
@@ -192,7 +193,7 @@
 .form input,
 .form textarea {
   box-sizing: border-box;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 6px;
   background: var(--dsw-alias-bg-base);
   color: var(--dsw-alias-label-primary);
diff --git a/packages/extensions/ui-cordis/src/client/CordisDefineRow.module.css b/packages/extensions/ui-cordis/src/client/CordisDefineRow.module.css
index fdc2ebbf55..7390f9a0de 100644
--- a/packages/extensions/ui-cordis/src/client/CordisDefineRow.module.css
+++ b/packages/extensions/ui-cordis/src/client/CordisDefineRow.module.css
@@ -166,7 +166,7 @@
 .sourceTabs {
   display: flex;
   height: 32px;
-  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 
 .sourceTab {
@@ -240,7 +240,7 @@
 .output {
   margin: 0;
   padding: 8px 10px;
-  border: 1px solid var(--dsw-alias-border-l1);
+  border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 8px;
   background: var(--dsw-alias-markdown-code-block);
   white-space: pre-wrap;
@@ -260,8 +260,9 @@
   gap: 4px;
   margin: 4px 0 2px 4px;
   padding: 2px 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 999px;
+  corner-shape: round;
   background: var(--dsw-alias-bg-base);
   color: var(--dsw-alias-label-secondary);
   font-size: 11px;
diff --git a/packages/extensions/ui-cordis/src/client/CordisPanel.module.css b/packages/extensions/ui-cordis/src/client/CordisPanel.module.css
index 1a10f07ee3..3b7764f5f1 100644
--- a/packages/extensions/ui-cordis/src/client/CordisPanel.module.css
+++ b/packages/extensions/ui-cordis/src/client/CordisPanel.module.css
@@ -71,6 +71,7 @@
   height: 36px;
   padding: 0;
   border-radius: 50%;
+  corner-shape: round;
 }
 
 .rail .footerButtons {
@@ -89,10 +90,11 @@
   max-width: calc(100vw - 24px);
   max-height: 60vh;
   overflow: hidden;
-  border: 1px solid var(--dsw-alias-border-inverted);
+  border: 0;
   border-radius: 12px;
   background: var(--dsw-specific-menu);
-  box-shadow: var(--dsw-shadow-lv3);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
   /* Only `.body` scrolls; the header remains fixed above it. */
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
@@ -159,7 +161,7 @@
   flex-direction: column;
   gap: 8px;
   padding: 14px 12px 10px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 12px;
 }
 
@@ -248,7 +250,7 @@
   flex: 1;
   height: 26px;
   padding: 0 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   border-radius: 7px;
   background: transparent;
   color: var(--dsw-alias-label-secondary);
@@ -297,8 +299,9 @@
 
 .transitionActions button {
   padding: 2px 8px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l3);
   border-radius: 999px;
+  corner-shape: round;
   background: transparent;
   color: var(--dsw-alias-label-secondary);
   font: inherit;
@@ -331,6 +334,7 @@
   padding: 0;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: transparent;
   color: var(--dsw-alias-label-tertiary);
   cursor: pointer;
diff --git a/packages/extensions/ui-cordis/src/client/CordisRunRow.module.css b/packages/extensions/ui-cordis/src/client/CordisRunRow.module.css
index 262dd1b612..3f545b01fb 100644
--- a/packages/extensions/ui-cordis/src/client/CordisRunRow.module.css
+++ b/packages/extensions/ui-cordis/src/client/CordisRunRow.module.css
@@ -31,6 +31,7 @@
   height: 2px;
   margin: 0 8px;
   border-radius: 50%;
+  corner-shape: round;
   background: var(--dsw-alias-state-business-primary);
 }
 
@@ -81,6 +82,7 @@
   padding: 0;
   border: none;
   border-radius: 999px;
+  corner-shape: round;
   background: transparent;
   color: var(--dsw-alias-label-tertiary);
   cursor: pointer;
@@ -108,7 +110,7 @@
 .business {
   min-width: 0;
   overflow: hidden;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 12px;
   background: var(--dsw-alias-bg-base);
 }
@@ -117,7 +119,7 @@
   margin: 0;
   padding: 10px 12px;
   overflow: auto;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 8px;
   background: var(--dsw-alias-markdown-code-block);
   color: var(--dsw-alias-label-secondary);
diff --git a/packages/session-query/session-log-export/src/client/HeaderAction.module.css b/packages/session-query/session-log-export/src/client/HeaderAction.module.css
index 288e7f9bae..ef6f6cfdf3 100644
--- a/packages/session-query/session-log-export/src/client/HeaderAction.module.css
+++ b/packages/session-query/session-log-export/src/client/HeaderAction.module.css
@@ -6,7 +6,7 @@
   height: 32px;
   padding: 6px 12px;
   gap: 4px;
-  border: 1px solid var(--dsw-alias-border-l2);
+  border: 0.5px solid var(--dsw-alias-border-l4);
   border-radius: 18px;
   color: var(--dsw-alias-label-primary);
   background: transparent;

From b873b9321e7512adaa70738fe2be344f28777621 Mon Sep 17 00:00:00 2001
From: "yx.zhang" <yx.zhang@yxzhangdeMacBook-Pro.local>
Date: Tue, 1 Sep 2026 19:15:56 +0800
Subject: [PATCH 02/37] fix(web): per-element elevation tokens and review sync

Re-declare the derived elevation tokens on body * so per-surface
--dsw-elevation-stroke-color rebinds reach the consuming shadow (custom
properties inherit with var() already substituted); pin that mechanism
and add synthetic rejection cases to the stylesheet scans; take the
ring-track basenames through node:path so the exemption matches on
Windows; update the ModelsSection row-card spec to the hairline recipe;
align the elevation note with the shipped l1 menu rebind, refresh the
feedback-popover note's surface recipe, and document the soft tier.
---
 ...-13-feedback-note-editor-popover.i18n.yaml |   4 +-
 ...2026-08-13-feedback-note-editor-popover.md |   2 +-
 ...6-08-13-feedback-note-editor-popover.zh.md |   2 +-
 ...-01-web-elevation-stroke-shadows.i18n.yaml |   4 +-
 ...2026-09-01-web-elevation-stroke-shadows.md |   2 +-
 ...6-09-01-web-elevation-stroke-shadows.zh.md |   2 +-
 docs/web-styling.i18n.yaml                    |   4 +-
 docs/web-styling.md                           |   2 +-
 docs/web-styling.zh.md                        |   2 +-
 .../tests/styles.client.spec.ts               |   2 +-
 packages/client/ui-theme/README.i18n.yaml     |   4 +-
 packages/client/ui-theme/README.md            |   2 +-
 packages/client/ui-theme/README.zh.md         |   2 +-
 .../src/styles/gradient-shadow-text.css       |  15 +-
 .../tests/corner-shape-styles.client.spec.ts  |  33 ++--
 .../tests/elevation-styles.client.spec.ts     | 162 +++++++++++++-----
 16 files changed, 167 insertions(+), 77 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.i18n.yaml
index c7289d869f..ac3e62bf89 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.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 .agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.md
-2026-08-13-feedback-note-editor-popover.md: 42c08e39cfb054db689503e23306c5049a97b6cb
-2026-08-13-feedback-note-editor-popover.zh.md: 553029f8a42dae42a38e909d716b41e2c6dd252e
+2026-08-13-feedback-note-editor-popover.md: 8f51f090cc24292ad02d96fefb1f45bc05df08c9
+2026-08-13-feedback-note-editor-popover.zh.md: e64e95ac6599be2d7c343b4432415f0e99c6ef9b
diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.md b/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.md
index 42c08e39cf..8f51f090cc 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.md
@@ -18,7 +18,7 @@ The note editor does not enter the row's flex layout at all. It is a popover: a
 
 **The action strip.** The like/dislike buttons and the note trigger stay in the row, unchanged. The trigger is a plain button (`aria-haspopup="dialog"`, `aria-expanded` while open) that shows "Add a note" before a note exists and the note text afterward.
 
-**The popover.** While open, the panel contains the textarea plus Save and Cancel, and any note-save failure, as `role="dialog"` with a title distinct from the textarea's own label so both are addressable by name. It opens beneath the trigger (4px gap), clamps to 12px from the viewport edges, auto-focuses the textarea, and closes on Escape or an outside pointer-down. Closing returns focus to the trigger only when the panel was really open, never on the initial mount (a freshly rendered rated message must not pull focus into its action row). A rating action during an open editor closes the panel. The four undefined tokens are replaced with the ones the theme actually defines, matching the primitives' precedent: `border-l2` and `bg-layer-1` for the input, `button-primary-fill` with `label-primary-foreground` plus a `button-primary-hover` state for Save; the panel surface reuses the Menu card recipe (`--dsw-specific-menu`, `--dsw-shadow-lv3`, inverted hairline `--dsw-alias-border-inverted`, `border-radius: 12px`).
+**The popover.** While open, the panel contains the textarea plus Save and Cancel, and any note-save failure, as `role="dialog"` with a title distinct from the textarea's own label so both are addressable by name. It opens beneath the trigger (4px gap), clamps to 12px from the viewport edges, auto-focuses the textarea, and closes on Escape or an outside pointer-down. Closing returns focus to the trigger only when the panel was really open, never on the initial mount (a freshly rendered rated message must not pull focus into its action row). A rating action during an open editor closes the panel. The four undefined tokens are replaced with the ones the theme actually defines, matching the primitives' precedent: `border-l2` and `bg-layer-1` for the input, `button-primary-fill` with `label-primary-foreground` plus a `button-primary-hover` state for Save; the panel surface reuses the Menu card surface recipe (`--dsw-specific-menu`, the `--dsw-elevation-prominent` shadow with the `--dsw-alias-border-l1` stroke rebind and `border: 0`) at `border-radius: 12px`.
 
 **Failure surfaces split by where the human is looking.** A rating or list-load failure shows beside the buttons in the row, legible whether or not the popover is open. A note-save failure shows inside the popover, next to Save/Cancel, and the panel stays open so the draft survives to be corrected.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.zh.md b/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.zh.md
index 553029f8a4..e64e95ac65 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 **操作条。** 点赞/点踩按钮与备注触发按钮保持原样留在行内。触发按钮是普通 `button`（`aria-haspopup="dialog"`，打开时 `aria-expanded`），在没有备注时显示「补充说明」，已有备注时显示备注文本。
 
-**浮层。** 打开时，面板内含 textarea、Save 与 Cancel，以及任何备注保存失败提示，作为 `role="dialog"`，其标题与 textarea 自身的标签不同，以便两者都能按名称寻址。它在触发按钮下方打开（4px 间距），钳制到距视口边缘 12px，自动聚焦 textarea，并在 Escape 或外部 pointer-down 时关闭。关闭时仅当面板确实曾经打开才把焦点还给触发按钮，绝不会在初始挂载时（新渲染出的一条已评分消息不得把焦点拉进其操作条）。编辑器打开时进行评分操作会关闭面板。四个未定义 token 换成主题确实定义的那些，与 primitives 的既有做法一致：输入框用 `border-l2` 与 `bg-layer-1`，Save 用 `button-primary-fill` 配 `label-primary-foreground` 并加 `button-primary-hover` 状态；面板表面复用 Menu 卡片的配方（`--dsw-specific-menu`、`--dsw-shadow-lv3`、反色发丝线 `--dsw-alias-border-inverted`、`border-radius: 12px`）。
+**浮层。** 打开时，面板内含 textarea、Save 与 Cancel，以及任何备注保存失败提示，作为 `role="dialog"`，其标题与 textarea 自身的标签不同，以便两者都能按名称寻址。它在触发按钮下方打开（4px 间距），钳制到距视口边缘 12px，自动聚焦 textarea，并在 Escape 或外部 pointer-down 时关闭。关闭时仅当面板确实曾经打开才把焦点还给触发按钮，绝不会在初始挂载时（新渲染出的一条已评分消息不得把焦点拉进其操作条）。编辑器打开时进行评分操作会关闭面板。四个未定义 token 换成主题确实定义的那些，与 primitives 的既有做法一致：输入框用 `border-l2` 与 `bg-layer-1`，Save 用 `button-primary-fill` 配 `label-primary-foreground` 并加 `button-primary-hover` 状态；面板表面复用 Menu 卡片的表面配方（`--dsw-specific-menu`、`--dsw-elevation-prominent` 投影配 `--dsw-alias-border-l1` 描边重绑与 `border: 0`），圆角取 `border-radius: 12px`。
 
 **失败提示按人的视线所落之处拆分。** 评分或列表加载失败显示在按钮旁的图标行里，无论浮层是否打开都清晰可读。备注保存失败显示在浮层内、Save/Cancel 旁，且面板保持打开，以便草稿留存待修正。
 
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
index 04bab8384f..fa75bdb9ba 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.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 .agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
-2026-09-01-web-elevation-stroke-shadows.md: 9d5789038267d4fc5693cc46bb8870a4410ce080
-2026-09-01-web-elevation-stroke-shadows.zh.md: 9ad34a6f15098710ee4cee34142c95c4c60e27fe
+2026-09-01-web-elevation-stroke-shadows.md: 774c9d996958cbc46cb21daaed928f9386c33421
+2026-09-01-web-elevation-stroke-shadows.zh.md: cb6dd3563952d97725d5e451c56e7fa7a710abaf
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
index 9d57890382..774c9d9969 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
@@ -12,7 +12,7 @@ Elevated web-client surfaces — menus, popovers, modals, panels, floating butto
 
 `gradient-shadow-text.css` (the ui-theme shadow owner) defines the elevation tokens beside the `--dsw-shadow-lv*` scale:
 
-- `--dsw-elevation-stroke-color` — the hairline color, defaulting to `--dsw-alias-border-l4` (black 16% light, white 20% dark); components rebind it per surface or state, and every menu-fill surface (`--dsw-specific-menu` background) rebinds the lighter `--dsw-alias-border-l2` so dropdown menus keep a quieter stroke than panels and buttons.
+- `--dsw-elevation-stroke-color` — the hairline color, defaulting to `--dsw-alias-border-l4` (black 16% light, white 20% dark); components rebind it per surface or state, and every menu-fill surface (`--dsw-specific-menu` background) and the composer rebind the lightest `--dsw-alias-border-l1`, both quieter than panels and buttons. The default is declared on `body` alone while the derived tokens below are re-declared on `body, body *`: a custom property computes with `var()` already substituted, so body-only derived tokens would bake in body's color and make every rebind a no-op (the same per-element re-substitution scrollbar.css states for `--dsh-scrollbar-thumb`).
 - `--dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color)` — the stroke alone, used standalone by inline cards that want only an outline (the plugin-inventory card).
 - `--dsw-elevation-panel` / `--dsw-elevation-prominent` — the stroke plus two faint soft layers (3px directional + 16/20px glow at 2–5% black), panel for small floating widgets and cards, prominent for floats, and soft — larger blur at lower alpha — for the composer.
 
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
index 9ad34a6f15..cb6dd35639 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
@@ -12,7 +12,7 @@ Web 客户端的高层级表面——菜单、浮层、对话框、面板、悬
 
 `gradient-shadow-text.css`（ui-theme 的阴影归属地）在 `--dsw-shadow-lv*` 阶旁定义 elevation token：
 
-- `--dsw-elevation-stroke-color`——发丝描边颜色，默认 `--dsw-alias-border-l4`（浅色黑 16%、深色白 20%）；组件可按表面或状态重绑：所有菜单面（`--dsw-specific-menu` 背景）与输入框重绑最浅的 `--dsw-alias-border-l1`，两者都比面板与按钮安静。
+- `--dsw-elevation-stroke-color`——发丝描边颜色，默认 `--dsw-alias-border-l4`（浅色黑 16%、深色白 20%）；组件可按表面或状态重绑：所有菜单面（`--dsw-specific-menu` 背景）与输入框重绑最浅的 `--dsw-alias-border-l1`，两者都比面板与按钮安静。默认色只声明在 `body` 上，而下述派生 token 在 `body, body *` 上逐元素重声明：自定义属性的计算值已替换完 `var()`，派生 token 若只在 body 声明会把 body 的颜色固化进去，让所有重绑失效（与 scrollbar.css 对 `--dsh-scrollbar-thumb` 声明的逐元素重替换是同一契约）。
 - `--dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color)`——单独的描边，供只要轮廓的行内卡片独立使用（插件清单卡片）。
 - `--dsw-elevation-panel` / `--dsw-elevation-prominent`——描边加两层极淡柔光（3px 方向光 + 16/20px 辉光，黑 2–5%），panel 用于小型悬浮部件与卡片，prominent 用于浮层，soft——更大模糊、更低透明度——用于输入框。
 
diff --git a/docs/web-styling.i18n.yaml b/docs/web-styling.i18n.yaml
index 536aabb6f9..c9e35b8d5f 100644
--- a/docs/web-styling.i18n.yaml
+++ b/docs/web-styling.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 docs/web-styling.md
-web-styling.md: 1fa79acba6289f7364846909a996f504785ff628
-web-styling.zh.md: 126011f0c8e4ff6832daa46e3c5096899a632171
+web-styling.md: dd057a3121422e4decfac06b9a3cf57e52254011
+web-styling.zh.md: 5ec0b65390b29e915fe3da633bb7c56ef92e17d6
diff --git a/docs/web-styling.md b/docs/web-styling.md
index 1fa79acba6..dd057a3121 100644
--- a/docs/web-styling.md
+++ b/docs/web-styling.md
@@ -20,7 +20,7 @@ Global style sheets belong in `ui-theme/src/styles/`. Component styles live besi
 - Put presentation in CSS. Inline React styles may pass component-local custom-property values but must not encode theme branches.
 - Preserve keyboard focus visibility and reduced-motion behavior when adding transitions or hover-only controls.
 - Rounded corners inherit the global superellipse smoothing from ui-theme's `corner-shape.css` on supporting engines. Pair `corner-shape: round` with every full-round `border-radius` (`50%`, `100%`, or a pill radius) so circles and capsules keep circular arcs; the ui-theme corner-shape spec enforces the pairing.
-- Elevated surfaces (menus, popovers, modals, panels, floating buttons, the composer) set `border: 0` and take `box-shadow: var(--dsw-elevation-panel)` or `var(--dsw-elevation-prominent)`: the 0.5px hairline stroke is the first shadow layer, and `--dsw-elevation-stroke-color` rebinds or suppresses it per surface or state. Never pair a `--dsw-alias-border-*` border with an lv/elevation shadow — the ui-theme elevation spec rejects the pairing; state-colored borders (warn panels) stay real borders.
+- Elevated surfaces (menus, popovers, modals, panels, floating buttons, the composer) set `border: 0` and take `box-shadow: var(--dsw-elevation-panel)`, `var(--dsw-elevation-prominent)`, or the composer's `var(--dsw-elevation-soft)` (larger blur at lower alpha): the 0.5px hairline stroke is the first shadow layer, and `--dsw-elevation-stroke-color` rebinds or suppresses it per surface or state. Never pair a `--dsw-alias-border-*` border with an lv/elevation shadow — the ui-theme elevation spec rejects the pairing; state-colored borders (warn panels) stay real borders.
 - Flat borders and separators that use a neutral `--dsw-alias-border-*` token draw at `0.5px` — buttons, inputs, cards, row dividers, and separators drawn as filled boxes (menu separators, the conversation header seam, markdown `hr`, vertical rails) share the hairline weight, which Chromium paints as one device pixel. Dashed affordances and state-colored borders keep 1px; spinner ring tracks keep their width through the spec's explicit allowlist. The ui-theme elevation spec rejects wider neutral solid borders.
 
 ## Changing the system
diff --git a/docs/web-styling.zh.md b/docs/web-styling.zh.md
index 126011f0c8..5ec0b65390 100644
--- a/docs/web-styling.zh.md
+++ b/docs/web-styling.zh.md
@@ -20,7 +20,7 @@
 - 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
 - 支持的引擎上，圆角继承 ui-theme `corner-shape.css` 的全局超级椭圆平滑。每个正圆 `border-radius`（`50%`、`100%` 或胶囊半径）必须配对 `corner-shape: round`，使圆形与胶囊保持圆弧；ui-theme 的 corner-shape spec 强制这一配对。
-- 高层级表面（菜单、浮层、对话框、面板、悬浮按钮、输入框）设 `border: 0` 并使用 `box-shadow: var(--dsw-elevation-panel)` 或 `var(--dsw-elevation-prominent)`：0.5px 发丝描边是第一层投影，`--dsw-elevation-stroke-color` 可按表面或状态重绑或抑制描边。不得将 `--dsw-alias-border-*` border 与 lv/elevation 投影配对——ui-theme 的 elevation spec 会拒绝；状态色 border（warn 面板）保持真 border。
+- 高层级表面（菜单、浮层、对话框、面板、悬浮按钮、输入框）设 `border: 0` 并使用 `box-shadow: var(--dsw-elevation-panel)`、`var(--dsw-elevation-prominent)` 或输入框专用的 `var(--dsw-elevation-soft)`（更大模糊、更低透明度）：0.5px 发丝描边是第一层投影，`--dsw-elevation-stroke-color` 可按表面或状态重绑或抑制描边。不得将 `--dsw-alias-border-*` border 与 lv/elevation 投影配对——ui-theme 的 elevation spec 会拒绝；状态色 border（warn 面板）保持真 border。
 - 使用中性 `--dsw-alias-border-*` token 的平面边框与分割线一律 `0.5px`——按钮、输入框、卡片、行分割线，以及以填充盒绘制的分隔线（菜单分隔、对话标题栏接缝、markdown `hr`、竖向轨道线）共用发丝线粗细，Chromium 将其绘制为一个设备像素。dashed 记号与状态色 border 保持 1px；spinner 圆环经 spec 的显式豁免保留原宽度。更宽的中性 solid border 会被 ui-theme elevation spec 拒绝。
 
 ## 变更系统
diff --git a/packages/client/ui-settings-models/tests/styles.client.spec.ts b/packages/client/ui-settings-models/tests/styles.client.spec.ts
index 526a2a5b07..16a698de5f 100644
--- a/packages/client/ui-settings-models/tests/styles.client.spec.ts
+++ b/packages/client/ui-settings-models/tests/styles.client.spec.ts
@@ -57,7 +57,7 @@ describe('ModelsSection theme styles', () => {
     // under the dark theme, so filling the row with either erases the nested
     // editor's boundary. The row is outlined; the fill is the editor's alone.
     expect(block('.editor')).toContain('background: var(--dsw-alias-bg-module-platform)')
-    expect(block('.rowCard')).toContain('border: 1px solid var(--dsw-alias-border-l2)')
+    expect(block('.rowCard')).toContain('border: 0.5px solid var(--dsw-alias-border-l4)')
     expect(block('.rowCard')).not.toMatch(/\bbackground\s*:/)
   })
 
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index 23b6f81209..b1ef34ea90 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/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/client/ui-theme/README.md
-README.md: 756175ba1208cdca4c92c73885bad3c7d11e0065
-README.zh.md: 29a901020dd96c5b75e5bd1b486e4167e7d49b08
+README.md: c591501e274de0419ea3585feb731802985ac95b
+README.zh.md: e970141963cc592541e77d748c421e693cc9568f
diff --git a/packages/client/ui-theme/README.md b/packages/client/ui-theme/README.md
index 756175ba12..c591501e27 100644
--- a/packages/client/ui-theme/README.md
+++ b/packages/client/ui-theme/README.md
@@ -55,7 +55,7 @@ The service owns theme and font-size state and publishes snapshots. The ui-layou
 
 `corner-shape.css` smooths every rounded corner: inside `@supports (corner-shape: superellipse(1.5))` it defines `--dsw-corner-shape` and applies it to all elements and their `::before`/`::after` through the universal selector, so engines without `corner-shape` keep circular corners. Full-round shapes — `border-radius: 50%` circles and pill radii — pair `corner-shape: round` with their radius in the owning component sheet because a superellipse deforms them; the corner-shape stylesheet spec enforces that pairing across every package stylesheet ([corner-smoothing note](../../../.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md)).
 
-`gradient-shadow-text.css` derives `--dsh-content-font-delta` from `--dsh-content-font-size` and shifts the Markdown heading and base-text ladder by that increment. It also derives the secondary tier `--dsh-content-font-size-secondary` (setting −1 at ≤14, setting −2 above; 13px at the default) with its own `--dsh-content-font-delta-secondary` for the table variants and the flow rows one step under the body. Dense small and code variants stay fixed. Outside the ladder, the user bubble and composer draft read the body pair directly, and flow-row titles and summaries read the secondary pair. The sheet also owns the shadow scale (`--dsw-shadow-lv*`) and the elevation tokens: `--dsw-elevation-stroke` draws a 0.5px hairline through the rebindable `--dsw-elevation-stroke-color`, and `--dsw-elevation-panel`/`--dsw-elevation-prominent` layer two faint soft shadows over that stroke, so elevated surfaces set `border: 0` and carry no layout-consuming outline ([elevation note](../../../.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md)).
+`gradient-shadow-text.css` derives `--dsh-content-font-delta` from `--dsh-content-font-size` and shifts the Markdown heading and base-text ladder by that increment. It also derives the secondary tier `--dsh-content-font-size-secondary` (setting −1 at ≤14, setting −2 above; 13px at the default) with its own `--dsh-content-font-delta-secondary` for the table variants and the flow rows one step under the body. Dense small and code variants stay fixed. Outside the ladder, the user bubble and composer draft read the body pair directly, and flow-row titles and summaries read the secondary pair. The sheet also owns the shadow scale (`--dsw-shadow-lv*`) and the elevation tokens: `--dsw-elevation-stroke` draws a 0.5px hairline through the rebindable `--dsw-elevation-stroke-color`, and `--dsw-elevation-panel`/`--dsw-elevation-prominent`/`--dsw-elevation-soft` (the composer's larger-blur, lower-alpha tier) layer two faint soft shadows over that stroke, so elevated surfaces set `border: 0` and carry no layout-consuming outline; the derived tokens are re-declared per element so a surface's stroke-color rebind takes effect ([elevation note](../../../.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md)).
 
 ### Scrollbar rebinding
 
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index 29a901020d..e970141963 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -55,7 +55,7 @@ kind: "package-reference"
 
 `corner-shape.css` 平滑所有圆角：在 `@supports (corner-shape: superellipse(1.5))` 内定义 `--dsw-corner-shape`，并通过通配选择器应用到所有元素及其 `::before`/`::after`，因此不支持 `corner-shape` 的引擎保持普通圆弧。正圆形状——`border-radius: 50%` 的圆与胶囊半径——因超级椭圆会使其变形，须在所属组件样式表中把 `corner-shape: round` 与半径声明配对；corner-shape 样式表 spec 跨全部包样式表强制这一配对（[圆角平滑笔记](../../../.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md)）。
 
-`gradient-shadow-text.css` 从 `--dsh-content-font-size` 派生 `--dsh-content-font-delta`，并以该增量移动 Markdown 标题与基础文本阶梯。它同时派生低一档变量 `--dsh-content-font-size-secondary`（设置 ≤14 时为设置值 −1，>14 时为设置值 −2；默认设置下为 13px）及配套的 `--dsh-content-font-delta-secondary`，供表格变体与比正文低一档的流内行使用。紧凑的小号文本与代码变体保持固定字号。阶梯之外，用户气泡与 composer 草稿直接读取正文档变量对，流内行的标题及摘要读取低一档变量对。该表还持有阴影阶（`--dsw-shadow-lv*`）与 elevation token：`--dsw-elevation-stroke` 经可重绑的 `--dsw-elevation-stroke-color` 画 0.5px 发丝描边，`--dsw-elevation-panel`/`--dsw-elevation-prominent` 在描边之上叠两层极淡柔光，因此高层级表面设 `border: 0`，不再有占布局的轮廓（[elevation 笔记](../../../.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md)）。
+`gradient-shadow-text.css` 从 `--dsh-content-font-size` 派生 `--dsh-content-font-delta`，并以该增量移动 Markdown 标题与基础文本阶梯。它同时派生低一档变量 `--dsh-content-font-size-secondary`（设置 ≤14 时为设置值 −1，>14 时为设置值 −2；默认设置下为 13px）及配套的 `--dsh-content-font-delta-secondary`，供表格变体与比正文低一档的流内行使用。紧凑的小号文本与代码变体保持固定字号。阶梯之外，用户气泡与 composer 草稿直接读取正文档变量对，流内行的标题及摘要读取低一档变量对。该表还持有阴影阶（`--dsw-shadow-lv*`）与 elevation token：`--dsw-elevation-stroke` 经可重绑的 `--dsw-elevation-stroke-color` 画 0.5px 发丝描边，`--dsw-elevation-panel`/`--dsw-elevation-prominent`/`--dsw-elevation-soft`（输入框专用的更大模糊、更低透明度档）在描边之上叠两层极淡柔光，因此高层级表面设 `border: 0`，不再有占布局的轮廓；派生 token 逐元素重声明，使表面对描边色的重绑真实生效（[elevation 笔记](../../../.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md)）。
 
 ### 滚动条重新绑定
 
diff --git a/packages/client/ui-theme/src/styles/gradient-shadow-text.css b/packages/client/ui-theme/src/styles/gradient-shadow-text.css
index b9e6eb25cd..5965bd5ce6 100644
--- a/packages/client/ui-theme/src/styles/gradient-shadow-text.css
+++ b/packages/client/ui-theme/src/styles/gradient-shadow-text.css
@@ -12,8 +12,19 @@ body {
      柔光几乎不可见，由描边承担分离。描边颜色经 --dsw-elevation-stroke-color
      间接，组件可重绑（菜单面与输入框重绑最浅的 l1，输入框的
      workspace-trigger 态置 transparent 只保留柔光）。soft 供输入框：更大
-     模糊、更低透明度的柔光。 */
+     模糊、更低透明度的柔光。默认色只声明在 body 上，让表面的重绑沿继承
+     传给真正消费投影的后代。 */
   --dsw-elevation-stroke-color: var(--dsw-alias-border-l4);
+  /* blur filter */
+  --dsw-mask-blur: blur(2px);
+}
+
+/* 派生 elevation 值逐元素声明而非从 body 继承：继承传下来的是在 body 上就
+   已替换完 var() 的值，组件重绑 --dsw-elevation-stroke-color 将无法进入
+   var(--dsw-elevation-*)；逐元素声明让每个元素按自己看到的描边色重新替换
+   （同 scrollbar.css 对 --dsh-scrollbar-thumb 的处理）。 */
+body,
+body * {
   --dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color);
   --dsw-elevation-panel:
     var(--dsw-elevation-stroke), 0 3px 8px 0 rgba(0, 0, 0, 0.03), 0 0 16px 0 rgba(0, 0, 0, 0.02);
@@ -21,8 +32,6 @@ body {
     var(--dsw-elevation-stroke), 0 3px 8px 0 rgba(0, 0, 0, 0.04), 0 0 20px 0 rgba(0, 0, 0, 0.05);
   --dsw-elevation-soft:
     var(--dsw-elevation-stroke), 0 4px 16px 0 rgba(0, 0, 0, 0.03), 0 0 24px 0 rgba(0, 0, 0, 0.03);
-  /* blur filter */
-  --dsw-mask-blur: blur(2px);
 }
 
 body[data-ds-dark-theme] {
diff --git a/packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts b/packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts
index b4569aeff8..fd9a5bd1e3 100644
--- a/packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts
+++ b/packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts
@@ -59,22 +59,33 @@ describe('corner-shape.css smoothing', () => {
   })
 })
 
+/**
+ * Full-round rules missing the `corner-shape: round` pairing.
+ * @param css - stylesheet text.
+ * @returns the offending selectors, in source order.
+ */
+function unpairedFullRound(css: string): string[] {
+  return parseRules(css)
+    .filter(rule => rule.declarations
+      .some(([property, value]) => property === 'border-radius' && isFullRound(value)))
+    .filter(rule => !rule.declarations
+      .some(([property, value]) => property === 'corner-shape' && value === 'round'))
+    .map(rule => rule.selectors.join(', '))
+}
+
 describe('full-round radii keep circular corners', () => {
+  it('rejects a full-round radius without the pairing', () => {
+    expect(unpairedFullRound('.a { border-radius: 50%; }')).toEqual(['.a'])
+    expect(unpairedFullRound('.a { border-radius: 999px; }')).toEqual(['.a'])
+    expect(unpairedFullRound('.a { border-radius: 50%; corner-shape: round; }')).toEqual([])
+  })
+
   it('pairs corner-shape: round with every full-round border-radius under packages/', () => {
     // The universal superellipse reaches every element, so each circle and
     // pill states its own arc back; a new one without the pairing regresses
     // silently on supporting engines only, which no jsdom test renders.
-    const unpaired: string[] = []
-    for (const file of packageStylesheets()) {
-      for (const rule of parseRules(readFileSync(file, 'utf8'))) {
-        const fullRound = rule.declarations
-          .some(([property, value]) => property === 'border-radius' && isFullRound(value))
-        if (!fullRound) continue
-        const paired = rule.declarations
-          .some(([property, value]) => property === 'corner-shape' && value === 'round')
-        if (!paired) unpaired.push(`${file} ${rule.selectors.join(', ')}`)
-      }
-    }
+    const unpaired = packageStylesheets().flatMap(file =>
+      unpairedFullRound(readFileSync(file, 'utf8')).map(selectors => `${file} ${selectors}`))
     expect(unpaired).toEqual([])
   })
 })
diff --git a/packages/client/ui-theme/tests/elevation-styles.client.spec.ts b/packages/client/ui-theme/tests/elevation-styles.client.spec.ts
index d70b265a00..bf246f2d10 100644
--- a/packages/client/ui-theme/tests/elevation-styles.client.spec.ts
+++ b/packages/client/ui-theme/tests/elevation-styles.client.spec.ts
@@ -8,6 +8,7 @@
  * example the warn approval panels) stay real borders and are out of scope.
  */
 import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { packageStylesheets, parseRules } from './stylesheet-scan.ts'
@@ -23,44 +24,120 @@ const sheetCss = readFileSync(
   fileURLToPath(new URL('../src/styles/gradient-shadow-text.css', import.meta.url)), 'utf8')
 
 describe('elevation tokens', () => {
-  const declarations = new Map(parseRules(sheetCss)
-    .filter(rule => rule.selectors.includes('body'))
+  const rules = parseRules(sheetCss)
+  const bodyOnly = new Map(rules
+    .filter(rule => rule.selectors.length === 1 && rule.selectors[0] === 'body')
+    .flatMap(rule => rule.declarations))
+  const perElement = new Map(rules
+    .filter(rule => rule.selectors.includes('body *'))
     .flatMap(rule => rule.declarations))
 
-  it('draws the hairline stroke at 0.5px through the rebindable color indirection', () => {
-    expect(declarations.get(STROKE_COLOR)).toBe('var(--dsw-alias-border-l4)')
-    expect(declarations.get('--dsw-elevation-stroke')).toBe(`0 0 0 0.5px var(${STROKE_COLOR})`)
+  it('defaults the stroke color on body alone, so a surface rebind inherits', () => {
+    // Declared per element, `body *` would beat inheritance on every
+    // descendant and a surface's rebind could not reach the box that carries
+    // the shadow; declared on body alone, the rebind inherits down.
+    expect(bodyOnly.get(STROKE_COLOR)).toBe('var(--dsw-alias-border-l4)')
+    expect(perElement.has(STROKE_COLOR)).toBe(false)
   })
 
-  it('layers panel and prominent on top of the stroke', () => {
+  it('declares the derived values per element, so a stroke rebind takes effect', () => {
+    // A custom property computes with var() already substituted, and
+    // descendants inherit that computed value: derived tokens declared only on
+    // body would bake in body's stroke color, making every
+    // --dsw-elevation-stroke-color rebind a no-op. Per-element declarations
+    // re-substitute against the color each element sees (the same contract
+    // scrollbar.css states for --dsh-scrollbar-thumb).
+    expect(perElement.get('--dsw-elevation-stroke')).toBe(`0 0 0 0.5px var(${STROKE_COLOR})`)
     for (const name of ['--dsw-elevation-panel', '--dsw-elevation-prominent', '--dsw-elevation-soft']) {
-      expect(declarations.get(name), name).toMatch(/^var\(--dsw-elevation-stroke\), 0 /)
+      expect(perElement.get(name), name).toMatch(/^var\(--dsw-elevation-stroke\), 0 /)
+      expect(bodyOnly.has(name), name).toBe(false)
     }
   })
 })
 
+/**
+ * Rules pairing an lv/elevation box-shadow with a neutral-border-token border.
+ * @param css - stylesheet text.
+ * @returns the offending selectors, in source order.
+ */
+function neutralBordersBesideElevation(css: string): string[] {
+  return parseRules(css)
+    .filter(rule => rule.declarations
+      .some(([property, value]) => property === 'box-shadow' && ELEVATED_SHADOW.test(value)))
+    .filter(rule => rule.declarations.some(([property, value]) =>
+      property.startsWith('border') && !property.startsWith('border-radius') && NEUTRAL_BORDER.test(value)))
+    .map(rule => rule.selectors.join(', '))
+}
+
 describe('elevated surfaces carry no neutral border', () => {
+  it('rejects a rule that pairs the shadow with a neutral border', () => {
+    expect(neutralBordersBesideElevation(
+      '.a { box-shadow: var(--dsw-elevation-panel); border: 0.5px solid var(--dsw-alias-border-l2); }',
+    )).toEqual(['.a'])
+    expect(neutralBordersBesideElevation(
+      '.a { box-shadow: var(--dsw-elevation-panel); border: 0; }',
+    )).toEqual([])
+  })
+
   it('never pairs an lv/elevation shadow with a neutral border token under packages/', () => {
     // A 1px border beside the elevation stroke double-draws the outline and
     // shifts layout by the border width; the hairline belongs to the shadow.
-    const paired: string[] = []
-    for (const file of packageStylesheets()) {
-      for (const rule of parseRules(readFileSync(file, 'utf8'))) {
-        const elevated = rule.declarations
-          .some(([property, value]) => property === 'box-shadow' && ELEVATED_SHADOW.test(value))
-        if (!elevated) continue
-        const neutralBorder = rule.declarations.some(([property, value]) =>
-          property.startsWith('border') && !property.startsWith('border-radius') && NEUTRAL_BORDER.test(value))
-        if (neutralBorder) paired.push(`${file} ${rule.selectors.join(', ')}`)
-      }
-    }
+    const paired = packageStylesheets().flatMap(file =>
+      neutralBordersBesideElevation(readFileSync(file, 'utf8'))
+        .map(selectors => `${file} ${selectors}`))
     expect(paired).toEqual([])
   })
 })
 
+/** Border properties that carry a width in their shorthand. */
+const BORDER_EDGE = /^border(?:-top|-bottom|-left|-right)?$/
+
+/**
+ * Solid neutral-token borders wider than the 0.5px hairline. The width test is
+ * lexical and order-sensitive: `border: solid 0.5px …` would be reported (a
+ * loud false positive to normalize), while split `border-width`/`border-color`
+ * declarations fall outside BORDER_EDGE and are not seen; no sheet under test
+ * writes either form.
+ * @param css - stylesheet text.
+ * @param exempt - `<selector> <property>` pairs allowed to keep their width.
+ * @returns the offending `<selectors> <property>: <value>` lines, in source order.
+ */
+function wideNeutralBorders(css: string, exempt: Set<string> = new Set()): string[] {
+  const wide: string[] = []
+  for (const rule of parseRules(css)) {
+    for (const [property, value] of rule.declarations) {
+      if (!BORDER_EDGE.test(property)) continue
+      if (!value.includes('solid') || !NEUTRAL_BORDER.test(value)) continue
+      if (value.startsWith('0.5px ')) continue
+      if (rule.selectors.some(selector => exempt.has(selector))) continue
+      wide.push(`${rule.selectors.join(', ')} ${property}: ${value}`)
+    }
+  }
+  return wide
+}
+
+/**
+ * Filled divider lines (a border-token background on a 1px-tall or 1px-wide
+ * box) that keep the pre-hairline weight.
+ * @param css - stylesheet text.
+ * @returns the offending `<selectors> <property>: <value>` lines, in source order.
+ */
+function wideFilledDividers(css: string): string[] {
+  const wide: string[] = []
+  for (const rule of parseRules(css)) {
+    const paintsLine = rule.declarations.some(([property, value]) =>
+      (property === 'background' || property === 'background-color') && NEUTRAL_BORDER.test(value))
+    if (!paintsLine) continue
+    for (const [property, value] of rule.declarations) {
+      if ((property === 'height' || property === 'width') && value === '1px') {
+        wide.push(`${rule.selectors.join(', ')} ${property}: ${value}`)
+      }
+    }
+  }
+  return wide
+}
+
 describe('neutral solid borders are hairlines', () => {
-  /** Border properties that carry a width in their shorthand. */
-  const BORDER_EDGE = /^border(?:-top|-bottom|-left|-right)?$/
   /**
    * Spinner ring tracks, keyed `<basename> <selector>`: the border is the
    * drawn graphic (a rotating ring), not an outline, so it keeps its width.
@@ -70,22 +147,26 @@ describe('neutral solid borders are hairlines', () => {
     'TrajectoryTable.module.css .historyLoadingSpinner',
   ])
 
+  it('rejects a wide neutral border and a wide filled divider', () => {
+    expect(wideNeutralBorders('.a { border: 1px solid var(--dsw-alias-border-l2); }'))
+      .toEqual(['.a border: 1px solid var(--dsw-alias-border-l2)'])
+    expect(wideNeutralBorders('.a { border: 0.5px solid var(--dsw-alias-border-l2); }')).toEqual([])
+    expect(wideFilledDividers('.a { background: var(--dsw-alias-border-l2); height: 1px; }'))
+      .toEqual(['.a height: 1px'])
+    expect(wideFilledDividers('.a { background: var(--dsw-alias-border-l2); height: 0.5px; }')).toEqual([])
+  })
+
   it('draws every solid neutral-token border at 0.5px under packages/', () => {
     // Buttons, inputs, cards, and separators share the hairline weight;
     // dashed affordances and state-colored borders are out of scope.
-    const wide: string[] = []
-    for (const file of packageStylesheets()) {
-      const base = file.slice(file.lastIndexOf('/') + 1)
-      for (const rule of parseRules(readFileSync(file, 'utf8'))) {
-        for (const [property, value] of rule.declarations) {
-          if (!BORDER_EDGE.test(property)) continue
-          if (!value.includes('solid') || !NEUTRAL_BORDER.test(value)) continue
-          if (value.startsWith('0.5px ')) continue
-          if (rule.selectors.some(selector => RING_TRACKS.has(`${base} ${selector}`))) continue
-          wide.push(`${file} ${rule.selectors.join(', ')} ${property}: ${value}`)
-        }
-      }
-    }
+    const wide = packageStylesheets().flatMap((file) => {
+      const base = basename(file)
+      const exempt = new Set([...RING_TRACKS]
+        .filter(track => track.startsWith(`${base} `))
+        .map(track => track.slice(base.length + 1)))
+      return wideNeutralBorders(readFileSync(file, 'utf8'), exempt)
+        .map(line => `${file} ${line}`)
+    })
     expect(wide).toEqual([])
   })
 
@@ -94,19 +175,8 @@ describe('neutral solid borders are hairlines', () => {
     // background (menu separators, the conversation header seam, markdown hr,
     // vertical rails) — is the same hairline as a border. Visually-hidden 1px
     // clip boxes carry no border-token background and stay exempt.
-    const wide: string[] = []
-    for (const file of packageStylesheets()) {
-      for (const rule of parseRules(readFileSync(file, 'utf8'))) {
-        const paintsLine = rule.declarations.some(([property, value]) =>
-          (property === 'background' || property === 'background-color') && NEUTRAL_BORDER.test(value))
-        if (!paintsLine) continue
-        for (const [property, value] of rule.declarations) {
-          if ((property === 'height' || property === 'width') && value === '1px') {
-            wide.push(`${file} ${rule.selectors.join(', ')} ${property}: ${value}`)
-          }
-        }
-      }
-    }
+    const wide = packageStylesheets().flatMap(file =>
+      wideFilledDividers(readFileSync(file, 'utf8')).map(line => `${file} ${line}`))
     expect(wide).toEqual([])
   })
 })

From 3ce5604a71b4f573e9a7bc4a31cab06cc4407493 Mon Sep 17 00:00:00 2001
From: "yx.zhang" <yx.zhang@yxzhangdeMacBook-Pro.local>
Date: Tue, 1 Sep 2026 19:25:59 +0800
Subject: [PATCH 03/37] feat(web): deepen composer stroke to l2, widen menu
 radii to 20px

The composer hairline moves one step up from the menus' l1; the seven
menu-fill dropdown cards grow from 16px to 20px corners. Notes and the
token comment record the new layering.
---
 .../2026-09-01-web-elevation-stroke-shadows.i18n.yaml     | 4 ++--
 .../feature/2026-09-01-web-elevation-stroke-shadows.md    | 4 ++--
 .../feature/2026-09-01-web-elevation-stroke-shadows.zh.md | 4 ++--
 .../ui-commands/src/client/PopupSelectView.module.css     | 2 +-
 .../src/client/skeleton/InputBar.module.css               | 8 ++++----
 .../ui-input-trigger/src/client/MenuView.module.css       | 2 +-
 .../client/ui-jobs/src/client/JobListAction.module.css    | 2 +-
 .../ui-model-selection/src/client/ModelSelect.module.css  | 2 +-
 packages/client/ui-primitives/src/Menu.module.css         | 2 +-
 .../src/client/ScheduleCatalogAction.module.css           | 2 +-
 .../src/client/SubagentHeaderLineage.module.css           | 2 +-
 .../client/ui-theme/src/styles/gradient-shadow-text.css   | 2 +-
 12 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
index fa75bdb9ba..e38afaa661 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.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 .agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
-2026-09-01-web-elevation-stroke-shadows.md: 774c9d996958cbc46cb21daaed928f9386c33421
-2026-09-01-web-elevation-stroke-shadows.zh.md: cb6dd3563952d97725d5e451c56e7fa7a710abaf
+2026-09-01-web-elevation-stroke-shadows.md: d3622271f6656c8f7aef1d0f8681fe3cb2861854
+2026-09-01-web-elevation-stroke-shadows.zh.md: 63f2213a0f8e50fb95d5f1b45507fba8c02d9619
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
index 774c9d9969..d3622271f6 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
@@ -12,11 +12,11 @@ Elevated web-client surfaces — menus, popovers, modals, panels, floating butto
 
 `gradient-shadow-text.css` (the ui-theme shadow owner) defines the elevation tokens beside the `--dsw-shadow-lv*` scale:
 
-- `--dsw-elevation-stroke-color` — the hairline color, defaulting to `--dsw-alias-border-l4` (black 16% light, white 20% dark); components rebind it per surface or state, and every menu-fill surface (`--dsw-specific-menu` background) and the composer rebind the lightest `--dsw-alias-border-l1`, both quieter than panels and buttons. The default is declared on `body` alone while the derived tokens below are re-declared on `body, body *`: a custom property computes with `var()` already substituted, so body-only derived tokens would bake in body's color and make every rebind a no-op (the same per-element re-substitution scrollbar.css states for `--dsh-scrollbar-thumb`).
+- `--dsw-elevation-stroke-color` — the hairline color, defaulting to `--dsw-alias-border-l4` (black 16% light, white 20% dark); components rebind it per surface or state: every menu-fill surface (`--dsw-specific-menu` background) rebinds the lightest `--dsw-alias-border-l1` and the composer rebinds `--dsw-alias-border-l2`, both quieter than panels and buttons. The default is declared on `body` alone while the derived tokens below are re-declared on `body, body *`: a custom property computes with `var()` already substituted, so body-only derived tokens would bake in body's color and make every rebind a no-op (the same per-element re-substitution scrollbar.css states for `--dsh-scrollbar-thumb`).
 - `--dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color)` — the stroke alone, used standalone by inline cards that want only an outline (the plugin-inventory card).
 - `--dsw-elevation-panel` / `--dsw-elevation-prominent` — the stroke plus two faint soft layers (3px directional + 16/20px glow at 2–5% black), panel for small floating widgets and cards, prominent for floats, and soft — larger blur at lower alpha — for the composer.
 
-Converted surfaces set `border: 0` and one elevation shadow: every `--dsw-shadow-lv3` float (Menu, Modal, popup selects, model select, usage/context popovers, feedback actions, schedule/job popovers, subagent lineage, settings panel, cordis panel, experimental team panel) takes prominent, and the lv2 surfaces (scroll-to-bottom button, turn-preview card, attachment-rail arrows, question composer, trajectory tooltip) take panel. The composer card takes the soft tier with the l1 stroke rebind, and its workspace-trigger state sets the stroke color `transparent` instead of the former `border-color: transparent`. Dark theme needs no shadow overrides: the soft layers are near-invisible there and the stroke carries the separation, as in Codex.
+Converted surfaces set `border: 0` and one elevation shadow: every `--dsw-shadow-lv3` float (Menu, Modal, popup selects, model select, usage/context popovers, feedback actions, schedule/job popovers, subagent lineage, settings panel, cordis panel, experimental team panel) takes prominent, and the lv2 surfaces (scroll-to-bottom button, turn-preview card, attachment-rail arrows, question composer, trajectory tooltip) take panel. The composer card takes the soft tier with the l2 stroke rebind, and its workspace-trigger state sets the stroke color `transparent` instead of the former `border-color: transparent`. Dark theme needs no shadow overrides: the soft layers are near-invisible there and the stroke carries the separation, as in Codex.
 
 `packages/client/ui-theme/tests/elevation-styles.client.spec.ts` pins the token composition and scans every stylesheet under `packages/`: a rule pairing an lv/elevation `box-shadow` with a `--dsw-alias-border-*` border fails, and every `solid` border on a neutral `--dsw-alias-border-*` token must be `0.5px` wide. Deliberate keeps: Toast and HoverCard (inverted fills where a theme-following stroke is meaningless), ImageLightbox (bare image), and the warn-bordered approval/plan panels, whose state-colored borders stay real borders and pass the scan.
 
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
index cb6dd35639..63f2213a0f 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
@@ -12,11 +12,11 @@ Web 客户端的高层级表面——菜单、浮层、对话框、面板、悬
 
 `gradient-shadow-text.css`（ui-theme 的阴影归属地）在 `--dsw-shadow-lv*` 阶旁定义 elevation token：
 
-- `--dsw-elevation-stroke-color`——发丝描边颜色，默认 `--dsw-alias-border-l4`（浅色黑 16%、深色白 20%）；组件可按表面或状态重绑：所有菜单面（`--dsw-specific-menu` 背景）与输入框重绑最浅的 `--dsw-alias-border-l1`，两者都比面板与按钮安静。默认色只声明在 `body` 上，而下述派生 token 在 `body, body *` 上逐元素重声明：自定义属性的计算值已替换完 `var()`，派生 token 若只在 body 声明会把 body 的颜色固化进去，让所有重绑失效（与 scrollbar.css 对 `--dsh-scrollbar-thumb` 声明的逐元素重替换是同一契约）。
+- `--dsw-elevation-stroke-color`——发丝描边颜色，默认 `--dsw-alias-border-l4`（浅色黑 16%、深色白 20%）；组件可按表面或状态重绑：所有菜单面（`--dsw-specific-menu` 背景）重绑最浅的 `--dsw-alias-border-l1`、输入框重绑 `--dsw-alias-border-l2`，两者都比面板与按钮安静。默认色只声明在 `body` 上，而下述派生 token 在 `body, body *` 上逐元素重声明：自定义属性的计算值已替换完 `var()`，派生 token 若只在 body 声明会把 body 的颜色固化进去，让所有重绑失效（与 scrollbar.css 对 `--dsh-scrollbar-thumb` 声明的逐元素重替换是同一契约）。
 - `--dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color)`——单独的描边，供只要轮廓的行内卡片独立使用（插件清单卡片）。
 - `--dsw-elevation-panel` / `--dsw-elevation-prominent`——描边加两层极淡柔光（3px 方向光 + 16/20px 辉光，黑 2–5%），panel 用于小型悬浮部件与卡片，prominent 用于浮层，soft——更大模糊、更低透明度——用于输入框。
 
-被转换的表面设 `border: 0` 加一个 elevation 投影：所有 `--dsw-shadow-lv3` 浮层（Menu、Modal、弹出选择、模型选择、用量/上下文浮层、反馈操作条、日程/任务浮层、子代理谱系、设置面板、cordis 面板、实验性 team 面板）取 prominent；lv2 表面（回到底部按钮、回合预览卡、附件栏箭头、问题 composer、轨迹 tooltip）取 panel。输入框卡片取 soft 档并重绑 l1 描边，其 workspace-trigger 态把描边色设为 `transparent`，替代原先的 `border-color: transparent`。深色主题无需投影覆盖：柔光在深色下几乎不可见，分离由描边承担，与 Codex 相同。
+被转换的表面设 `border: 0` 加一个 elevation 投影：所有 `--dsw-shadow-lv3` 浮层（Menu、Modal、弹出选择、模型选择、用量/上下文浮层、反馈操作条、日程/任务浮层、子代理谱系、设置面板、cordis 面板、实验性 team 面板）取 prominent；lv2 表面（回到底部按钮、回合预览卡、附件栏箭头、问题 composer、轨迹 tooltip）取 panel。输入框卡片取 soft 档并重绑 l2 描边，其 workspace-trigger 态把描边色设为 `transparent`，替代原先的 `border-color: transparent`。深色主题无需投影覆盖：柔光在深色下几乎不可见，分离由描边承担，与 Codex 相同。
 
 `packages/client/ui-theme/tests/elevation-styles.client.spec.ts` 钉住 token 组成并扫描 `packages/` 下全部样式表：lv/elevation `box-shadow` 与 `--dsw-alias-border-*` border 配对的规则即失败；中性 `--dsw-alias-border-*` token 上的每个 `solid` border 必须为 `0.5px` 宽。有意保留：Toast 与 HoverCard（反色填充，跟随主题的描边色在其上无意义）、ImageLightbox（裸图片）、warn 描边的审批/计划面板——状态色 border 保持真 border，扫描放行。
 
diff --git a/packages/client/ui-commands/src/client/PopupSelectView.module.css b/packages/client/ui-commands/src/client/PopupSelectView.module.css
index 39ee045f16..9867b76a3f 100644
--- a/packages/client/ui-commands/src/client/PopupSelectView.module.css
+++ b/packages/client/ui-commands/src/client/PopupSelectView.module.css
@@ -25,7 +25,7 @@
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
   border: 0;
-  border-radius: 16px;
+  border-radius: 20px;
   background: var(--dsw-specific-menu);
   --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
   box-shadow: var(--dsw-elevation-prominent);
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index 916039e3d0..b7561bbfd8 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -40,11 +40,11 @@
   width: 100%;
   max-width: var(--dsh-composer-card-max-width);
   padding-top: 10px;
-  /* Input stroke: the lightest neutral (l1), drawn as the elevation hairline
-     so it costs no layout; the shadow is the soft elevation tier. Fill: the
-     input surface token (elevated in dark). */
+  /* Input stroke: the light neutral (l2, one step above the menus' l1),
+     drawn as the elevation hairline so it costs no layout; the shadow is the
+     soft elevation tier. Fill: the input surface token (elevated in dark). */
   border: 0;
-  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l2);
   border-radius: 22px;
   background: var(--dsw-specific-input-major);
   box-shadow: var(--dsw-elevation-soft);
diff --git a/packages/client/ui-input-trigger/src/client/MenuView.module.css b/packages/client/ui-input-trigger/src/client/MenuView.module.css
index 4f6b5c4d18..948bfac52f 100644
--- a/packages/client/ui-input-trigger/src/client/MenuView.module.css
+++ b/packages/client/ui-input-trigger/src/client/MenuView.module.css
@@ -18,7 +18,7 @@
   display: flex;
   flex-direction: column;
   border: 0;
-  border-radius: 16px;
+  border-radius: 20px;
   background: var(--dsw-specific-menu);
   --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
   box-shadow: var(--dsw-elevation-prominent);
diff --git a/packages/client/ui-jobs/src/client/JobListAction.module.css b/packages/client/ui-jobs/src/client/JobListAction.module.css
index 56bf028248..418ddf9b9a 100644
--- a/packages/client/ui-jobs/src/client/JobListAction.module.css
+++ b/packages/client/ui-jobs/src/client/JobListAction.module.css
@@ -55,7 +55,7 @@
   overflow: auto;
   list-style: none;
   border: 0;
-  border-radius: 16px;
+  border-radius: 20px;
   background: var(--dsw-specific-menu);
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
diff --git a/packages/client/ui-model-selection/src/client/ModelSelect.module.css b/packages/client/ui-model-selection/src/client/ModelSelect.module.css
index 2c19256a8e..85b67ba496 100644
--- a/packages/client/ui-model-selection/src/client/ModelSelect.module.css
+++ b/packages/client/ui-model-selection/src/client/ModelSelect.module.css
@@ -83,7 +83,7 @@
   /* Surface tokens match the Menu primitive card (ui-primitives
    * Menu.module.css) so every dropdown reads as the same material. */
   border: 0;
-  border-radius: 16px;
+  border-radius: 20px;
   background: var(--dsw-specific-menu);
   --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
   box-shadow: var(--dsw-elevation-prominent);
diff --git a/packages/client/ui-primitives/src/Menu.module.css b/packages/client/ui-primitives/src/Menu.module.css
index 7c5d11f4bc..72210cffbc 100644
--- a/packages/client/ui-primitives/src/Menu.module.css
+++ b/packages/client/ui-primitives/src/Menu.module.css
@@ -14,7 +14,7 @@
   flex-direction: column;
   gap: 0;
   border: 0;
-  border-radius: 16px;
+  border-radius: 20px;
   background: var(--dsw-specific-menu);
   --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
   box-shadow: var(--dsw-elevation-prominent);
diff --git a/packages/client/ui-schedule/src/client/ScheduleCatalogAction.module.css b/packages/client/ui-schedule/src/client/ScheduleCatalogAction.module.css
index 5319887ae0..c768861cea 100644
--- a/packages/client/ui-schedule/src/client/ScheduleCatalogAction.module.css
+++ b/packages/client/ui-schedule/src/client/ScheduleCatalogAction.module.css
@@ -53,7 +53,7 @@
   overflow: auto;
   list-style: none;
   border: 0;
-  border-radius: 16px;
+  border-radius: 20px;
   background: var(--dsw-specific-menu);
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
index 86e6dcf9b5..5b8582c295 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
@@ -103,7 +103,7 @@
   max-height: min(560px, calc(100vh - 140px));
   padding: 4px;
   overflow: auto;
-  border-radius: 16px;
+  border-radius: 20px;
   background: var(--dsw-specific-menu);
   --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
   --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
diff --git a/packages/client/ui-theme/src/styles/gradient-shadow-text.css b/packages/client/ui-theme/src/styles/gradient-shadow-text.css
index 5965bd5ce6..36fee49415 100644
--- a/packages/client/ui-theme/src/styles/gradient-shadow-text.css
+++ b/packages/client/ui-theme/src/styles/gradient-shadow-text.css
@@ -10,7 +10,7 @@ body {
   /* Elevation：浮层/面板/面型按钮的描边+投影三件套。0.5px 发丝描边画在
      box-shadow 里（组件配 border: 0，不占布局），叠两层极淡柔光；深色主题下
      柔光几乎不可见，由描边承担分离。描边颜色经 --dsw-elevation-stroke-color
-     间接，组件可重绑（菜单面与输入框重绑最浅的 l1，输入框的
+     间接，组件可重绑（菜单面重绑最浅的 l1、输入框重绑 l2，输入框的
      workspace-trigger 态置 transparent 只保留柔光）。soft 供输入框：更大
      模糊、更低透明度的柔光。默认色只声明在 body 上，让表面的重绑沿继承
      传给真正消费投影的后代。 */

From 8a97e817b5502587d95e27930a129b2787609e44 Mon Sep 17 00:00:00 2001
From: "yx.zhang" <yx.zhang@yxzhangdeMacBook-Pro.local>
Date: Tue, 1 Sep 2026 20:01:23 +0800
Subject: [PATCH 04/37] docs(agents): describe the corner and elevation prior
 art generically

The two styling notes name the surveyed product; the mechanism facts
(superellipse token, guard, full-round opt-out, stroke-in-shadow
elevation, 0.5px hairline) stand alone, so the notes now state them
without the product reference. Pairing records re-recorded.
---
 ...2026-09-01-web-elevation-stroke-shadows.i18n.yaml |  4 ++--
 .../2026-09-01-web-elevation-stroke-shadows.md       |  8 ++++----
 .../2026-09-01-web-elevation-stroke-shadows.zh.md    |  8 ++++----
 ...09-01-web-superellipse-corner-smoothing.i18n.yaml |  4 ++--
 .../2026-09-01-web-superellipse-corner-smoothing.md  | 12 ++++++------
 ...026-09-01-web-superellipse-corner-smoothing.zh.md | 12 ++++++------
 6 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
index e38afaa661..6339d26da2 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.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 .agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
-2026-09-01-web-elevation-stroke-shadows.md: d3622271f6656c8f7aef1d0f8681fe3cb2861854
-2026-09-01-web-elevation-stroke-shadows.zh.md: 63f2213a0f8e50fb95d5f1b45507fba8c02d9619
+2026-09-01-web-elevation-stroke-shadows.md: 2bc3105203b63c87aaf39e3d68780650b163dcca
+2026-09-01-web-elevation-stroke-shadows.zh.md: bda3ee27af03d20937253fa23968afd0cd7d39c7
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
index d3622271f6..2bc3105203 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.md
@@ -6,7 +6,7 @@ English | [中文](2026-09-01-web-elevation-stroke-shadows.zh.md)
 
 ## Problem
 
-Elevated web-client surfaces — menus, popovers, modals, panels, floating buttons, the composer — each paired a real `border: 1px solid <neutral token>` with a `--dsw-shadow-lv2`/`lv3` shadow. The border consumes layout (1px per side, and it is the UA-default replacement on `<button>` elements), the light theme drew most floats with no stroke at all (`--dsw-alias-border-inverted` is transparent in light) while `lv3` faked one with a blurred 1px ring, and the composer wore a broad soft `lv2` patch that read as a smudge rather than a lifted surface. The unpacked ChatGPT desktop (Codex) UI instead draws elevation as one `box-shadow` list: a 0.5px hairline stroke plus two faint soft layers (`--elevation-stroke`/`--elevation-sidebar`/`--elevation-prominent`), with `border: 0` on the surface.
+Elevated web-client surfaces — menus, popovers, modals, panels, floating buttons, the composer — each paired a real `border: 1px solid <neutral token>` with a `--dsw-shadow-lv2`/`lv3` shadow. The border consumes layout (1px per side, and it is the UA-default replacement on `<button>` elements), the light theme drew most floats with no stroke at all (`--dsw-alias-border-inverted` is transparent in light) while `lv3` faked one with a blurred 1px ring, and the composer wore a broad soft `lv2` patch that read as a smudge rather than a lifted surface. Current desktop chat UIs instead draw elevation as one `box-shadow` list: a 0.5px hairline stroke plus two faint soft layers, with `border: 0` on the surface.
 
 ## Decision
 
@@ -16,7 +16,7 @@ Elevated web-client surfaces — menus, popovers, modals, panels, floating butto
 - `--dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color)` — the stroke alone, used standalone by inline cards that want only an outline (the plugin-inventory card).
 - `--dsw-elevation-panel` / `--dsw-elevation-prominent` — the stroke plus two faint soft layers (3px directional + 16/20px glow at 2–5% black), panel for small floating widgets and cards, prominent for floats, and soft — larger blur at lower alpha — for the composer.
 
-Converted surfaces set `border: 0` and one elevation shadow: every `--dsw-shadow-lv3` float (Menu, Modal, popup selects, model select, usage/context popovers, feedback actions, schedule/job popovers, subagent lineage, settings panel, cordis panel, experimental team panel) takes prominent, and the lv2 surfaces (scroll-to-bottom button, turn-preview card, attachment-rail arrows, question composer, trajectory tooltip) take panel. The composer card takes the soft tier with the l2 stroke rebind, and its workspace-trigger state sets the stroke color `transparent` instead of the former `border-color: transparent`. Dark theme needs no shadow overrides: the soft layers are near-invisible there and the stroke carries the separation, as in Codex.
+Converted surfaces set `border: 0` and one elevation shadow: every `--dsw-shadow-lv3` float (Menu, Modal, popup selects, model select, usage/context popovers, feedback actions, schedule/job popovers, subagent lineage, settings panel, cordis panel, experimental team panel) takes prominent, and the lv2 surfaces (scroll-to-bottom button, turn-preview card, attachment-rail arrows, question composer, trajectory tooltip) take panel. The composer card takes the soft tier with the l2 stroke rebind, and its workspace-trigger state sets the stroke color `transparent` instead of the former `border-color: transparent`. Dark theme needs no shadow overrides: the soft layers are near-invisible there and the stroke carries the separation.
 
 `packages/client/ui-theme/tests/elevation-styles.client.spec.ts` pins the token composition and scans every stylesheet under `packages/`: a rule pairing an lv/elevation `box-shadow` with a `--dsw-alias-border-*` border fails, and every `solid` border on a neutral `--dsw-alias-border-*` token must be `0.5px` wide. Deliberate keeps: Toast and HoverCard (inverted fills where a theme-following stroke is meaningless), ImageLightbox (bare image), and the warn-bordered approval/plan panels, whose state-colored borders stay real borders and pass the scan.
 
@@ -24,9 +24,9 @@ Flat widgets keep real borders at hairline width: every neutral-token `1px solid
 
 ## Alternatives considered
 
-**Keeping 1px real borders and only softening the shadows.** Leaves the layout-consuming border, the light-theme stroke gap on `border-inverted` floats, and the double outline wherever both existed; the stroke-in-shadow form is what produces the crisp Codex edge.
+**Keeping 1px real borders and only softening the shadows.** Leaves the layout-consuming border, the light-theme stroke gap on `border-inverted` floats, and the double outline wherever both existed; the stroke-in-shadow form is what produces the crisp hairline edge.
 
-**A 1px stroke instead of 0.5px.** The Codex elevation stroke is 0.5px; at 2x displays it renders one physical pixel, and on 1x it blends lighter, which is the intended hairline. 1px reads as the old border.
+**A 1px stroke instead of 0.5px.** At 2x displays 0.5px renders one physical pixel, and on 1x it blends lighter, which is the intended hairline. 1px reads as the old border.
 
 **Drawing flat-widget hairlines as box-shadow strokes too.** Buttons and inputs swap `border-color` on hover and focus and several pair a box-shadow focus ring; moving their stroke into `box-shadow` would collide with those rings (one property) and rewrite every state rule, while `0.5px solid` keeps the whole state logic and changes only the weight.
 
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
index 63f2213a0f..bda3ee27af 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-01-web-elevation-stroke-shadows.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-Web 客户端的高层级表面——菜单、浮层、对话框、面板、悬浮按钮、输入框——原先都把真 `border: 1px solid <中性 token>` 与 `--dsw-shadow-lv2`/`lv3` 投影配对。border 占布局（每侧 1px，且在 `<button>` 上是对 UA 默认边框的替换）；浅色主题下多数浮层实际没有描边（`--dsw-alias-border-inverted` 在浅色下是透明的），靠 `lv3` 里模糊的 1px 环冒充；输入框则披着一大片柔和的 `lv2` 投影，读起来更像污渍而非悬浮表面。解包的 ChatGPT 桌面端（Codex）UI 改用单个 `box-shadow` 列表绘制 elevation：0.5px 发丝描边加两层极淡柔光（`--elevation-stroke`/`--elevation-sidebar`/`--elevation-prominent`），表面本身 `border: 0`。
+Web 客户端的高层级表面——菜单、浮层、对话框、面板、悬浮按钮、输入框——原先都把真 `border: 1px solid <中性 token>` 与 `--dsw-shadow-lv2`/`lv3` 投影配对。border 占布局（每侧 1px，且在 `<button>` 上是对 UA 默认边框的替换）；浅色主题下多数浮层实际没有描边（`--dsw-alias-border-inverted` 在浅色下是透明的），靠 `lv3` 里模糊的 1px 环冒充；输入框则披着一大片柔和的 `lv2` 投影，读起来更像污渍而非悬浮表面。当前桌面聊天 UI 改用单个 `box-shadow` 列表绘制 elevation：0.5px 发丝描边加两层极淡柔光，表面本身 `border: 0`。
 
 ## Decision
 
@@ -16,7 +16,7 @@ Web 客户端的高层级表面——菜单、浮层、对话框、面板、悬
 - `--dsw-elevation-stroke: 0 0 0 0.5px var(--dsw-elevation-stroke-color)`——单独的描边，供只要轮廓的行内卡片独立使用（插件清单卡片）。
 - `--dsw-elevation-panel` / `--dsw-elevation-prominent`——描边加两层极淡柔光（3px 方向光 + 16/20px 辉光，黑 2–5%），panel 用于小型悬浮部件与卡片，prominent 用于浮层，soft——更大模糊、更低透明度——用于输入框。
 
-被转换的表面设 `border: 0` 加一个 elevation 投影：所有 `--dsw-shadow-lv3` 浮层（Menu、Modal、弹出选择、模型选择、用量/上下文浮层、反馈操作条、日程/任务浮层、子代理谱系、设置面板、cordis 面板、实验性 team 面板）取 prominent；lv2 表面（回到底部按钮、回合预览卡、附件栏箭头、问题 composer、轨迹 tooltip）取 panel。输入框卡片取 soft 档并重绑 l2 描边，其 workspace-trigger 态把描边色设为 `transparent`，替代原先的 `border-color: transparent`。深色主题无需投影覆盖：柔光在深色下几乎不可见，分离由描边承担，与 Codex 相同。
+被转换的表面设 `border: 0` 加一个 elevation 投影：所有 `--dsw-shadow-lv3` 浮层（Menu、Modal、弹出选择、模型选择、用量/上下文浮层、反馈操作条、日程/任务浮层、子代理谱系、设置面板、cordis 面板、实验性 team 面板）取 prominent；lv2 表面（回到底部按钮、回合预览卡、附件栏箭头、问题 composer、轨迹 tooltip）取 panel。输入框卡片取 soft 档并重绑 l2 描边，其 workspace-trigger 态把描边色设为 `transparent`，替代原先的 `border-color: transparent`。深色主题无需投影覆盖：柔光在深色下几乎不可见，分离由描边承担。
 
 `packages/client/ui-theme/tests/elevation-styles.client.spec.ts` 钉住 token 组成并扫描 `packages/` 下全部样式表：lv/elevation `box-shadow` 与 `--dsw-alias-border-*` border 配对的规则即失败；中性 `--dsw-alias-border-*` token 上的每个 `solid` border 必须为 `0.5px` 宽。有意保留：Toast 与 HoverCard（反色填充，跟随主题的描边色在其上无意义）、ImageLightbox（裸图片）、warn 描边的审批/计划面板——状态色 border 保持真 border，扫描放行。
 
@@ -24,9 +24,9 @@ Web 客户端的高层级表面——菜单、浮层、对话框、面板、悬
 
 ## Alternatives considered
 
-**保留 1px 真 border、只调柔投影。** 留下占布局的 border、浅色主题 `border-inverted` 浮层的描边缺口，以及两者并存处的双轮廓；描边入投影正是产生 Codex 式锐利边缘的形式。
+**保留 1px 真 border、只调柔投影。** 留下占布局的 border、浅色主题 `border-inverted` 浮层的描边缺口，以及两者并存处的双轮廓；描边入投影正是产生锐利发丝边缘的形式。
 
-**用 1px 而非 0.5px 描边。** Codex 的 elevation 描边是 0.5px；2x 屏渲染为一物理像素，1x 屏混合得更浅，正是发丝线意图。1px 读起来就是原来的 border。
+**用 1px 而非 0.5px 描边。** 0.5px 在 2x 屏渲染为一物理像素，1x 屏混合得更浅，正是发丝线意图。1px 读起来就是原来的 border。
 
 **平面部件的发丝线也用 box-shadow 描边画。** 按钮与输入框在 hover/focus 时切换 `border-color`，多处还配 box-shadow 焦点环；把描边挪进 `box-shadow`（单一属性）会与焦点环冲突并重写全部状态规则，而 `0.5px solid` 保留整套状态逻辑，只改粗细。
 
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.i18n.yaml b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.i18n.yaml
index 5a179791e3..232c41abcd 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.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 .agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md
-2026-09-01-web-superellipse-corner-smoothing.md: 1da15664d4c4d92476d7f9414b27c0812665bd60
-2026-09-01-web-superellipse-corner-smoothing.zh.md: f2ff1690511fa530b66c53b4e62a53d1af0283ff
+2026-09-01-web-superellipse-corner-smoothing.md: 7088438a8068343434a27495b771515d4a5158ee
+2026-09-01-web-superellipse-corner-smoothing.zh.md: 26aa64fda9f557069cfc3040422c8e1b7e34676e
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md
index 1da15664d4..7088438a80 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md
+++ b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.md
@@ -6,25 +6,25 @@ English | [中文](2026-09-01-web-superellipse-corner-smoothing.zh.md)
 
 ## Problem
 
-Every rounded surface in the web client — cards, composer, buttons, popovers — draws its corners as plain circular arcs, which read as visibly harder than the smooth (squircle-like) corners current desktop chat UIs ship. An unpacked-`app.asar` survey of the ChatGPT desktop app's Codex UI found the smoothness comes from CSS `corner-shape: superellipse(1.5)` applied behind an `@supports` guard to every rounded-corner utility class except full-round (`rounded-full`), not from larger radii or masking tricks. This client has no utility classes: `border-radius` values are px literals spread across CSS Modules in every client package, so there is no single class list to attach the property to, and full-round shapes (`border-radius: 50%` circles, 999px pills) must keep circular arcs — a superellipse deforms a circle into a squircle, so a border-drawn spinner would visibly wobble, and it squares off capsule ends.
+Every rounded surface in the web client — cards, composer, buttons, popovers — draws its corners as plain circular arcs, which read as visibly harder than the smooth (squircle-like) corners current desktop chat UIs ship. That smoothness comes from CSS `corner-shape: superellipse(1.5)` applied behind an `@supports` guard, not from larger radii or masking tricks; utility-class implementations attach it to every rounded-corner class except full-round. This client has no utility classes: `border-radius` values are px literals spread across CSS Modules in every client package, so there is no single class list to attach the property to, and full-round shapes (`border-radius: 50%` circles, 999px pills) must keep circular arcs — a superellipse deforms a circle into a squircle, so a border-drawn spinner would visibly wobble, and it squares off capsule ends.
 
 ## Decision
 
-`packages/client/ui-theme/src/styles/corner-shape.css` is a global sheet mounted by ui-theme's client entry (after `base.css`). Inside `@supports (corner-shape: superellipse(1.5))` it defines `--dsw-corner-shape: superellipse(1.5)` on `:root` and applies `corner-shape: var(--dsw-corner-shape)` through `*, *::before, *::after` — `corner-shape` does not inherit, so the universal selector is the mechanism that reaches every rounded surface without a utility-class system. Engines without `corner-shape` keep circular corners because both declarations live inside the guard. `superellipse(1.5)` sits between `round` (`superellipse(1)`) and `squircle` (`superellipse(2)`), matching the Codex UI's value.
+`packages/client/ui-theme/src/styles/corner-shape.css` is a global sheet mounted by ui-theme's client entry (after `base.css`). Inside `@supports (corner-shape: superellipse(1.5))` it defines `--dsw-corner-shape: superellipse(1.5)` on `:root` and applies `corner-shape: var(--dsw-corner-shape)` through `*, *::before, *::after` — `corner-shape` does not inherit, so the universal selector is the mechanism that reaches every rounded surface without a utility-class system. Engines without `corner-shape` keep circular corners because both declarations live inside the guard. `superellipse(1.5)` sits between `round` (`superellipse(1)`) and `squircle` (`superellipse(2)`), matching the smoothing current desktop chat UIs ship.
 
 Full-round shapes opt back out at their declaration: every `border-radius` of `50%`, `100%`, or a pill radius (≥ 99px) pairs `corner-shape: round` in the same rule of its owning component sheet. The pairing is enforced by `packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts`, which scans every stylesheet under `packages/` (the shared scan helpers live in `tests/stylesheet-scan.ts`, extracted from the scrollbar spec); the same spec pins the guard and the universal application in `corner-shape.css`. Component-local radius indirections (`--dsl-*-radius`) all hold values far below the pill threshold, so the lexical scan covers current usage.
 
-The Codex UI also multiplies its radius tokens by 1.25 alongside the shape change; this client has no radius tokens (px literals per component), so radii are unchanged and only the corner curvature moves.
+Token-based implementations pair the shape change with a 1.25× radius scale; this client has no radius tokens (px literals per component), so radii are unchanged and only the corner curvature moves.
 
 ## Alternatives considered
 
-**A radius token system first, then per-token application (the literal Codex structure).** Faithful, but converting ~130 px-literal radii across every client package into tokens is a large refactor serving no other current need; the universal selector reaches the same surfaces with one rule.
+**A radius token system first, then per-token application.** Faithful, but converting ~130 px-literal radii across every client package into tokens is a large refactor serving no other current need; the universal selector reaches the same surfaces with one rule.
 
-**Applying superellipse to full-round shapes too (no opt-outs).** Fewer declarations, but spinners built from `border-radius: 50%` borders wobble when the rotating shape is not a circle, and capsule ends square off; the Codex UI equally excludes `rounded-full` from `corner-shape`.
+**Applying superellipse to full-round shapes too (no opt-outs).** Fewer declarations, but spinners built from `border-radius: 50%` borders wobble when the rotating shape is not a circle, and capsule ends square off.
 
 **Subtree opt-out via `--dsw-corner-shape: round` instead of per-declaration `corner-shape: round`.** The custom property inherits, so a pill's rounded descendants would silently lose smoothing; the explicit per-rule declaration keeps the opt-out exactly as wide as the full-round shape and is what the pairing spec can check.
 
-**Scaling radii by 1.25 like Codex.** Requires the token system above; the curvature change alone already delivers the smoothness, and radii stay as designed.
+**Scaling radii by 1.25 alongside the curvature change.** Requires the token system above; the curvature change alone already delivers the smoothness, and radii stay as designed.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md
index f2ff169051..26aa64fda9 100644
--- a/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-01-web-superellipse-corner-smoothing.zh.md
@@ -6,25 +6,25 @@ Status: implemented
 
 ## Problem
 
-Web 客户端里每个圆角表面——卡片、输入框、按钮、浮层——都以普通圆弧绘制圆角，观感明显硬于当前桌面聊天 UI 普遍采用的平滑（类 squircle）圆角。对 ChatGPT 桌面应用 Codex UI 解包 `app.asar` 的调研发现，其平滑感来自在 `@supports` 守卫内对除正圆（`rounded-full`）之外的所有圆角工具类应用 CSS `corner-shape: superellipse(1.5)`，而非更大的半径或遮罩技巧。本客户端没有工具类：`border-radius` 以 px 字面量散布在各客户端包的 CSS Modules 中，没有可以统一挂载该属性的类列表；而正圆形状（`border-radius: 50%` 的圆、999px 胶囊）必须保持圆弧——超级椭圆会把圆变形为 squircle，用 border 绘制的加载圈旋转时会明显晃动，胶囊两端也会变方。
+Web 客户端里每个圆角表面——卡片、输入框、按钮、浮层——都以普通圆弧绘制圆角，观感明显硬于当前桌面聊天 UI 普遍采用的平滑（类 squircle）圆角。这种平滑感来自在 `@supports` 守卫内应用 CSS `corner-shape: superellipse(1.5)`，而非更大的半径或遮罩技巧；工具类体系的实现把它挂到除正圆之外的所有圆角工具类上。本客户端没有工具类：`border-radius` 以 px 字面量散布在各客户端包的 CSS Modules 中，没有可以统一挂载该属性的类列表；而正圆形状（`border-radius: 50%` 的圆、999px 胶囊）必须保持圆弧——超级椭圆会把圆变形为 squircle，用 border 绘制的加载圈旋转时会明显晃动，胶囊两端也会变方。
 
 ## Decision
 
-`packages/client/ui-theme/src/styles/corner-shape.css` 是由 ui-theme 客户端 entry 挂载的全局样式表（位于 `base.css` 之后）。它在 `@supports (corner-shape: superellipse(1.5))` 内于 `:root` 定义 `--dsw-corner-shape: superellipse(1.5)`，并通过 `*, *::before, *::after` 应用 `corner-shape: var(--dsw-corner-shape)`——`corner-shape` 不继承，通配选择器正是在没有工具类系统的前提下触达每个圆角表面的机制。两条声明都在守卫内，因此不支持 `corner-shape` 的引擎保持普通圆弧。`superellipse(1.5)` 介于 `round`（`superellipse(1)`）与 `squircle`（`superellipse(2)`）之间，与 Codex UI 取值一致。
+`packages/client/ui-theme/src/styles/corner-shape.css` 是由 ui-theme 客户端 entry 挂载的全局样式表（位于 `base.css` 之后）。它在 `@supports (corner-shape: superellipse(1.5))` 内于 `:root` 定义 `--dsw-corner-shape: superellipse(1.5)`，并通过 `*, *::before, *::after` 应用 `corner-shape: var(--dsw-corner-shape)`——`corner-shape` 不继承，通配选择器正是在没有工具类系统的前提下触达每个圆角表面的机制。两条声明都在守卫内，因此不支持 `corner-shape` 的引擎保持普通圆弧。`superellipse(1.5)` 介于 `round`（`superellipse(1)`）与 `squircle`（`superellipse(2)`）之间，与当前桌面聊天 UI 的平滑度一致。
 
 正圆形状在其声明处退出：每个取值为 `50%`、`100%` 或胶囊半径（≥ 99px）的 `border-radius`，都在所属组件样式表的同一规则内配对 `corner-shape: round`。该配对由 `packages/client/ui-theme/tests/corner-shape-styles.client.spec.ts` 强制，它扫描 `packages/` 下的全部样式表（共享扫描辅助函数位于 `tests/stylesheet-scan.ts`，自 scrollbar spec 抽出）；同一 spec 也钉住 `corner-shape.css` 的守卫与通配应用。组件局部半径变量（`--dsl-*-radius`）取值都远低于胶囊阈值，因此词法扫描覆盖当前用法。
 
-Codex UI 在改变曲线的同时还把半径 token 乘以 1.25；本客户端没有半径 token（各组件 px 字面量），故半径不变，只改变圆角曲率。
+基于 token 的实现会在改变曲线的同时把半径 token 乘以 1.25；本客户端没有半径 token（各组件 px 字面量），故半径不变，只改变圆角曲率。
 
 ## Alternatives considered
 
-**先建半径 token 系统，再按 token 应用（照搬 Codex 结构）。** 更忠实，但把所有客户端包约 130 处 px 字面量半径改造成 token 是没有其他现实需求的大重构；通配选择器用一条规则触达同样的表面。
+**先建半径 token 系统，再按 token 应用。** 更忠实，但把所有客户端包约 130 处 px 字面量半径改造成 token 是没有其他现实需求的大重构；通配选择器用一条规则触达同样的表面。
 
-**对正圆形状也应用超级椭圆（不设豁免）。** 声明更少，但用 `border-radius: 50%` border 绘制的加载圈在形状不是圆时旋转会晃动，胶囊两端会变方；Codex UI 同样把 `rounded-full` 排除在 `corner-shape` 之外。
+**对正圆形状也应用超级椭圆（不设豁免）。** 声明更少，但用 `border-radius: 50%` border 绘制的加载圈在形状不是圆时旋转会晃动，胶囊两端会变方。
 
 **用子树级 `--dsw-corner-shape: round` 替代逐声明 `corner-shape: round` 豁免。** 自定义属性会继承，胶囊的圆角后代会静默失去平滑；逐规则显式声明让豁免范围恰好等于正圆形状本身，也是配对 spec 能检查的形式。
 
-**像 Codex 一样把半径乘 1.25。** 需要上述 token 系统；仅曲率变化已带来平滑感，半径维持设计值。
+**在改变曲率的同时把半径乘 1.25。** 需要上述 token 系统；仅曲率变化已带来平滑感，半径维持设计值。
 
 ## Consequences
 

From 515eca7dc772cb7d65ed3999620e8ae0cda72605 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Tue, 1 Sep 2026 20:21:11 +0800
Subject: [PATCH 05/37] fix(web): keep turn previews above code banners

---
 apps/web/tests/chat-scroll-contract.e2e.ts           | 12 ++++++++++++
 packages/client/ui-chat/README.i18n.yaml             |  4 ++--
 packages/client/ui-chat/README.md                    |  2 +-
 packages/client/ui-chat/README.zh.md                 |  2 +-
 .../ui-chat/src/client/chat/TurnNavigator.module.css |  4 +++-
 5 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/apps/web/tests/chat-scroll-contract.e2e.ts b/apps/web/tests/chat-scroll-contract.e2e.ts
index 37996ef301..49e14028ae 100644
--- a/apps/web/tests/chat-scroll-contract.e2e.ts
+++ b/apps/web/tests/chat-scroll-contract.e2e.ts
@@ -591,6 +591,18 @@ describe('web e2e: long Chat scroll contract', () => {
       await expect.poll(() => tooltip.count(), { timeout: 15_000 }).toBe(1)
       expect(await tooltip.textContent()).toContain(HISTORY_FIXTURE.markers.user(1))
       expect(await tooltip.textContent()).toContain(HISTORY_FIXTURE.markers.assistant(1))
+      const transcriptLayers = await tooltip.evaluate((preview) => {
+        const railSlot = preview.closest('nav')?.parentElement
+        const codeBanner = document.querySelector<HTMLElement>('.md-code-block > :first-child')
+        if (!(railSlot instanceof HTMLElement) || codeBanner === null) {
+          throw new Error('turn preview or code-block banner stacking context is unavailable')
+        }
+        return {
+          codeBanner: Number(getComputedStyle(codeBanner).zIndex),
+          rail: Number(getComputedStyle(railSlot).zIndex),
+        }
+      })
+      expect(transcriptLayers.rail).toBeGreaterThan(transcriptLayers.codeBanner)
       await world.page.keyboard.press('Enter')
 
       // The jump pages history in and lands on turn 1: its mark flips to the
diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml
index 7df0e3ba3e..8183f95981 100644
--- a/packages/client/ui-chat/README.i18n.yaml
+++ b/packages/client/ui-chat/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/client/ui-chat/README.md
-README.md: 19cfcf4d14f7e805d6113eeb4e34a586f7150574
-README.zh.md: 18e20eeea15cf3eeb5e8e4a777fa534251232a81
+README.md: 79214bf2feb8384cecbb152aa31af162dc6dfdde
+README.zh.md: 674959e1974c74abba75f179eff50fe8488458fc
diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md
index 19cfcf4d14..79214bf2fe 100644
--- a/packages/client/ui-chat/README.md
+++ b/packages/client/ui-chat/README.md
@@ -46,7 +46,7 @@ Settings → General exposes a persisted `Normal` / `Compact` conversation-displ
 <a id="scroll-ownership"></a>
 ## Scroll ownership
 
-Chat restores semantic anchors across history prepend and renderer remounts. While the reader is pinned to the floor, `ResizeObserver` follows the new floor and selects the latest loaded Turn without reading row geometry. Once the reader moves away, flow-height changes preserve the top position and the reading-line geometry selects the active Turn ([loaded-Turn navigation](../../../.agents/notes/implemented/feature/2026-08-25-loaded-turn-chat-navigation.md)).
+Chat restores semantic anchors across history prepend and renderer remounts. While the reader is pinned to the floor, `ResizeObserver` follows the new floor and selects the latest loaded Turn without reading row geometry. Once the reader moves away, flow-height changes preserve the top position and the reading-line geometry selects the active Turn. Turn-rail previews paint above sticky Markdown code-block banners, while the rail frame remains inside the transcript band above the composer ([loaded-Turn navigation](../../../.agents/notes/implemented/feature/2026-08-25-loaded-turn-chat-navigation.md)).
 
 -----
 
diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md
index 18e20eeea1..674959e197 100644
--- a/packages/client/ui-chat/README.zh.md
+++ b/packages/client/ui-chat/README.zh.md
@@ -46,7 +46,7 @@ Chat 会为每个非空的初始或恢复请求、显式消息序列起点或真
 <a id="scroll-ownership"></a>
 ## 滚动归属
 
-Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点。读者跟随底部时，`ResizeObserver` 追随新的底部，并且无需读取行几何就选中最后一个已加载 Turn；读者离开底部后，高度变化会保持顶部位置，再由阅读线几何选择活跃 Turn（[已加载 Turn 导航](../../../.agents/notes/implemented/feature/2026-08-25-loaded-turn-chat-navigation.zh.md)）。
+Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点。读者跟随底部时，`ResizeObserver` 追随新的底部，并且无需读取行几何就选中最后一个已加载 Turn；读者离开底部后，高度变化会保持顶部位置，再由阅读线几何选择活跃 Turn。轮次导航预览位于 Markdown 代码块粘性头栏上方，而导航外框始终处于 composer 上方的 transcript 区域内（[已加载 Turn 导航](../../../.agents/notes/implemented/feature/2026-08-25-loaded-turn-chat-navigation.zh.md)）。
 
 -----
 
diff --git a/packages/client/ui-chat/src/client/chat/TurnNavigator.module.css b/packages/client/ui-chat/src/client/chat/TurnNavigator.module.css
index 5e771e6727..b212032c96 100644
--- a/packages/client/ui-chat/src/client/chat/TurnNavigator.module.css
+++ b/packages/client/ui-chat/src/client/chat/TurnNavigator.module.css
@@ -3,7 +3,9 @@
 .slot {
   position: sticky;
   top: 0;
-  z-index: 6;
+  /* Above transcript CodeBlock banners (z-index 6). The rail band excludes
+     the composer, so its preview never needs to cross the footer. */
+  z-index: 7;
   height: 0;
   pointer-events: none;
 }

From 27bf1039dbb974be00cce8bd17d813c032fba6fb Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 31 Aug 2026 03:10:27 +0800
Subject: [PATCH 06/37] refactor(session)!: distinguish event seqs from log
 offsets

---
 .../2026-06-20-branded-ids.i18n.yaml          |   4 +-
 .../architecture/2026-06-20-branded-ids.md    |   2 +-
 .../architecture/2026-06-20-branded-ids.zh.md |   2 +-
 ...30-session-end-seed-log-boundary.i18n.yaml |   4 +-
 ...026-07-30-session-end-seed-log-boundary.md |   2 +-
 ...-07-30-session-end-seed-log-boundary.zh.md |   2 +-
 ...ubagent-list-identity-projection.i18n.yaml |   4 +-
 ...08-06-subagent-list-identity-projection.md |  57 ++--
 ...06-subagent-list-identity-projection.zh.md |  57 ++--
 ...n-sequence-and-log-offset-brands.i18n.yaml |   6 +
 ...-session-sequence-and-log-offset-brands.md |  45 ++++
 ...ssion-sequence-and-log-offset-brands.zh.md |  45 ++++
 ...026-06-30-session-store-fork-api.i18n.yaml |   4 +-
 .../2026-06-30-session-store-fork-api.md      |   6 +-
 .../2026-06-30-session-store-fork-api.zh.md   |   6 +-
 ...continuable-background-subagents.i18n.yaml |   4 +-
 ...-07-21-continuable-background-subagents.md |   4 +-
 ...-21-continuable-background-subagents.zh.md |   4 +-
 ...3-session-telemetry-otel-revival.i18n.yaml |   4 +-
 ...26-07-23-session-telemetry-otel-revival.md |   2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |   2 +-
 ...7-25-subagent-policy-inheritance.i18n.yaml |   4 +-
 .../2026-07-25-subagent-policy-inheritance.md |   2 +-
 ...26-07-25-subagent-policy-inheritance.zh.md |   2 +-
 .../2026-08-05-durable-web-schedule.i18n.yaml |   4 +-
 .../2026-08-05-durable-web-schedule.md        |   4 +-
 .../2026-08-05-durable-web-schedule.zh.md     |   4 +-
 ...-fork-child-replay-seed-boundary.i18n.yaml |   4 +-
 ...6-06-22-fork-child-replay-seed-boundary.md |  14 +-
 ...6-22-fork-child-replay-seed-boundary.zh.md |  14 +-
 .../tests/semantic-checkpoint.expected.e2e.ts |  13 +-
 .../session-format-guard.expected.e2e.ts      |   9 +-
 .../tests/subagent-diagnostic.expected.e2e.ts |  14 +-
 .../subagent-inheritance.expected.e2e.ts      |  13 +-
 .../workspace-context-resume.expected.e2e.ts  |  10 +-
 apps/cli/tests/web-agent-presets.e2e.ts       |  10 +-
 apps/web/tests/agent-preset-selection.e2e.ts  |  18 +-
 apps/web/tests/chat-long-interactions.e2e.ts  |   2 +-
 apps/web/tests/complex-history.perf.ts        |   4 +-
 apps/web/tests/reference-composer.e2e.ts      |   3 +-
 apps/web/tests/scaffold.ts                    |  19 +-
 apps/web/tests/schedule-after.e2e.ts          |  10 +-
 apps/web/tests/subagent-conversation.e2e.ts   |  44 ++--
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |  30 +--
 docs/config-catalog.zh.md                     |  22 +-
 docs/event-producer-consumer.i18n.yaml        |   4 +-
 docs/event-producer-consumer.md               |  14 +-
 docs/event-producer-consumer.zh.md            |  14 +-
 docs/persistence-catalog.i18n.yaml            |   4 +-
 docs/persistence-catalog.md                   |  64 ++---
 docs/persistence-catalog.zh.md                |  62 ++---
 docs/subsystems/commands.i18n.yaml            |   4 +-
 docs/subsystems/commands.md                   |   2 +-
 docs/subsystems/commands.zh.md                |   2 +-
 docs/subsystems/compaction.i18n.yaml          |   4 +-
 docs/subsystems/compaction.md                 |  18 +-
 docs/subsystems/compaction.zh.md              |  18 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       |   2 +-
 docs/subsystems/core.zh.md                    |   2 +-
 docs/subsystems/persistence.i18n.yaml         |   4 +-
 docs/subsystems/persistence.md                |  75 ++++--
 docs/subsystems/persistence.zh.md             |  75 ++++--
 docs/subsystems/schedule.i18n.yaml            |   4 +-
 docs/subsystems/schedule.md                   |   2 +-
 docs/subsystems/schedule.zh.md                |   2 +-
 docs/subsystems/session-projection.i18n.yaml  |   4 +-
 docs/subsystems/session-projection.md         |  28 +-
 docs/subsystems/session-projection.zh.md      |  28 +-
 docs/subsystems/session-query.i18n.yaml       |   4 +-
 docs/subsystems/session-query.md              |  28 +-
 docs/subsystems/session-query.zh.md           |  28 +-
 docs/subsystems/session-title.i18n.yaml       |   4 +-
 docs/subsystems/session-title.md              |  10 +-
 docs/subsystems/session-title.zh.md           |  10 +-
 docs/subsystems/session.i18n.yaml             |   4 +-
 docs/subsystems/session.md                    | 100 +++++--
 docs/subsystems/session.zh.md                 | 100 +++++--
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   2 +-
 docs/subsystems/subagent.zh.md                |   2 +-
 docs/subsystems/token-meter.i18n.yaml         |   4 +-
 docs/subsystems/token-meter.md                |   4 +-
 docs/subsystems/token-meter.zh.md             |   4 +-
 packages/acp/acp/tests/bridge.spec.ts         |  17 +-
 packages/acp/acp/tests/updates.spec.ts        |   8 +-
 packages/api/session-controller/src/agent.ts  |  11 +-
 .../src/client/contract/session.ts            |   6 +-
 .../src/client/sessions/manager.ts            |  19 +-
 .../src/client/sessions/projection-store.ts   |   9 +-
 .../src/client/sessions/service.ts            |   4 +-
 .../src/client/sessions/session.ts            |  38 ++-
 .../api/session-controller/src/commands.ts    |  19 +-
 .../api/session-controller/src/history.ts     |  98 +++++--
 packages/api/session-controller/src/index.ts  |  11 +-
 packages/api/session-controller/src/list.ts   |   5 +-
 packages/api/session-controller/src/types.ts  |  25 +-
 .../tests/agent.host.spec.ts                  |  50 ++--
 .../tests/client-contract.client.spec.ts      |  40 ++-
 .../commands-queue-attachment.host.spec.ts    |  28 +-
 .../tests/controller.host.spec.ts             |  37 ++-
 .../tests/event-script.client.ts              |  66 +++--
 .../tests/manager.client.spec.ts              |   3 +-
 .../tests/projection-store.client.spec.ts     |  41 +--
 .../tests/queue-store.client.spec.ts          |   6 +-
 .../tests/session-cold.host.spec.ts           | 119 ++++++---
 .../tests/session-fork.host.spec.ts           |  30 ++-
 .../session-history-journal.host.spec.ts      |  15 +-
 ...session-pending-submissions.client.spec.ts |  16 +-
 .../tests/session-projections.host.spec.ts    |  40 ++-
 .../tests/session-search.host.spec.ts         |   5 +-
 .../tests/session-skills.host.spec.ts         |   4 +-
 .../tests/session.client.spec.ts              | 179 ++++++-------
 .../session-controller/tests/test-remote.ts   |   8 +
 .../tests/transport.host.spec.ts              | 141 +++++++---
 packages/bundle/headless/src/index.ts         |   7 +-
 .../client/connection/src/client/fixture.ts   |  20 +-
 .../connection/tests/fixture.client.spec.ts   |   7 +-
 .../ui-chat/src/client/chat/ChatView.tsx      |   3 +-
 .../src/client/chat/turn-rail-items.ts        |   9 +-
 .../ui-chat/src/client/contract/slots.ts      |   3 +-
 .../tests/apply-inject.client.spec.tsx        |   4 +-
 .../tests/turn-rail-items.client.spec.ts      |   2 +
 .../conversation-assembler.client.spec.ts     | 155 +++++------
 .../tests/history-transport.perf.client.ts    |   3 +-
 .../tests/request-inspection.client.spec.ts   |  19 +-
 .../tests/tool-details-render.client.tsx      |   9 +-
 .../tests/rename-assembly.client.spec.tsx     |   4 +-
 .../tests/command-compact.spec.ts             |  12 +-
 .../tests/loader-composition.spec.ts          |  12 +-
 .../compaction/compaction-basic/src/index.ts  |   6 +-
 .../compaction/compaction-basic/src/region.ts |  26 +-
 .../tests/compaction-basic.spec.ts            |  16 +-
 .../src/index.ts                              |   4 +-
 .../src/types.ts                              |   5 +-
 packages/compaction/compaction/src/index.ts   |   6 +-
 .../compaction/compaction/src/invariant.ts    |  96 +++++--
 .../compaction/compaction/src/tool-pairing.ts |  12 +-
 packages/compaction/compaction/src/types.ts   |  19 +-
 .../compaction/tests/compaction.spec.ts       |   5 +-
 .../compaction/tests/invariant.spec.ts        | 124 +++++++--
 .../compaction/tests/tool-pairing.spec.ts     |  50 ++--
 .../tests/agent-instructions.spec.ts          |  14 +-
 .../context/session-reference/src/index.ts    |   8 +-
 .../session-reference/src/projection.ts       |   8 +-
 .../context/session-reference/src/types.ts    |   4 +-
 .../tests/session-reference.spec.ts           |  14 +-
 packages/context/time-context/src/index.ts    |   3 +-
 .../time-context/tests/invariant.spec.ts      |  12 +-
 packages/core/agent-loop/src/agent.ts         |   4 +-
 packages/core/agent-loop/src/index.ts         |   9 +-
 .../core/agent-loop/src/runtime-context.ts    |   6 +-
 packages/core/agent-loop/src/tool-calls.ts    |   8 +-
 packages/core/agent-loop/tests/resume.spec.ts |  38 +--
 packages/core/agent/src/inbox.ts              |   2 +-
 packages/core/agent/src/index.ts              |  10 +-
 packages/core/agent/src/types.ts              |   8 +-
 packages/core/session/README.i18n.yaml        |   4 +-
 packages/core/session/README.md               |   6 +-
 packages/core/session/README.zh.md            |   6 +-
 packages/core/session/src/chunk-rows.ts       |  23 +-
 packages/core/session/src/index.ts            | 113 +++++---
 packages/core/session/src/invariant.ts        |   4 +-
 packages/core/session/src/repair.ts           |  11 +-
 packages/core/session/src/seq-ranges.ts       |  17 +-
 packages/core/session/src/surface.ts          |  74 +++---
 packages/core/session/src/types.ts            |  65 ++++-
 .../core/session/tests/chunk-rows.spec.ts     |  72 ++---
 packages/core/session/tests/fork.spec.ts      |  37 ++-
 packages/core/session/tests/invariant.spec.ts |  12 +-
 packages/core/session/tests/repair.spec.ts    |  17 +-
 .../core/session/tests/request-header.spec.ts |   8 +-
 .../core/session/tests/seq-ranges.spec.ts     |  14 +-
 .../core/session/tests/sequence-types.spec.ts | 153 +++++++++++
 packages/core/session/tests/session.spec.ts   |  78 +++---
 packages/core/session/tests/surface.spec.ts   | 215 ++++++++-------
 .../experimental/agent-team/src/mailbox.ts    |   5 +-
 .../experimental/agent-team/src/roster.ts     |   8 +-
 .../agent-team/tests/persistence.spec.ts      |   2 +-
 .../tests/projection-events.spec.ts           |  82 +++---
 .../agent-team/tests/team.spec.ts             |  11 +-
 .../home/storages/session_projcache.json      |   6 +-
 .../tests/vfs-example-fixture.spec.ts         |  36 ++-
 .../tests/vfs-example-fixture.ts              |  71 +++--
 .../src/client/api-catalog.ts                 |   2 +-
 .../src/client/slot-catalog.ts                |  12 +-
 .../extensions/tool-cordis/src/api-catalog.ts | 144 ++++++----
 .../feedback/message-feedback/src/index.ts    |  11 +-
 .../message-feedback/tests/helpers.ts         |  31 ++-
 .../tests/loader-composition.spec.ts          |   4 +-
 .../tests/message-feedback.spec.ts            |  13 +-
 packages/fs/tool-fs/tests/tools.spec.ts       |  65 ++++-
 .../tests/tools.spec.ts                       |   2 +-
 packages/goal/goal/src/index.ts               |  15 +-
 packages/goal/goal/tests/goal.spec.ts         |   3 +-
 packages/goal/tool-goal/src/authority.ts      |   4 +-
 .../goal/tool-goal/tests/tool-goal.spec.ts    |  11 +-
 .../hook-protocol/tests/invariant.spec.ts     |   8 +-
 packages/interaction/commands/src/index.ts    |   7 +-
 packages/interaction/commands/src/types.ts    |   5 +-
 .../commands/tests/commands.spec.ts           |   1 +
 .../commands/tests/invariant.spec.ts          |   6 +-
 .../tests/invariant.spec.ts                   |   6 +-
 .../interaction/user-approval/src/index.ts    |   5 +-
 .../user-approval/tests/invariant.spec.ts     |   8 +-
 .../token-meter/src/breakdown-projection.ts   |   7 +-
 packages/llm/token-meter/src/index.ts         |  20 +-
 packages/llm/token-meter/src/surface-fold.ts  |   6 +-
 .../llm/token-meter/src/surface-projection.ts |  12 +-
 packages/llm/token-meter/src/types.ts         |   5 +-
 .../llm/token-meter/src/usage-projection.ts   |   5 +-
 .../context-breakdown-projection.spec.ts      |  45 ++--
 .../llm/token-meter/tests/token-meter.spec.ts |  24 +-
 .../tests/token-usage-projection.spec.ts      |  12 +-
 .../plan/plan-mode/tests/invariant.spec.ts    |  10 +-
 .../agent-presets/tests/session.spec.ts       |  11 +-
 .../sandbox-policy/tests/policy.spec.ts       |   1 +
 packages/schedule/AGENTS.md                   |   2 +-
 packages/schedule/schedule/README.i18n.yaml   |   4 +-
 packages/schedule/schedule/README.md          |   4 +-
 packages/schedule/schedule/README.zh.md       |   4 +-
 packages/schedule/schedule/src/domain.ts      |  15 +-
 packages/schedule/schedule/src/invariant.ts   |  10 +-
 packages/schedule/schedule/src/projection.ts  |  16 +-
 packages/schedule/schedule/src/runtime.ts     |   5 +-
 packages/schedule/schedule/src/tools.ts       |   2 +-
 .../schedule/schedule/tests/domain.spec.ts    |   9 +-
 .../schedule/schedule/tests/invariant.spec.ts |  13 +-
 .../schedule/tests/jsonl-restart.spec.ts      |   2 +-
 .../schedule/tests/projection.spec.ts         |  78 +++---
 .../tests/archive.host.spec.ts                |   3 +
 .../tests/route.host.spec.ts                  |  16 +-
 .../session-query-sqlite/README.i18n.yaml     |   4 +-
 .../session-query-sqlite/README.md            |   2 +-
 .../session-query-sqlite/README.zh.md         |   2 +-
 .../session-query-sqlite/src/index.ts         |  44 +++-
 .../tests/load-path.e2e.ts                    |  11 +-
 .../session-query-sqlite/tests/sqlite.spec.ts | 122 +++++++--
 .../session-query/README.i18n.yaml            |   4 +-
 .../session-query/session-query/README.md     |   2 +
 .../session-query/session-query/README.zh.md  |   2 +
 .../session-query/session-query/src/corpus.ts |  21 +-
 .../session-query/src/documents.ts            |   6 +-
 .../session-query/session-query/src/index.ts  |  24 +-
 .../session-query/src/observation.ts          |  20 +-
 .../session-query/src/sources.ts              |   2 +-
 .../session-query/src/tracing.ts              |  26 +-
 .../session-query/session-query/src/types.ts  |  31 ++-
 .../session-query/tests/observation.spec.ts   |  35 ++-
 .../tests/search-helpers.spec.ts              |  47 ++--
 .../session-query/tests/session-query.spec.ts | 111 +++++---
 .../session-query/tests/tracing.spec.ts       | 117 +++++----
 .../tool-session-query/src/operations.ts      |   7 +-
 .../tests/sqlite-integration.spec.ts          |  13 +-
 .../tests/tool-session-query.spec.ts          |  27 +-
 .../tests/session-checkpoint-policy.spec.ts   |  10 +-
 .../session-log-deepseek/README.i18n.yaml     |   4 +-
 .../session/session-log-deepseek/README.md    |   2 +-
 .../session/session-log-deepseek/README.zh.md |   2 +-
 .../session/session-log-deepseek/package.json |   1 +
 .../session/session-log-deepseek/src/index.ts |  90 +++++--
 .../session-log-deepseek/src/invariant.ts     |  12 +-
 .../session/session-log-deepseek/src/types.ts |  39 ++-
 .../tests/invariant.spec.ts                   |  36 ++-
 .../session-log-deepseek/tests/upload.spec.ts | 136 ++++++++--
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-jsonl/README.md       |   4 +-
 .../session-persistence-jsonl/README.zh.md    |   4 +-
 .../session-persistence-jsonl/src/format.ts   | 118 ++++++---
 .../session-persistence-jsonl/src/index.ts    |  65 +++--
 .../tests/jsonl.spec.ts                       | 123 +++++++--
 .../tests/zstd.spec.ts                        |  28 +-
 .../session-persistence/README.i18n.yaml      |   4 +-
 .../session/session-persistence/README.md     |  10 +-
 .../session/session-persistence/README.zh.md  |  10 +-
 .../session-persistence/src/coordinator.ts    | 229 ++++++++++++----
 .../session/session-persistence/src/index.ts  |  48 +++-
 .../session-persistence/tests/contract.ts     | 130 +++++++---
 .../tests/coordinator-contract.ts             | 167 ++++++++++--
 .../tests/persistence.spec.ts                 | 245 +++++++++++++-----
 .../tests/write-behind.spec.ts                |  38 +--
 .../session-projection-cache/README.i18n.yaml |   4 +-
 .../session-projection-cache/README.md        |   4 +-
 .../session-projection-cache/README.zh.md     |   4 +-
 .../session-projection-cache/src/index.ts     |  87 +++++--
 .../session-projection-cache/src/spec.ts      |  10 +-
 .../tests/cache.spec.ts                       | 148 ++++++++---
 .../session-projection/README.i18n.yaml       |   4 +-
 packages/session/session-projection/README.md |   6 +-
 .../session/session-projection/README.zh.md   |   6 +-
 .../session/session-projection/src/index.ts   | 105 +++++---
 .../session-projection/tests/registry.spec.ts | 172 +++++++++---
 .../session-telemetry-otel/tests/otel.spec.ts |   4 +-
 .../session-telemetry/src/coordinator.ts      |  16 +-
 .../session-telemetry/tests/telemetry.spec.ts |   5 +-
 .../tests/provider.spec.ts                    |   3 +-
 .../session/session-title-llm/src/index.ts    |   3 +-
 packages/session/session-title/src/index.ts   |  22 +-
 .../session/session-title/src/invariant.ts    |  48 +++-
 packages/session/session-title/src/types.ts   |   9 +-
 .../session-title/tests/invariant.spec.ts     |  56 +++-
 .../session-title/tests/projection.spec.ts    |  26 +-
 .../session-title/tests/provider.spec.ts      |   4 +-
 .../tests/service-contracts.spec.ts           |   8 +-
 .../session-title/tests/session-title.spec.ts |   6 +-
 .../session-turn-outline/src/projection.ts    |   4 +-
 .../session/session-turn-outline/src/types.ts |   4 +-
 .../tests/projection.spec.ts                  |  30 ++-
 .../tests/loader-composition.spec.ts          |   2 +-
 .../tool-bash-persistent/tests/tools.spec.ts  |   1 +
 packages/shell/tool-bash/tests/tools.spec.ts  |  42 ++-
 .../tests/loader-composition.spec.ts          |   2 +-
 .../tool-pwsh-persistent/tests/tools.spec.ts  |   1 +
 packages/shell/tool-pwsh/tests/tools.spec.ts  |  50 ++--
 packages/skill/tool-skill/src/index.ts        |   4 +-
 .../skill/tool-skill/tests/tool-skill.spec.ts |   2 +-
 .../tests/subagent-fork-in-process.spec.ts    |  14 +-
 .../subagent-in-process-driver/src/index.ts   |  12 +-
 .../tests/inheritance.spec.ts                 |   6 +-
 .../tests/subagent-in-process-driver.spec.ts  |   3 +-
 packages/subagent/subagent/src/child-agent.ts |   6 +-
 .../subagent/subagent/src/continuation.ts     |  19 +-
 packages/subagent/subagent/src/lifecycle.ts   |   5 +-
 .../subagent/subagent/src/list-children.ts    |  45 ++--
 .../subagent/subagent/src/projection-types.ts |   8 +-
 packages/subagent/subagent/src/projection.ts  |   5 +-
 .../tests/continuation-inheritance.spec.ts    |   6 +-
 .../subagent/tests/continuation.spec.ts       |   3 +-
 .../subagent/tests/list-children.spec.ts      |  53 ++--
 .../tests/tool-subagent-control.spec.ts       |   5 +-
 packages/subagent/tool-subagent/src/index.ts  |   3 +-
 .../terminal-bash/tests/index.spec.ts         |   4 +-
 packages/test-support/llm-replay/src/index.ts |  21 +-
 .../llm-replay/tests/llm-replay.spec.ts       | 156 +++++------
 .../session-snapshot/src/normalize.ts         |  10 +-
 .../todo/tool-todo/tests/invariant.spec.ts    |   8 +-
 .../todo/tool-todo/tests/tool-todo.spec.ts    |   4 +-
 .../generator/tests/schema-emitter.spec.ts    |  34 +++
 packages/util/brand/README.i18n.yaml          |   4 +-
 packages/util/brand/README.md                 |  30 ++-
 packages/util/brand/README.zh.md              |  30 ++-
 packages/util/brand/package.json              |   2 +-
 packages/util/brand/src/index.ts              |  24 +-
 packages/util/brand/tests/brand.spec.ts       |  13 +
 .../tool-ralph/tests/integration.spec.ts      |   3 +-
 .../workspace/tests/workspace.spec.ts         |   1 +
 pnpm-lock.yaml                                |   3 +
 scripts/gen-cordis-catalog.ts                 |   5 +
 scripts/session-fixture-layout.spec.ts        |   4 +-
 scripts/type-equiv.manifest.json              |  30 +++
 351 files changed, 5912 insertions(+), 2837 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.zh.md
 create mode 100644 packages/core/session/tests/sequence-types.spec.ts
 create mode 100644 packages/util/brand/tests/brand.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
index 2c4a5e3544..e847027821 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.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 .agents/notes/implemented/architecture/2026-06-20-branded-ids.md
-2026-06-20-branded-ids.md: 954fd89aa229ba587cd1293973b4038cfeb20473
-2026-06-20-branded-ids.zh.md: 0dd761da2e5b5fc3e864fe03c250b9781be9ee59
+2026-06-20-branded-ids.md: 1f579a7afb7ac5f7facd6c5e8040d5df719c4bed
+2026-06-20-branded-ids.zh.md: eaf032027f2f61bec9e4ab624622a5012c97e9b9
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
index 954fd89aa2..1f579a7afb 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
@@ -51,7 +51,7 @@ Kept deliberately narrow per the "not every string needs a brand" policy. Each o
 - **`ModelId`** (`GenerateOptions.model`, the `LlmRuntime` adapter-registry key) — a real cross-package lookup key (config → agent → llm → adapter); a reasonable next brand, left out only to keep this decision's blast radius focused.
 - **`ToolName`** (the `ToolRuntime` key) — author-defined, human-readable, and rarely confused with another id; the weakest candidate, likely not worth a brand.
 - **`ErrorCode`** (`HarnessError.code`) — a closed vocabulary (`ABORTED`, `NO_ADAPTER`, …), not a per-instance id; better served by a string-literal union than a brand, if anything.
-- **Numeric ordinals** — turn number, step number, and the event `seq` are `number`, not `string`, so `Branded<string>` does not apply; a parallel `number & { readonly [BRAND]: B }` variant could brand them, but they are positional ordinals rarely passed across boundaries, so the payoff is low.
+- **Other numeric ordinals** — the [Session sequence and log-offset decision](2026-08-31-session-sequence-and-log-offset-brands.md) brands event identities and log gaps because they cross persistence and reference seams. Turn and step numbers remain plain numbers: they are payload-local ordinals and are not interchangeable with Session event positions.
 - **Validated construction** — `brandString<T>()` performs no runtime check, and every boundary (ACP `sessionId`, provider-issued `call.id`, the empty-string fallback in `dsh-llm-deepseek`) trusts the raw string. A `SessionId.parse()` / `isValid()` companion that throws on malformed input at boundaries is a genuine gap, but it is a runtime-behavior change with its own design (what is "malformed"? what happens on failure?) and belongs in its own decision.
 
 ## Verification
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
index 0dd761da2e..eaf032027f 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
@@ -51,7 +51,7 @@ const owner = brandString<OwnerToken>('session-1')
 - **`ModelId`**（`GenerateOptions.model`，`LlmRuntime` 适配器注册表的键）：一个真正的跨包查找键（config → agent → llm → 适配器）；合理的下一个 brand，仅为控制本决策的影响范围而暂不纳入。
 - **`ToolName`**（`ToolRuntime` 的键）：由作者定义、人类可读，且很少与其他 id 混淆；最弱的候选，可能不值得加 brand。
 - **`ErrorCode`**（`HarnessError.code`）：一个封闭词汇（`ABORTED`、`NO_ADAPTER`……），不是逐实例的 id；如果要做，string 字面量联合类型比 brand 更合适。
-- **数值序号**：轮次号、步骤号和事件 `seq` 是 `number` 而非 `string`，`Branded<string>` 不适用；可以用并行的 `number & { readonly [BRAND]: B }` 变体来 brand 它们，但它们是位置序号、很少跨边界传递，收益较低。
+- **其他数值序号**：[Session 序列号与日志偏移决策](2026-08-31-session-sequence-and-log-offset-brands.zh.md)会为事件身份与日志间隙加 brand，因为它们跨越 persistence 与引用 seam。turn 与 step number 保持普通 number：它们是 payload-local ordinal，不会与 Session 事件位置互换。
 - **带校验的构造**：`brandString<T>()` 不执行运行时检查，且每个边界（ACP `sessionId`、提供方签发的 `call.id`、`dsh-llm-deepseek` 中的空字符串回退）都信任裸 string。一个在边界处对格式错误的输入抛异常的 `SessionId.parse()` / `isValid()` 配套工具确实是缺口，但它属于运行时行为变更，有自己的设计问题（什么算「格式错误」？失败时会怎样？），应在独立决策中处理。
 
 ## 验证
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
index a995ac778f..b91733813c 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.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 .agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
-2026-07-30-session-end-seed-log-boundary.md: 1c5a8097a6b901f133205dcd52d674a8e3594b28
-2026-07-30-session-end-seed-log-boundary.zh.md: ea3549543229a15d0fba7ad0316a8683c674a558
+2026-07-30-session-end-seed-log-boundary.md: c6ed3911a797480804d064273922d85412664c79
+2026-07-30-session-end-seed-log-boundary.zh.md: 1e9517f9a5aed819fdaff6194ab952c322c85b82
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
index 1c5a8097a6..c6ed3911a7 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
@@ -40,7 +40,7 @@ The predicate holds for a bracket *this* session inherited, not as a liveness si
 
 **A boundary appended at loop start.** The loop calls `resumeWith`, so it covers the resume paths, but it misses `fork()` and `adopt()` entirely, and the event would have to fire on `'startup'` — the source a fork child publishes — so `SessionStartSource` would stop discriminating. It also publishes the session before the marker is appended, so a `session/created` listener could observe a seeded log with no boundary.
 
-**Reusing `header.seedLength`.** It is the durable *fork-lineage* boundary and deliberately keeps the original fork value across a resume, where the constructor seed is the whole stored log. The two facts differ and conflating them would lose both.
+**Reusing `Session.inheritedEventCount`.** It is the durable *fork-lineage* cut and deliberately keeps the original fork value across a resume, where the constructor seed is the whole stored log. The two facts differ and conflating them would lose both.
 
 **Crash repair closing `compaction/*` alongside turn boundaries.** Rejected: it moves every plugin's bracket semantics into core's repair pass, and core cannot know what closing another package's bracket should record.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
index ea35495432..1e9517f9a5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
@@ -40,7 +40,7 @@ Status: implemented
 
 **在 loop 启动时追加边界。** loop 调用 `resumeWith`，因此覆盖恢复路径，但完全漏掉 `fork()` 与 `adopt()`，而且事件不得不在 `'startup'` 上触发——那是 fork 子会话发布的来源——于是 `SessionStartSource` 将不再具有区分力。它还会在追加标记之前就发布会话，因此 `session/created` 监听方可能观察到一份没有边界的带种子日志。
 
-**复用 `header.seedLength`。** 它是持久的 *fork 血缘*边界，并且刻意在恢复时保留原始 fork 取值——而恢复时构造种子是整份存储日志。这两个事实并不相同，混同会同时失去两者。
+**复用 `Session.inheritedEventCount`。** 它是持久的 *fork 血缘* cut，并且刻意在恢复时保留原始 fork 取值——而恢复时构造种子是整份存储日志。这两个事实并不相同，混同会同时失去两者。
 
 **让崩溃修复连同轮次边界一起关闭 `compaction/*`。** 否决：这会把每个插件的括号语义搬进核心的修复流程，而核心无法知道关闭另一个包的括号应该记录什么。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index 29613b58c7..cfdc3bd607 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.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 .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
-2026-08-06-subagent-list-identity-projection.md: aeed828530f615b1bb4958a360b5ba4db543f714
-2026-08-06-subagent-list-identity-projection.zh.md: b2b64eaa7c06b738734a7b975adb5948704465bd
+2026-08-06-subagent-list-identity-projection.md: cbb15696314930acfaf20ba8651699c53c5dbde2
+2026-08-06-subagent-list-identity-projection.zh.md: dbb62dbfc6bb6ca3ab63504de1ba8dd35327bbbf
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
index aeed828530..cbb1569631 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
@@ -14,16 +14,16 @@ The root cause is that the [durable-subagent-catalog decision](../feature/2026-0
 
 ## Decision
 
-mode and label are folded by the new `subagent` projection unit (pure identity, two arms), and the unit is the sole authority over the fold rules; `listChildren` no longer depends on session-query — enumeration is a subagent-owned live-preferred merge, and value retrieval walks a three-rung compute-and-discard ladder: a live child synchronously reads the registry's existing watermark cache (zero log reads); a cold child first asks the optional `sessionProjectionCache` checkpoint, and a served identity that passes the seq gate is final; otherwise it pays one full `persistence.inspect` read plus a fold through the registered `subagent` unit. No index, no cache of its own, no write-back.
+mode and label are folded by the `subagent` projection unit (pure identity, two arms), and the unit is the sole authority over the fold rules. Enumeration uses the shared Session query corpus, while value retrieval walks a three-rung compute-and-discard ladder: a live child synchronously reads the registry's existing watermark cache (zero log reads); an unseeded cold child may use the optional `sessionProjectionCache` checkpoint because its exact inherited cut is known to be zero; every seeded child and every cache miss pays one body-bearing Session observation plus a fold through the registered `subagent` unit. No index, no cache of its own, no list-side write-back.
 
 There are three families of escape from the per-child scan: promote mode/label into the header (the write path pays); build a durable derivation for the projection (a checkpoint ladder, or values landed during query-index rebuild with read-side reconciliation); or compute at read time (live from the watermark cache, cold from one full read). This note takes the third. "Values landed with the query index" was retired wholesale: query infrastructure was forced to learn domain vocabulary while the sole consumer is satisfied by read-time computation — the live child's zero reads come for free from session-projection's existing watermark cache, and the cold child's single full read is explicitly accepted as compute-and-discard. The first two routes and the retirement rationale are detailed under Alternatives considered.
 
 Key points:
 
-- **The subagent list does not depend on session-query**: enumeration is completed by a subagent-owned live-preferred merge, and mode/label is retrieved through `ctx.sessionProjections`; deployments without a query backend list as usual.
-- **Value retrieval is a three-rung compute-and-discard ladder**: a live child reads `sessionProjections.snapshot(session, ['subagent'])` (the registry's existing watermark cache, zero log reads); a cold child first reads the optional `sessionProjectionCache.cachedSnapshot(header, ['subagent'])`, using the non-null identity directly when it passes the seq gate (`seq >= seedLength ?? 0`); otherwise it pays one full Session observation plus a fold through the registered `subagent` unit; beyond that, absent is absent — no cache of its own, no write-back, no index.
+- **The subagent list uses the Session query corpus for enumeration and body-bearing observations**: mode/label still comes through `ctx.sessionProjections`, and the list owns no descriptor parser or domain index.
+- **Value retrieval is a three-rung compute-and-discard ladder**: a live child reads `sessionProjections.snapshot(session, ['subagent'])` (the registry's existing watermark cache, zero log reads); an unseeded cold child may read `sessionProjectionCache.cachedSnapshot(header, SessionLogOffset(0), ['subagent'])`; a seeded child or cache miss pays one Session observation carrying `inheritedEventCount` plus a fold through the registered `subagent` unit. Beyond that, absent is absent — no cache of its own, no list-side write-back, no index.
 - **The `subagent` projection unit is the sole authority over the fold rules**: live and cold snapshots both run the one registered unit; no second copy of descriptor-interpretation logic exists.
-- **The header, the descriptor (v2), session-persistence, session-projection(-cache), and session-query(-sqlite) are all untouched**; pre-existing data acquires exact values through one `inspect` computation the first time it is listed — no degraded unknown state, no migration.
+- **The descriptor (v2) remains untouched**. Session, persistence, projection cache, and query now carry the exact inherited cut separately from the logical header; pre-existing data acquires exact values through one body-bearing observation when listing cannot prove a zero cut — no degraded unknown state and no durable format migration.
 
 Relationship to existing notes:
 
@@ -36,8 +36,8 @@ It hangs beside the existing `subagentTiming` ([projection.ts](../../../../packa
 
 ```ts ignore-check
 export type SubagentIdentityProjection =
-  | { mode: 'one-shot'; label?: string; seq: number }
-  | { mode: 'continuable'; label: string; seq: number }
+  | { mode: 'one-shot'; label?: string; seq: SessionSeq }
+  | { mode: 'continuable'; label: string; seq: SessionSeq }
 
 declare module '@deepseek-ai/dsh-session-projection/types' {
   interface SessionProjectionStateMap {
@@ -52,19 +52,19 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 
 - The projection is pure identity, and **the projection system has no failure channel**: a unit never throws; a corrupt payload or an unrecognized version folds exactly like a log with no descriptor at all. The host checkpoint state is the serializable wrapper `{ identity?: SubagentIdentityProjection }`; absence is `{}`. Its client view is the non-optional `SubagentIdentityProjection | null` entry. `null` passes JSON losslessly, so a pushed reset replaces a stale identity instead of being dropped by stringify. The judging discipline: consuming surfaces treat null and an absent client key alike as no value. How "computed to nothing" is presented is the consumer's own business (see the `listChildren` four-state mapping below).
 - Label strength is decided by the descriptor schema: a continuable's label is mandatory at parse, a one-shot's was always optional; the mode/label discriminant matches the child row's strong contract below exactly (the row carries no `seq` — it is the projection's internal own-suffix proof).
-- The identity carries `seq`: the seq of the `subagent/descriptor` event it was folded from, mandatory on both arms and absent on the null sentinel — `seq >= header.seedLength ?? 0` proves the identity was folded from the child's own suffix rather than a fork seed's replayed ancestor descriptor. The unit maps the wrapper's validated identity to its client wire view and is checkpointed like every unit (the `persist` opt-in is gone); its `stateVersion` is 2, bumped when `seq` was added. Existing older checkpoint rows are invalidated by version mismatch per the registry contract, falling to the authoritative refold.
+- The identity carries branded `seq`: the seq of the `subagent/descriptor` event it was folded from, mandatory on both arms and absent on the null sentinel. A live Session checks it through `isOwnSeq()`; a cold body-bearing observation compares it with `inheritedEventCount`. Header-only seeded candidates skip the cache because the header intentionally exposes no integer cut; unseeded candidates know the cut is zero. The unit maps the wrapper's validated identity to its client wire view and is checkpointed like every unit (the `persist` opt-in is gone); its `stateVersion` is 2, bumped when `seq` was added. Existing older checkpoint rows are invalidated by version mismatch per the registry contract, falling to the authoritative refold.
 - Fold rule: `subagent/descriptor` is last-wins, under the same descriptor-reset discipline as `subagentTiming` — ancestor descriptors in the fork prefix are overridden by the session's own descriptor. A corrupt or unrecognized-version payload is last-wins all the same: it resets to the null sentinel rather than keeping the prior identity, so a fork of a healthy ancestor does not inherit an identity its own descriptor cannot stand up.
 
-### Enumeration: subagent-owned live-preferred merge
+### Enumeration: query corpus with live preference
 
-`listChildren`'s ([list-children.ts](../../../../packages/subagent/subagent/src/list-children.ts)) enumeration goes through no query service: the two sources `ctx.sessions.list()` and `ctx.get('sessionPersistence')?.list()` merge by id, with a live record overriding the same-id persisted record wholesale and no header consistency check. Everything enumeration needs is header facts:
+`listChildren` ([list-children.ts](../../../../packages/subagent/subagent/src/list-children.ts)) asks `sessionQuery.listSessions()` for the canonical live-preferred corpus, then pairs each listed id with `ctx.sessions.get(id)` when a live Session exists. The live header overrides the listed header for that id. Everything enumeration needs is header facts:
 
 - Filtering: `header.origin === 'subagent' && header.parentSession === parentSessionId`.
 - `hasChildren`: the same merged material, looked at one level down — a direct descendant exists with `origin === 'subagent'` whose `parentSession` is that child.
 - `activity`: a live record is `running`; one present only in persistence is `inactive`.
 - Ordering: `createdAt` ascending, then child id ascending (matching the old contract).
-- **Absent persistence degrades to live-only enumeration, not an error**: in a deployment without persistence, a cold child could not be resumed anyway, and listing live children remains meaningful. (Contrast: the old implementation rejected wholesale when sessionQuery was missing.)
-- A persistence listing failure fails the whole enumeration; per-child isolation applies only to the per-child cold reads.
+- An absent `sessionQuery` service fails with `SUBAGENT_CONTROL_QUERY_UNAVAILABLE`; the shared query corpus owns whether a deployment can enumerate live-only or persisted Sessions.
+- A query-corpus failure fails the whole enumeration; per-child isolation applies only to per-child cold observations.
 
 ### Value retrieval: the three-rung compute-and-discard ladder
 
@@ -73,20 +73,20 @@ For each enumerated child, mode/label retrieval walks a three-rung ladder — co
 | Rung | Read | Cost |
 | --- | --- | --- |
 | 1: live child | `ctx.sessionProjections.snapshot(session, ['subagent'])` | Zero log reads — the registry's existing watermark cache, synchronous retrieval |
-| 2: cold child, cache hit | The optional `sessionProjectionCache.cachedSnapshot(header, ['subagent'])`, used directly only when the non-null identity satisfies `identity.seq >= header.seedLength ?? 0` — an own descriptor is immutable once appended, and the seq gate proves the value was folded from the child's own suffix, regardless of the row's watermark | Zero log reads |
-| 3: cold child, fallback | One full `persistence.inspect(id)` read + a fold through the registered `subagent` unit | One full read computed per listing |
+| 2: unseeded cold child, cache hit | The optional `sessionProjectionCache.cachedSnapshot(header, SessionLogOffset(0), ['subagent'])`; every valid seq is owned when the exact cut is zero | Zero log reads |
+| 3: seeded child or cold fallback | One body-bearing `sessionQuery.observeSession(id)` + the registered `subagent` projection, with `inheritedEventCount` available for the own-suffix check | One full read computed per listing |
 
-- Error contract: `sessionProjections` is a required injection — `SubagentRuntime` declares it in its inject set, so a deployment without the registry never activates the service (or the loop), and `listChildren` is unreachable rather than served degraded rows ([mandatory-seam note](2026-08-19-session-projection-mandatory-seam.md)); the loud runtime check and `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` are deleted with it. The session store keeps the explicit posture: an absent `ctx.get('sessions')` (a strict global read, never the caller-scope-bound property proxy) fails with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. apiproxy's dedicated `PROJECTIONS_UNAVAILABLE` wire face is deleted along with the code; `SESSION_STORE_UNAVAILABLE` goes through the generic internal fallback — apiproxy's composition injects `sessions` itself, so that error is unreachable in its deployment, and a dedicated mapping would violate the need principle. `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` is deleted along with the session-query dependency.
-- The cache is a purely optional acceleration layer: an absent service is skipped on a null check — no error code, no part in configuration validation (in contrast to `sessionProjections`, a required injection). Anything the second rung throws (including a poisoned unit row in the cache detonating `viewCheckpoint`) silently falls to the third rung — the cache is derived data, so its faults never produce a `corrupt` verdict; the final judgment belongs to the authoritative refold. A row whose checkpoint cut predates the descriptor naturally lacks the `subagent` key and falls through automatically, with no special-casing; a null sentinel in the row does not count either — it falls to the third rung for the authoritative refold's verdict. A count/interval checkpoint inside the creation window can land a fork seed's replayed ancestor identity in the row — the ancestor's seq falls inside the seed range, the seq gate rejects it, and it likewise falls to the third rung's verdict.
+- Error contract: `sessionProjections`, the Session store, and `sessionQuery` are required runtime services for listing. Their explicit failures are `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`, and `SUBAGENT_CONTROL_QUERY_UNAVAILABLE`; no empty result disguises a missing classification or corpus capability.
+- The cache is a purely optional acceleration layer: an absent service is skipped on a null check — no error code, no part in configuration validation (in contrast to `sessionProjections`, a required injection). A seeded header skips this rung because it cannot supply the cache identity's exact cut without a body read. For an unseeded child, anything the second rung throws (including a poisoned unit row detonating `viewCheckpoint`) silently falls to the third rung — the cache is derived data, so its faults never produce a `corrupt` verdict; the final judgment belongs to the authoritative refold. A row whose checkpoint cut predates the descriptor, an absent key, or a null sentinel likewise falls through.
 - Per-child isolation: a single child's failed cold full read only turns that row into an `unavailable` diagnostic, naturally retried on the next listing, without affecting siblings (see the four-state mapping).
-- The cold path's lifecycle witness: preparation's result must still point at the lifecycle that was enumerated — the witness field set is the same seven fields as the old SOURCE_CONFLICT check (version, id, createdAt, cwd, parentSession, seedLength, delegationDepth); a session deleted and republished under the same id degrades to a `corrupt` row in the old parent's catalog, leaking nothing of the new owner's child.
+- The cold path's lifecycle witness: the observation must still point at the lifecycle that was enumerated. The witness fields are version, id, createdAt, cwd, parentSession, isSeeded, delegationDepth, origin, and agentPreset; a Session deleted and republished under the same id degrades to a `corrupt` row in the old parent's catalog, leaking nothing of the new owner's child.
 - Cold-read concurrency is bounded by the constant 4 — it constrains a read-only scan of local media, not deployment behavior; when a networked persistence backend appears, it is promoted to a validated `Config` field.
-- The cold-read cost, recorded honestly: only with the cache unmounted or missed does a cold child pay one full read per listing, at a cost proportional to its transcript size; the settled stance is compute-and-discard, and no cache of its own is built. The full read goes through `inspect()` into the [Session preparation](2026-08-05-session-preparation.md) cold read, so short-term repeated reads of the same id can hit its LRU for reuse, but listing does not depend on this. A live child reads zero log throughout.
+- The cold-read cost, recorded honestly: every seeded child and every unseeded cache miss pays one full query observation per listing, at a cost proportional to its transcript size; the settled stance is compute-and-discard, and no cache of its own is built. The observation may reuse the query/persistence preparation layer, but listing does not depend on that optimization. A live child reads zero log throughout.
 - Cancellation: the caller's signal is checked before and after each persistence read, and a read that settles only after abort is rejected, normalized to the stable error code `CANCELLED`.
 
 ### Authority model
 
-- The session log is the sole authority; this design adds no derived persistence of any kind — no index values, no checkpoints of its own, no in-process memo; the `sessionProjectionCache` checkpoint the second rung reads is an existing composition item's derived data, which this design only reads and never writes. Values are computed on read and discarded, and a value's freshness is exactly the live state or persisted revision at the moment of the read (an own descriptor is immutable once appended — a cached identity past the seq gate has no staleness problem; the gate guards against seed-replayed ancestor identities).
+- The session log is the sole authority; this design adds no domain index, checkpoint of its own, or in-process memo. The `sessionProjectionCache` checkpoint the second rung reads is an existing composition item's derived data, which the list only reads. Values are computed on read and discarded. Seeded candidates use a body-bearing observation to classify the identity against the exact cut; unseeded cached identities need no seq gate because every valid seq is owned.
 - The Session and persistence write paths are entirely unaware of listing and projection consumption: no event-listener write-back, no fold-on-write.
 - Enumeration and value retrieval constitute no second authorization source and make no unpublished child visible — the two sources see only published live records and durably written persisted records, consistent with the rule the durable-subagent-catalog note laid down for derived read surfaces.
 
@@ -127,25 +127,24 @@ For each enumerated child, the ladder's result maps to a row through four states
 
 Known boundary deviations (deliberately accepted, recorded with this note):
 
-- A fork child that died in its publication window, with an ancestor descriptor in its seed, gets the ancestor identity from last-wins and wrongly surfaces as a child row; resume still fails against the own-suffix fold authority (`NOT_RESUMABLE`). The old implementation omitted it via `seedLength` filtering; the projection unit cannot see the header, and this debris-grade deviation is accepted (`subagentTiming` has the same kind of pre-existing exposure).
 - Multiple descriptors in the own suffix: the old implementation judged corrupt; last-wins now takes the final one (the provider contract guarantees exactly one anyway).
 - A live/persisted header conflict: the old implementation made it per-child corrupt; enumeration now prefers live with no consistency check, the conflict goes unnoticed, and the live record forms the row.
 - A source-read failure on damaged storage (e.g. a bad surface rejected by the cold full read): the old implementation mapped it to per-child `corrupt`; it is now uniformly an `unavailable` row (the read side cannot tell the causes apart).
 - An unknown parent: the old implementation threw not-found through session-query ('parent session … was not found'); the subagent-owned merge now yields an empty subset for a nonexistent parent, enumeration returns an empty list, and later operations on the wire land as child-level subagent-not-found — a silent change of semantics and wording, recorded as explicitly accepted.
-- Rung 2's later-event window: a cache row lands right after the first own descriptor, the log then appends a second own descriptor (or a malformed payload setting the null sentinel), and the process crashes before the next checkpoint — from then on a cold listing's rung 2, admitted by the seq≥seedLength gate, keeps serving the row's old identity (the first own descriptor's value), diverging from the authoritative refold (last-wins, the second), and a rung-2 hit triggers no refold, so nothing notices. Three boundaries: ① the precondition is a second own descriptor on the same child, violating the establishing provider's append-exactly-once contract — corruption-class data, same family and source as the multi-descriptor deviation; ② it takes both "corruption + a crash missing every checkpoint (the two mandatory points, turn/end and disposal, and the count/interval throttle points all unmet)" at once; ③ a healthy child (exactly one own descriptor) is unaffected — what the seq gate admits is precisely the only true identity. Self-healing: any live run of that child (the turn/end mandatory checkpoint) or any moment that triggers cache.write overwrites the whole row with a fresh fold (whole-record replace), and rung 2 serves correctly from then on; the authoritative paths (the rung-3 refold, the live snapshot, the resume fold) are correct from the start, and the divergence exists only in listing reads while the child stays cold and the row is never rewritten. The mechanical fixes were not taken: gate reconciliation would need the log-end seq, unavailable to a zero-read cold path; a cache row carrying the revision is an opaque token, incomparable and a cross-domain schema change — filed as accepted under the "the cache is never authoritative" doctrine.
+- Rung 2's later-event window applies only to an unseeded child: a cache row lands right after the first descriptor, the log then appends a second descriptor (or a malformed payload setting the null sentinel), and the process crashes before the next checkpoint. Cold listing can keep serving the old identity until a live run or cache write replaces the row. The precondition violates the provider's append-exactly-once contract and also requires missing every mandatory checkpoint; healthy children are unaffected. Seeded children never take rung 2 without the body-owned cut.
 
-Consuming surfaces: diagnostic handling across wire, tool, and GUI **stays entirely as it was, zero changes** (the `list_agents` description and output schema are untouched; the plugin's load requirement changes — `sessionQuery` dropped from inject, `sessionProjections` added as a required injection). The only behavioral changes are in apiproxy: on the route segment, the `hasSubagentDescriptor()` scan is deleted and `hasSubagentOwner` looks only at `header.origin` — pre-#1569 data without `origin` is no longer recognized as a subagent owner; it never entered the catalog anyway, and the pre-release stance accepts this; and `subagents.history` is aligned with `session.history`'s source — a live child served from in-memory events and the registry's watermark snapshot, a cold child from `inspectServable` reading persistence directly with a detached fold, no query service involved, the SESSION_QUERY_* error arms retired with it, and the wire shape unchanged (the `history` JSDoc wording becomes the live in-memory snapshot / cold persisted log dual arm).
+Consuming surfaces keep the same row and diagnostic wire shape. `list_agents` reaches the required query corpus plus projection registry; live identities come from the registry snapshot and cold identities from cache or query observation. Host ownership still uses `header.origin`, and history uses the shared live/cold Session query sources; no consumer parses descriptor events independently.
 
 ### Change footprint
 
 | Area | Files | Change |
 | --- | --- | --- |
 | subagent | projection.ts, projection-types.ts, index.ts | New client-visible `subagent` unit and its registration |
-| subagent | list-children.ts and its types | Rewritten as subagent-owned enumeration plus the projection-ladder four-state mapping; the session-query dependency, per-child event reads, and in-place classification machinery deleted; error code `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` deleted, and `sessionProjections` becomes a required injection (no projection error code remains); new optional dependency dsh-session-projection-cache (pure read acceleration, skipped when absent) |
-| host/apiproxy | api-proxy.ts | `hasSubagentDescriptor` deleted; the owner check looks only at `header.origin`; `subagents.history` shares `session.history`'s source — live from in-memory events and the registry's watermark snapshot, cold from `inspectServable` reading persistence directly with a detached fold, no query service, the SESSION_QUERY_* error arms and the dedicated `PROJECTIONS_UNAVAILABLE` wire face retired with it |
-| tool | tool-subagent-control/list-agents.ts | Load requirement narrowed (`sessionQuery` dropped from inject); model-visible schema, description, and rendering unchanged |
+| subagent | list-children.ts and its types | Query-corpus enumeration plus the projection-ladder four-state mapping; required projections/query services and optional projection-cache acceleration |
+| host/apiproxy | Session controller/query integration | Owner checks use `header.origin`; live/cold history and listing consume the shared query and projection sources |
+| tool | tool-subagent-control/list-agents.ts | Model-visible schema, description, and rendering remain unchanged |
 | wire/client | api/subagents.ts, runtime sessions/service.ts, GUI | Types, row shape, and diagnostic handling **unchanged**; api/subagents.ts only reworded the `history` JSDoc to the dual arm |
-| core/session, session-persistence, session-projection(-cache), session-query(-sqlite) | — | **Zero changes** |
+| core/session, session-persistence, session-projection(-cache), session-query(-sqlite) | body-bearing cut and branded seq plumbing | Logical headers expose `isSeeded`; Session, persistence observations, cache identity, and query records carry exact `inheritedEventCount` separately |
 
 ## Alternatives considered
 
@@ -169,20 +168,20 @@ Consuming surfaces: diagnostic handling across wire, tool, and GUI **stays entir
 
 ## Verification
 
-`packages/subagent/subagent/tests/list-children.spec.ts` is rewritten to this contract: live-only listing without persistence, query services, or the continuation runtime; without the registry the service never activates (the mandatory seam — a `setup` variant asserting `ctx.get('subagents')` stays undefined); a live child incurs zero `inspect` throughout while a cold child incurs exactly one per listing; multiple descriptors resolve last-wins to the final one; corrupt payloads and unknown versions fold to `corrupt`; a cold-read failure maps to `unavailable` and retries on the next listing; the ancestor descriptor in a fork seed forms a row under that identity (pinning deviation one); ordinary forks and descendants without a subagent origin neither enter the list nor count toward `hasChildren`; `createdAt`-then-id ordering; an unmounted provider does not affect listing; compacted and uncompacted twins list identically; the three cases of pre-abort, persistence listing, and cold-read cancellation all normalize to `CANCELLED`; the empty list and stable error codes (`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` for an absent store). Second-rung cases: an own-seq identity used directly with zero `inspect`, a fork seed's ancestor identity (seq inside the seed range) rejected by the gate and falling through, an in-row identity absence (null sentinel or absent key) falling through, an absent cache service falling through, and a poisoned cache row silently falling through to the refold; cold-path lifecycle tampering degrades to `corrupt` field by witness field (`it.each` over the seven). The `tool-subagent-control` list-agents tests are updated for the narrowed load requirement; `optional-session-query.spec.ts` is deleted with the dependency it guarded; the existing keyless snapshots (`subagent-list-agents` among others) are unchanged, pinning that the healthy path's wire and model-visible surfaces did not move; a new keyless snapshot, `subagent-diagnostic` (examples/headless-agent), pins the four-state mapping's diagnostic classification — the model-visible changes such as descriptor-less settled debris becoming a `corrupt` row.
+`packages/subagent/subagent/tests/list-children.spec.ts` pins this contract: live identity checks use `Session.isOwnSeq()`; an unseeded cold identity may use the cache at cut zero; seeded candidates skip that cache rung and use an observation carrying `inheritedEventCount`; ancestor identities fail the own-suffix check; absent, null, poisoned, and unavailable cache/observation cases fall through or produce the documented diagnostic; lifecycle tampering degrades to `corrupt` across the complete witness field set. The existing keyless snapshots keep the healthy wire and model-visible surfaces fixed, while `subagent-diagnostic` pins diagnostic classification.
 
 ## Consequences
 
 - Listing a live child reads zero log throughout; with the cache unmounted or missed, a cold child pays one full `inspect` read per listing, at a cost proportional to its transcript size and repeated with listing frequency — compute-and-discard is the settled stance: no cache of its own is built, nothing is written back, and short-term repeated full reads of the same id can hit the preparation-phase LRU, though listing does not depend on it.
-- The subagent list no longer requires a query backend: both pure-live and persistence-less deployments can list; `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` is gone, loading the `list_agents` plugin no longer requires `sessionQuery`, and `sessionProjections` becomes a required injection of `SubagentRuntime` — a deployment without the projection registry never activates the service (the mandatory seam).
+- The subagent list requires the Session query corpus and projection registry; missing services fail explicitly instead of producing incomplete rows. The optional projection cache changes only the number of body reads.
 - Identity interpretation exists only in the single unit registered with the registry: the list's three-rung ladder and GUI history's cold read use its live, cached, or observed wire snapshots, and no hand-written bypass fold exists; if some future consuming surface bypasses the unit with a hand-written fold, values will drift across read faces — a discipline this design requires be maintained, not a mechanical guarantee.
 - Per-child isolation is back: a single child's cold-read failure loses only that row and healthy siblings are unaffected; a persistence listing failure still fails the whole enumeration.
-- The diagnostic and enumeration semantics leaves six boundary deviations (a stillborn fork surfacing under its ancestor's identity, multiple descriptors resolving to the last, header conflicts going unnoticed, damaged-source read failures shifting from `corrupt` to `unavailable`, an unknown parent yielding an empty list instead of not-found, and rung 2's later-event window); the full semantics is in the known-boundary-deviations list; the first four are display or classification deviations on debris-grade data, the unknown-parent one is a silent query-semantics change, and the rung-2 window is a self-healing cache-serving divergence under the double condition of corruption plus a crash; resume authorization is unaffected throughout, all explicitly accepted.
+- The diagnostic and enumeration semantics leaves five boundary deviations (multiple descriptors resolving to the last, header conflicts going unnoticed, damaged-source read failures changing classification, an unknown parent yielding an empty list instead of not-found, and the unseeded rung-2 later-event window). Seeded ancestor identities are no longer a deviation because body-bearing reads compare them with `inheritedEventCount`; resume authorization remains unaffected.
 - Pre-#1569 data without `origin` is no longer recognized as a subagent owner; it never entered the catalog anyway, and pre-release carries no compatibility promise.
 
 ## Related
 
-- [Durable subagent catalog and list_agents](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) — partially superseded by this note: the descriptor remains the durable authority for mode/label and the fold input, while the list's enumeration and value retrieval move to the subagent-owned merge plus the projection ladder.
+- [Durable subagent catalog and list_agents](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) — partially superseded by this note: the descriptor remains the durable authority for mode/label and the fold input, while value retrieval moves to the projection ladder over the shared query corpus.
 - [Session projections and command lifecycle logging](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md) — the authority for the registry contract; this note adds the `subagent` identity unit and consumes its live and cold wire snapshots.
 - [Session projection state and client views](2026-08-19-session-projection-state-and-client-views.md) — the state/client split; both `subagent` and `subagentTiming` provide client wire views.
 - [Session projections as a required seam](2026-08-19-session-projection-mandatory-seam.md) — `sessionProjections` becomes a required injection; the list's error contract follows it (registry absence is an activation-time failure, and the projection error code is deleted).
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index b2b64eaa7c..dbb62dbfc6 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -14,16 +14,16 @@ Status: implemented
 
 ## 决策
 
-mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威；`listChildren` 不再依赖 session-query——枚举是 subagent 自管的 live-preferred 合并，取值走三级「算完即止」阶梯：live child 同步读注册表的既有水位缓存（零日志读）；cold child 先问可选的 `sessionProjectionCache` checkpoint，取到过 seq 门的身份即定值；否则一次 `persistence.inspect` 整读加经注册的 `subagent` unit 折叠。无索引、不自建缓存、无回写。
+mode 与 label 由 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威。枚举使用共享 Session query corpus，取值则走三级「算完即止」阶梯：live child 同步读注册表的既有水位缓存（零日志读）；unseeded cold child 可以使用可选 `sessionProjectionCache` checkpoint，因为其精确 inherited cut 已知为零；每个 seeded child 与每次 cache miss 都执行一次含正文的 Session observation，再经注册的 `subagent` unit 折叠。无索引、不自建缓存、列表侧无回写。
 
 消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（写路承担）；为投影建持久派生（checkpoint 阶梯，或随查询索引重建落值、读端对账）；读时现算（live 走水位缓存，cold 一次整读）。本记录取第三条。「值随查询索引落库」已整体退役：查询基础设施被迫认识领域词汇，而唯一消费方读时现算即可满足——live child 的零读由 session-projection 既有水位缓存白拿，cold child 的一次整读被「算完即止」显式接受。前两条与退役理由详见考虑过的替代方案一节。
 
 要点：
 
-- **subagent 列表不依赖 session-query**：枚举由 subagent 自管的 live-preferred 合并完成，mode/label 经 `ctx.sessionProjections` 取值；没有 query backend 的部署照常列表。
-- **取值三级「算完即止」阶梯**：live child 读 `sessionProjections.snapshot(session, ['subagent'])`（注册表既有水位缓存，零日志读）；cold child 先读可选 `sessionProjectionCache.cachedSnapshot(header, ['subagent'])`，非 null 身份通过 seq 门（`seq >= seedLength ?? 0`）即直接使用；否则执行一次完整 Session 观察，再经注册的 `subagent` unit 折叠；再没有就没有——不自建缓存、无回写、无索引。
+- **subagent 列表使用 Session query corpus 完成枚举与含正文 observation**：mode/label 仍经 `ctx.sessionProjections` 获取，列表不拥有 descriptor parser 或领域索引。
+- **取值三级「算完即止」阶梯**：live child 读 `sessionProjections.snapshot(session, ['subagent'])`（注册表既有水位缓存，零日志读）；unseeded cold child 可读 `sessionProjectionCache.cachedSnapshot(header, SessionLogOffset(0), ['subagent'])`；seeded child 或 cache miss 执行一次携带 `inheritedEventCount` 的 Session observation，再经注册的 `subagent` unit 折叠。再没有就没有——不自建缓存、列表侧无回写、无索引。
 - **`subagent` projection unit 是折叠规则唯一权威**：live 与 cold 快照都运行同一份已注册 unit，不存在第二份描述符解释逻辑。
-- **header、描述符（v2）、session-persistence、session-projection(-cache)、session-query(-sqlite) 全部零改动**；存量数据第一次被列表时一次 `inspect` 现算获得精确值，无 unknown 降级态、无迁移。
+- **描述符（v2）保持不变**。Session、persistence、projection cache 与 query 在 logical header 之外单独携带精确 inherited cut；listing 无法证明 cut 为零时，存量数据经一次含正文 observation 获得精确值——无 unknown 降级态，也无持久格式迁移。
 
 与既有记录的关系：
 
@@ -36,8 +36,8 @@ mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠
 
 ```ts ignore-check
 export type SubagentIdentityProjection =
-  | { mode: 'one-shot'; label?: string; seq: number }
-  | { mode: 'continuable'; label: string; seq: number }
+  | { mode: 'one-shot'; label?: string; seq: SessionSeq }
+  | { mode: 'continuable'; label: string; seq: SessionSeq }
 
 declare module '@deepseek-ai/dsh-session-projection/types' {
   interface SessionProjectionStateMap {
@@ -52,19 +52,19 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 
 - 投影是纯身份，**projection 体系不做失败通道**：unit 永不抛错；载荷损坏、版本不认识与整日志没有描述符一样。host checkpoint 状态使用可序列化的包装 `{ identity?: SubagentIdentityProjection }`，缺席为 `{}`；客户端 view 则是非可选的 `SubagentIdentityProjection | null` 条目。`null` 完好通过 JSON，因此推送 reset 会替换旧身份，而不会被 stringify 丢掉。判定纪律：消费面把 null 与客户端 key 缺席一律视为无值。「算出来没有」如何呈现是消费方自己的事（见下文 `listChildren` 四态映射）。
 - label 强度由描述符 schema 决定：continuable 的 label 解析强制必有，one-shot 的本就可选；mode/label 判别与下文 child 行的强约定完全一致（行不携带 `seq`——它是投影内部的 own-suffix 证明）。
-- 身份携带 `seq`：折出该身份的 `subagent/descriptor` 事件 seq，两臂必有、null 哨兵无——`seq >= header.seedLength ?? 0` 证明身份折叠自 child 自身后缀，而非 fork 种子回放的祖先描述符。unit 把包装状态中校验后的身份映射为客户端 wire view，并与其他 unit 一律检查点化（`persist` 选项已删除）；`stateVersion` 为 2，在增加 `seq` 时升版。更早的 checkpoint 行按 registry 约定版本失配失效、落权威重折。
+- 身份携带品牌化 `seq`：折出该身份的 `subagent/descriptor` 事件 seq，两臂必有、null 哨兵无。live Session 通过 `isOwnSeq()` 检查它；cold 含正文 observation 则与 `inheritedEventCount` 比较。仅 header 的 seeded candidate 会跳过 cache，因为 header 有意不暴露整数 cut；unseeded candidate 知道 cut 为零。unit 把包装状态中校验后的身份映射为客户端 wire view，并与其他 unit 一律检查点化（`persist` 选项已删除）；`stateVersion` 为 2，在增加 `seq` 时升版。更早的 checkpoint 行按 registry 约定版本失配失效、落权威重折。
 - 折叠规则：`subagent/descriptor` last-wins，与 `subagentTiming` 同一条 descriptor-reset 纪律——fork 前缀里的祖先描述符被自身描述符覆盖。损坏或版本不认识的载荷同样 last-wins：重置为 null 哨兵而非保留先前身份，健康祖先的 fork 不会继承自身描述符立不住的身份。
 
-### 枚举：subagent 自管 live-preferred 合并
+### 枚举：query corpus 与 live preference
 
-`listChildren`（[list-children.ts](../../../../packages/subagent/subagent/src/list-children.ts)）的枚举不经任何查询服务：`ctx.sessions.list()` 与 `ctx.get('sessionPersistence')?.list()` 两个来源按 id 合并，live 记录整条覆盖同 id 持久化记录、不做 header 一致性校验。枚举所需全部是 header 事实：
+`listChildren`（[list-children.ts](../../../../packages/subagent/subagent/src/list-children.ts)）通过 `sessionQuery.listSessions()` 取得 canonical live-preferred corpus，再把每个 listed id 与可能存在的 `ctx.sessions.get(id)` 配对；同 id 存在 live Session 时使用 live header。枚举所需全部是 header 事实：
 
 - 过滤：`header.origin === 'subagent' && header.parentSession === parentSessionId`。
 - `hasChildren`：同一份合并材料向下看一层——存在 `origin === 'subagent'` 且 `parentSession` 为该 child 的直接后代。
 - `activity`：live 记录为 `running`，仅存在于持久化的为 `inactive`。
 - 排序：`createdAt` 升序、再按 child id 升序（与旧约定一致）。
-- **persistence 缺席退为 live-only 枚举，不报错**：没有 persistence 的部署，cold child 本就无法 resume，列出 live child 仍然有意义。（对照：旧实现在 sessionQuery 缺失时整体拒绝。）
-- persistence 列表失败使整次枚举失败；per-child 隔离只作用于逐 child 的冷读。
+- `sessionQuery` 服务缺席时以 `SUBAGENT_CONTROL_QUERY_UNAVAILABLE` 失败；共享 query corpus 负责决定部署能枚举 live-only 还是持久化 Session。
+- query corpus 失败使整次枚举失败；per-child 隔离只适用于逐 child cold observation。
 
 ### 取值：三级「算完即止」阶梯
 
@@ -73,20 +73,20 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 | 级 | 读法 | 成本 |
 | --- | --- | --- |
 | 1：live child | `ctx.sessionProjections.snapshot(session, ['subagent'])` | 零日志读——注册表既有水位缓存，同步取值 |
-| 2：cold child，cache 命中 | 可选 `sessionProjectionCache.cachedSnapshot(header, ['subagent'])`，非 null 身份满足 `identity.seq >= header.seedLength ?? 0` 才直接使用——own descriptor 一经追加不可变，seq 门证明该值折叠自 child 自身后缀，无视行水位 | 零日志读 |
-| 3：cold child，兜底 | `persistence.inspect(id)` 整读 + 经注册的 `subagent` unit 折叠 | 每次列表一次整读现算 |
+| 2：unseeded cold child，cache 命中 | 可选 `sessionProjectionCache.cachedSnapshot(header, SessionLogOffset(0), ['subagent'])`；精确 cut 为零时，每个合法 seq 都归 child 自有 | 零日志读 |
+| 3：seeded child 或 cold 兜底 | 一次含正文 `sessionQuery.observeSession(id)` 加已注册的 `subagent` projection，使用 `inheritedEventCount` 做 own-suffix 检查 | 每次列表一次整读现算 |
 
-- 错误约定：`sessionProjections` 是必需注入——`SubagentRuntime` 在 inject 集里声明它，没有 registry 的部署根本无法激活服务（与 loop），`listChildren` 不可达，而不是供出降级行（[mandatory-seam 记录](2026-08-19-session-projection-mandatory-seam.zh.md)）；响亮运行时检查与 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 随之删除。会话存储保留显式姿态：`ctx.get('sessions')`（严格全局读取，不走调用方作用域的属性代理）缺席以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 失败。apiproxy 为 `PROJECTIONS_UNAVAILABLE` 设的专门 wire 脸随码删除；`SESSION_STORE_UNAVAILABLE` 走通用 internal 兜底——apiproxy 组合自身就 inject `sessions`，该错误在其部署不可达，专门映射违反 need 原则。`SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 已随 session-query 依赖删除。
-- cache 是纯可选加速层：服务缺席判空跳过——无错误码、不进配置校验（与 `sessionProjections` 的必需注入相对）。第二级任何抛错（包括缓存内任一 unit 行中毒使 `viewCheckpoint` 引爆）静默落第三级——缓存是派生数据，其故障不产生 `corrupt` 判决，终审归权威重折；checkpoint 切面早于描述符的行，`subagent` key 天然缺席，自动落底，无特判；行里的 null 哨兵同样不作数——一律落第三级，由权威重折裁决。创建窗口内的 count/interval checkpoint 可能把 fork 种子回放的祖先身份落进行——祖先 seq 落在 seed 区间，被 seq 门拒绝，同样落第三级裁决。
+- 错误约定：`sessionProjections`、Session store 与 `sessionQuery` 都是 listing 所需的 runtime service。三者分别以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 与 `SUBAGENT_CONTROL_QUERY_UNAVAILABLE` 显式失败；缺失分类或 corpus 能力不会伪装成空结果。
+- cache 是纯可选加速层：服务缺席判空跳过——无错误码、不进配置校验（与 `sessionProjections` 的必需注入相对）。seeded header 会跳过该级，因为不读取正文就无法提供 cache identity 所需的精确 cut。对 unseeded child，第二级任何抛错（包括中毒 unit 行引爆 `viewCheckpoint`）都会静默落第三级——缓存是派生数据，其故障不产生 `corrupt` 判决，终审归权威重折；checkpoint 早于 descriptor、key 缺席或 null 哨兵也都会落底。
 - per-child 隔离：单 child 的 cold 整读失败只使该行成为 `unavailable` diagnostic，下次列表自然重试，不影响 sibling（见四态映射）。
-- 冷路径的生命周期见证：preparation 的结果必须仍指向枚举时的那个生命周期——见证字段集与旧 SOURCE_CONFLICT 检查同款七字段（version、id、createdAt、cwd、parentSession、seedLength、delegationDepth）；同 id 删除后重新发布的会话对旧 parent 的目录降级为 `corrupt` 行，不外漏新 owner 的 child。
+- 冷路径的生命周期见证：observation 必须仍指向枚举时的那个生命周期。见证字段为 version、id、createdAt、cwd、parentSession、isSeeded、delegationDepth、origin 与 agentPreset；同 id 删除后重新发布的 Session 对旧 parent 的目录降级为 `corrupt` 行，不外漏新 owner 的 child。
 - 冷读并发以常数 4 有界——它约束的是本地介质的一次只读扫描而非部署行为；出现联网 persistence backend 时提升为验证过的 `Config` 字段。
-- 冷读成本如实记录：cache 未挂载或未命中时，cold child 每次列表才付一次整读，成本与其 transcript 大小成正比；定案「算完即止」，不自建缓存。整读经 `inspect()` 走 [Session 准备阶段](2026-08-05-session-preparation.zh.md)的冷读，同 id 短期重复读取可命中其 LRU 复用，但列表不依赖此。live child 全程零日志读。
+- 冷读成本如实记录：每个 seeded child 与每次 unseeded cache miss 都会在每次列表时支付一次完整 query observation，成本与其 transcript 大小成正比；定案「算完即止」，不自建缓存。observation 可以复用 query／persistence preparation 层，但列表不依赖该优化。live child 全程零日志读。
 - 取消：每次 persistence 读前后检查调用方 signal，abort 之后才结算的读拒绝归一化为稳定错误码 `CANCELLED`。
 
 ### 权威模型
 
-- session log 是唯一权威；本方案不新增任何派生持久化——没有索引值、没有自己的 checkpoint、没有进程 memo；第二级读取的 `sessionProjectionCache` checkpoint 是既有组合项的派生数据，本方案只读不写。取值现算现弃，值的新鲜度就是读取时点的 live 状态或持久化 revision（own descriptor 一经追加不可变——缓存身份过 seq 门后无陈旧性问题，门防的是种子回放的祖先身份）。
+- session log 是唯一权威；本方案不新增领域索引、自有 checkpoint 或进程 memo。第二级读取的 `sessionProjectionCache` checkpoint 是既有组合项的派生数据，列表只读。取值现算现弃；seeded candidate 用含正文 observation 按精确 cut 分类，unseeded cached identity 无需 seq 门，因为每个合法 seq 都归自身所有。
 - Session 与 persistence 写路完全不感知列表与投影消费：没有事件监听回写，没有写时折叠。
 - 枚举与取值不构成第二个鉴权来源，也不让尚未发布的 child 可见——两个来源只见已发布的 live 记录与已落盘的持久化记录，与 durable-subagent-catalog 记录对派生读面立下的规则一致。
 
@@ -127,25 +127,24 @@ export type SubagentListEntry =
 
 已知边界偏差（有意接受，随本记录留档）：
 
-- 死于发布窗口的 fork child，seed 里若有祖先描述符，last-wins 会给出祖先身份，误现为 child 行；恢复仍按 own-suffix 折叠权威失败（`NOT_RESUMABLE`）。旧实现靠 `seedLength` 过滤将其 omit；projection unit 看不到 header，接受此残骸级偏差（`subagentTiming` 有同类既有暴露）。
 - own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（提供方约定本就保证恰一）。
 - live/persisted header 冲突，旧实现是 per-child corrupt；现枚举 live 优先、不做一致性校验，冲突不再被察觉，以 live 记录成行。
 - 损坏存储的源读失败（如坏 surface 被冷读整读拒收），旧实现映射 per-child `corrupt`，现统一成 `unavailable` 行（读侧无从区分成因）。
 - 未知 parent，旧实现经 session-query 抛 not-found（「parent session … was not found」）；现自管合并对不存在的 parent 得到空子集，枚举返回空列表，wire 上后续操作落到 child 级 subagent-not-found——语义与文案的静默变化，显式接受。
-- rung 2 的更晚事件窗口：cache 行恰在首个自有描述符之后落盘，日志随后追加第二个自有描述符（或 malformed 载荷置 null 哨兵），且进程在下一次 checkpoint 前崩溃——此后冷列表的 rung 2 凭 seq≥seedLength 门持续供出行内旧身份（第一个自有描述符的值），与权威重折（last-wins 第二个）分歧，且 rung 2 命中期间不触发重折、无从察觉。边界三条：①前提是同一 child 出现第二个自有描述符，违反建档提供方「恰追加一次」约定，属损坏类数据，与多描述符偏差同族同源；②需「损坏 + 崩溃错过 checkpoint（turn/end 与 disposal 两个 mandatory 点及 count/interval 节流点全部未及）」双条件同时成立；③健康 child（恰一自有描述符）不受影响——seq 门放行的正是唯一真身份。自愈条件：该 child 任一次 live 运行（turn/end mandatory checkpoint）或任何触发 cache.write 的时点，都会以新 fold 整行覆写（whole-record replace），rung 2 随即供正；权威路径（rung 3 重折、live snapshot、resume 折叠）自始正确，分歧只存在于持续冷、行未再更新期间的列表读。机制修法不采：gate 对账需知日志末端 seq，冷路径零读不可得；cache 行携 revision 是 opaque token，无法比较且跨域改 schema——按「cache 永不为权威」总纲归档为接受项。
+- rung 2 的更晚事件窗口只适用于 unseeded child：cache 行恰在首个 descriptor 后落盘，日志随后追加第二个 descriptor（或 malformed 载荷置 null 哨兵），且进程在下一次 checkpoint 前崩溃。cold listing 可能持续供出旧身份，直到一次 live 运行或 cache write 替换该行。其前提违反 provider 的「恰追加一次」约定，并且还需错过所有 mandatory checkpoint；健康 child 不受影响。seeded child 没有 body-owned cut 时绝不进入 rung 2。
 
-消费面：wire、tool、GUI 的 diagnostic 处理**全部保持原状零改动**（`list_agents` 的 description 与 output schema 未动；该插件的加载要求变化——inject 去掉 `sessionQuery`、新增必需注入 `sessionProjections`）。行为上动的只有 apiproxy：路由段的 `hasSubagentDescriptor()` 扫描已删除，`hasSubagentOwner` 只看 `header.origin`——pre-#1569 的无 `origin` 存量不再被认作 subagent 属主，其本就不进目录，pre-release 立场接受；`subagents.history` 与 `session.history` 同源对齐——live child 用内存事件与注册表水位快照，cold child 用 `inspectServable` 直读持久化并 detached 折叠，不经查询服务，SESSION_QUERY_* 错误臂随之退役，wire 形状不变（`history` 的 JSDoc 措辞改为 live 内存快照／cold 持久日志双臂）。
+消费面保持相同的 row 与 diagnostic wire 形状。`list_agents` 使用必需的 query corpus 与 projection registry；live identity 来自 registry snapshot，cold identity 来自 cache 或 query observation。Host ownership 仍使用 `header.origin`，history 使用共享的 live／cold Session query source；没有消费方独立解析 descriptor event。
 
 ### 改动落点
 
 | 区域 | 文件 | 改动 |
 | --- | --- | --- |
 | subagent | projection.ts、projection-types.ts、index.ts | 新客户端可见 `subagent` unit 与注册 |
-| subagent | list-children.ts 及类型 | 重写为自管枚举 + 投影阶梯四态映射；删 session-query 依赖、逐 child 事件读取与就地分类机器；错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 删除，`sessionProjections` 转为必需注入（不再存在投影错误码）；新增可选依赖 dsh-session-projection-cache（纯加速读取，缺席跳过） |
-| host/apiproxy | api-proxy.ts | 删 `hasSubagentDescriptor`，属主判定只看 `header.origin`；`subagents.history` 与 `session.history` 同源——live 用内存事件与注册表水位快照，cold 用 `inspectServable` 直读持久化并 detached 折叠，不经查询服务，SESSION_QUERY_* 错误臂与 `PROJECTIONS_UNAVAILABLE` 专门 wire 脸随之退役 |
-| tool | tool-subagent-control/list-agents.ts | 加载要求收窄（inject 去 `sessionQuery`）；model-visible schema、描述与渲染零改动 |
+| subagent | list-children.ts 及类型 | query-corpus 枚举加 projection 阶梯四态映射；必需 projections／query service 与可选 projection-cache 加速 |
+| host/apiproxy | Session controller／query integration | owner 检查使用 `header.origin`；live／cold history 与 listing 消费共享 query 和 projection source |
+| tool | tool-subagent-control/list-agents.ts | model-visible schema、描述与渲染保持不变 |
 | wire/client | api/subagents.ts、runtime sessions/service.ts、GUI | 类型、行形状与 diagnostic 处理**零改动**；api/subagents.ts 仅 `history` 的 JSDoc 措辞改为双臂 |
-| core/session、session-persistence、session-projection(-cache)、session-query(-sqlite) | — | **零改动** |
+| core/session、session-persistence、session-projection(-cache)、session-query(-sqlite) | 含正文 cut 与品牌化 seq 传递 | Logical header 暴露 `isSeeded`；Session、persistence observation、cache identity 与 query record 单独携带精确 `inheritedEventCount` |
 
 ## 考虑过的替代方案
 
@@ -169,20 +168,20 @@ export type SubagentListEntry =
 
 ## 验证
 
-`packages/subagent/subagent/tests/list-children.spec.ts` 重写为本约定：无 persistence、query 服务与继续运行时的 live-only 列表；registry 缺席时服务根本不激活（mandatory seam——`setup` 变体断言 `ctx.get('subagents')` 保持 undefined）；live child 全程零 `inspect`、cold child 每次列表恰一次；多描述符 last-wins 取末者；损坏载荷与未知版本折为 `corrupt`；冷读失败映射 `unavailable` 且下次列表重试；fork seed 里的祖先描述符按该身份成行（偏差一钉住）；普通 fork 与无 subagent origin 的后代不入列也不计入 `hasChildren`；`createdAt`→id 排序；提供方未挂载不影响列表；压缩与未压缩孪生一致；预中止、持久化列表与冷读取消三例归一 `CANCELLED`；空列表与稳定错误码（存储缺席时 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）。第二级例：own-seq 身份直用零 `inspect`、fork 种子祖先身份（seq 落在 seed 区间）被门拒绝落底、行内无身份（null 哨兵或 key 缺席）落底、cache 服务缺席落底、缓存行中毒静默落底重折；冷路径 lifecycle 篡改按见证七字段逐一（`it.each`）降级为 `corrupt`。`tool-subagent-control` 的 list-agents 测试随加载要求收窄更新；`optional-session-query.spec.ts` 随依赖消失删除；既有无密钥快照（`subagent-list-agents` 等）零变化，钉住健康路径的 wire 与 model-visible 面不变；新增无密钥快照 `subagent-diagnostic`（examples/headless-agent）钉住四态映射的诊断分类——descriptor-less 定局残骸成 `corrupt` 行等模型可见变化。
+`packages/subagent/subagent/tests/list-children.spec.ts` 固定本约定：live identity 通过 `Session.isOwnSeq()` 检查；unseeded cold identity 可在 cut 零时使用 cache；seeded candidate 跳过该 cache rung，转而使用携带 `inheritedEventCount` 的 observation；祖先 identity 无法通过 own-suffix 检查；缺席、null、中毒与不可用的 cache／observation 会按约定落底或产生 diagnostic；lifecycle 篡改按完整见证字段集降级为 `corrupt`。既有无密钥快照保持健康 wire 与 model-visible 面不变，`subagent-diagnostic` 则固定诊断分类。
 
 ## 后果
 
 - live child 的列表全程零日志读；cold child 在 cache 未挂载或未命中时每次列表一次 `inspect` 整读，成本与其 transcript 大小成正比、随列表频率重复——定案「算完即止」，不自建缓存、不回写，同 id 短期重复整读可命中准备阶段 LRU 但列表不依赖它。
-- subagent 列表不再要求 query backend：纯 live 与无 persistence 的部署都能列表；`SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 消失，`list_agents` 插件加载不再要求 `sessionQuery`，而 `sessionProjections` 转为 `SubagentRuntime` 的必需注入——没有投影 registry 的部署根本不会激活服务（mandatory seam）。
+- subagent 列表要求 Session query corpus 与 projection registry；服务缺失会显式失败，而不是供出不完整 row。可选 projection cache 只改变正文读取次数。
 - 身份解释只存在于 registry 注册的一份 unit：列表三级阶梯与 GUI history 冷读使用其 live、cached 或 observed wire 快照，不存在手写旁路折叠；若未来某消费面绕开该 unit 手写折叠，各读面的值将漂移——这是本设计要求维持的纪律，不是机制保证。
 - per-child 隔离回归：单 child 冷读失败只损失该行，healthy sibling 不受影响；persistence 列表失败仍使整次枚举失败。
-- 诊断与枚举语义留下六处边界偏差（stillborn fork 祖先身份误现、多描述符取末者、header 冲突不再被察觉、损坏源读失败由 `corrupt` 转 `unavailable`、未知 parent 由 not-found 改为空列表、rung 2 更晚事件窗口），完整语义见已知边界偏差清单；前四处为残骸级数据的展示或分类偏差，未知 parent 一处是查询语义的静默变化，rung 2 窗口一处是损坏加崩溃双条件下可自愈的缓存供值分歧；恢复鉴权均不受影响，显式接受。
+- 诊断与枚举语义留下五处边界偏差（多描述符取末者、header 冲突不再被察觉、损坏源读失败改变分类、未知 parent 由 not-found 改为空列表、unseeded rung 2 更晚事件窗口）。seeded 祖先 identity 已不再构成偏差，因为含正文读取会把它与 `inheritedEventCount` 比较；恢复鉴权始终不受影响。
 - pre-#1569 的无 `origin` 存量不再被认作 subagent 属主；其本就不进目录，pre-release 无兼容承诺。
 
 ## 相关
 
-- [durable-subagent-catalog 与 list_agents](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md)——被本记录部分取代：描述符仍是 mode/label 的持久权威与折叠输入，列表的枚举与取值改为自管合并加投影阶梯。
+- [durable-subagent-catalog 与 list_agents](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md)——被本记录部分取代：描述符仍是 mode/label 的持久权威与折叠输入，取值改为共享 query corpus 上的 projection 阶梯。
 - [session projections 与命令生命周期日志](../../proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md)——registry 约定的权威；本记录为其新增 `subagent` 身份 unit，并消费其 live 与 cold wire 快照。
 - [session projection 状态与客户端视图](2026-08-19-session-projection-state-and-client-views.zh.md)——state/client 拆分；`subagent` 与 `subagentTiming` 都提供客户端 wire view。
 - [session projections 作为必需接缝](2026-08-19-session-projection-mandatory-seam.zh.md)——`sessionProjections` 转为必需注入；列表的错误约定随其变化（registry 缺席是激活期失败，投影错误码删除）。
diff --git a/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.i18n.yaml
new file mode 100644
index 0000000000..06883b0ef8
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.md
+2026-08-31-session-sequence-and-log-offset-brands.md: 0057b2b6c95391abbb4ec2464ee58b54e2fe24f2
+2026-08-31-session-sequence-and-log-offset-brands.zh.md: f51ad5953cab34294a53db6e3c91884292497faf
diff --git a/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.md b/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.md
new file mode 100644
index 0000000000..0057b2b6c9
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.md
@@ -0,0 +1,45 @@
+# Agent Note: Distinguish Session event identities from log offsets
+
+Status: implemented
+
+English | [中文](2026-08-31-session-sequence-and-log-offset-brands.zh.md)
+
+## Problem
+
+Session positions used one structural `number` type for two incompatible meanings. An event reference names an existing row, while a prefix length, next append position, or read cut names a gap and may equal the event count. The compiler therefore accepted an offset where an event identity was required and could not expose a missed sequence-field migration.
+
+`SessionHeader.seedLength` also mixed a v0 storage coordinate into metadata used by body-free readers. Listing needs to know whether a Session has fork lineage, but only a reader that holds the event body can interpret the exact inherited prefix length.
+
+## Decision
+
+`@deepseek-ai/dsh-brand` exports the erased numeric primitive `BrandedNumber<B>` and the runtime-identity helper `brandNumber()`. `@deepseek-ai/dsh-session` owns two validated brands: `SessionSeq` names one existing event and `SessionLogOffset` names a log gap, prefix length, or read offset. `SessionSeqCursor = SessionSeq | -1` represents an inclusive watermark before or after the first event, and `OptionalSessionSeq = SessionSeq | null` represents an event identity whose absence is data.
+
+`SessionEvent.seq`, surface replacement endpoints, provenance, and owner payload fields that identify Session events use `SessionSeq`. `Session.seq`, `Session.firstLiveSeq`, `Session.inheritedEventCount`, body-read offsets, and inherited prefix cuts use `SessionLogOffset`. Arithmetic returns an ordinary number and re-enters either domain through its validating constructor.
+
+The logical `SessionHeader` carries `isSeeded: boolean` and no numeric seed cut. Body-bearing storage values and observations carry `inheritedEventCount` beside the header; `Session.ownEvents()` and `Session.isOwnSeq()` hide the comparison from ordinary consumers. A seeded constructor requires an explicit seed and exact cut, including an empty seed with cut zero, because constructor input may contain child-owned setup events after the inherited prefix.
+
+The v0 JSONL header remains byte-compatible: absent `seedLength` decodes to `isSeeded: false` with cut zero, while present zero or nonzero values decode to `isSeeded: true` with the exact cut. Header-only listing translates only the presence bit. API, SDK, DeepSeek, telemetry, query-row, and JSON representations continue to carry ordinary numbers; their owning adapters validate and brand values when they enter same-process domain code.
+
+## Admission and ownership
+
+Domain constructors reject negative, fractional, non-finite, and unsafe integer values. Parsers validate a raw number once and retain the parsed object where the brand does not require a runtime wrapper. A compile-time brand does not discover unknown numeric fields in an external event; a format migration still needs an exhaustive owner disposition and must refuse schemas it cannot safely rewrite.
+
+`session/end-seed` remains a lifecycle marker, not the source of the inherited cut. Every constructor restore appends or retains that marker, including unseeded replay, so projections and cold readers receive `inheritedEventCount` explicitly instead of scanning the log.
+
+## Alternatives considered
+
+**Keep every position as `number`.** Rejected because event identities, counts, and cursors cross package and persistence seams frequently enough that accidental interchange is a migration risk, not a local arithmetic convenience.
+
+**Use one branded Session position for identities and offsets.** Rejected because it would again permit `eventCount` or `fromSeq` where an existing event is required and would force the `-1` and `null` sentinels into unrelated operations.
+
+**Derive the inherited cut from `session/end-seed`.** Rejected because the marker records constructor lifecycle, not only fork lineage, and a constructor seed may contain child-owned events after the inherited prefix.
+
+## Consequences
+
+Sequence-bearing code now states whether a number identifies an event or a gap. Header-only readers receive stable lineage metadata without opening the body, while persistence, projection, query, and authorization paths retain the exact cut they need. The on-disk v0 format and public numeric wires do not change.
+
+The cost is explicit conversion at durable and wire parsers and a separate exact-cut field on body-bearing observations. Projection-cache identity includes the lineage bit and exact cut, so its disposable storage domain advances and older rows rebuild on demand; body-free readers skip seeded cache hints when they do not hold the cut. Turn numbers, step numbers, message-list indexes, workflow member ordinals, token counts, and unrelated numeric domains remain plain numbers because they do not identify Session events.
+
+## Testing
+
+Type assertions pin that `SessionSeq` and `SessionLogOffset` are not interchangeable. Runtime suites cover constructor validation, mixed inherited and child-owned seeds, empty seeds, `ownEvents()` and `isOwnSeq()`, v0 JSONL absent/zero/nonzero headers in plain and Zstandard encodings, header-only listing, cold prepare and reopen, query and projection cuts, and unchanged numeric wire values.
diff --git a/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.zh.md b/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.zh.md
new file mode 100644
index 0000000000..f51ad5953c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.zh.md
@@ -0,0 +1,45 @@
+# Agent Note: 区分 Session 事件身份与日志偏移
+
+Status: implemented
+
+[English](2026-08-31-session-sequence-and-log-offset-brands.md) | 中文
+
+## Problem
+
+Session 位置曾用同一个结构化 `number` 类型表达两种不兼容的含义。事件引用指向一条已存在的记录，而前缀长度、下一追加位置或读取切点指向记录间隙，并且可以等于事件总数。因此，编译器会在需要事件身份的位置接受偏移，也无法暴露迁移时漏改的序号字段。
+
+`SessionHeader.seedLength` 还把 v0 存储坐标混入了无须读取正文的 metadata consumer。列表只需要知道 Session 是否有 fork lineage，只有同时持有事件正文的读取方才能解释精确的继承前缀长度。
+
+## Decision
+
+`@deepseek-ai/dsh-brand` 导出编译后消失的数值原语 `BrandedNumber<B>` 与运行时保持原值的 helper `brandNumber()`。`@deepseek-ai/dsh-session` 拥有两个经验证的 brand：`SessionSeq` 指明一条已存在事件，`SessionLogOffset` 指明日志间隙、前缀长度或读取偏移。`SessionSeqCursor = SessionSeq | -1` 表达首条事件之前或之后的闭区间 watermark，`OptionalSessionSeq = SessionSeq | null` 表达允许以缺失为数据的事件身份。
+
+`SessionEvent.seq`、surface 替换端点、provenance 以及 owner payload 中指向 Session 事件的字段使用 `SessionSeq`。`Session.seq`、`Session.firstLiveSeq`、`Session.inheritedEventCount`、带正文读取的偏移与继承前缀切点使用 `SessionLogOffset`。算术结果恢复为普通 number，并通过对应的验证构造函数重新进入任一领域。
+
+逻辑 `SessionHeader` 携带 `isSeeded: boolean`，不携带数值 seed cut。包含正文的存储值和 observation 在 header 旁携带 `inheritedEventCount`；`Session.ownEvents()` 与 `Session.isOwnSeq()` 向普通 consumer 隐藏比较。seeded constructor 必须显式提供 seed 与精确 cut，包括 cut 为零的空 seed，因为 constructor 输入可能在继承前缀之后还包含 child-owned setup event。
+
+v0 JSONL header 保持字节兼容：缺少 `seedLength` 时解码为 `isSeeded: false` 和零 cut，存在零或非零值时解码为 `isSeeded: true` 和对应精确 cut。仅 header 的 listing 只转换字段是否存在。API、SDK、DeepSeek、telemetry、query row 与 JSON 表示继续携带普通 number；由它们各自的 adapter 在值进入同进程 domain code 时完成验证与 brand。
+
+## Admission and ownership
+
+Domain constructor 拒绝负数、小数、非有限值与非安全整数。parser 验证原始 number 一次；brand 不需要运行时 wrapper 时，保留原解析对象。编译期 brand 无法发现外部事件里的未知数值字段；格式迁移仍须获得穷尽的 owner disposition，并拒绝无法安全改写的 schema。
+
+`session/end-seed` 仍是 lifecycle marker，不是继承 cut 的来源。每次 constructor restore 都会追加或保留该 marker，unseeded replay 也一样，因此 projection 与 cold reader 会显式接收 `inheritedEventCount`，而不是扫描日志。
+
+## Alternatives considered
+
+**继续让所有位置都使用 `number`。** 拒绝，因为事件身份、计数与 cursor 已频繁跨越 package 与 persistence seam，意外混用是迁移风险，而不是局部算术便利。
+
+**用同一个 branded Session position 表达身份和偏移。** 拒绝，因为这样仍会在需要已存在事件的位置接受 `eventCount` 或 `fromSeq`，还会迫使 `-1` 与 `null` sentinel 进入互不相关的操作。
+
+**从 `session/end-seed` 推导继承 cut。** 拒绝，因为该 marker 记录 constructor lifecycle，并不只记录 fork lineage，而且 constructor seed 可以在继承前缀之后包含 child-owned event。
+
+## Consequences
+
+携带序号的代码会明确说明一个 number 指向事件还是间隙。仅 header 的 reader 无须打开正文即可取得稳定 lineage metadata，persistence、projection、query 与 authorization path 则保留所需的精确 cut。磁盘 v0 格式与公共数值 wire 不变。
+
+代价是在 durable 与 wire parser 处显式转换，并让含正文 observation 携带独立的精确 cut 字段。Projection cache identity 包含 lineage bit 与精确 cut，因此其可丢弃的 storage domain 会推进，旧 row 按需重建；不持有 cut 的仅 header reader 会跳过 seeded cache hint。turn number、step number、message-list index、workflow member ordinal、token count 与无关数值领域保持普通 number，因为它们不指向 Session 事件。
+
+## Testing
+
+类型断言钉住 `SessionSeq` 与 `SessionLogOffset` 不可互换。运行时 suite 覆盖 constructor 验证、混合继承与 child-owned seed、空 seed、`ownEvents()` 与 `isOwnSeq()`、plain 与 Zstandard 编码中的 v0 JSONL 缺失/零/非零 header、仅 header 的 listing、cold prepare 与 reopen、query 和 projection cut，以及不变的数值 wire 值。
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
index d121a5db15..fc258a1609 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.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 .agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
-2026-06-30-session-store-fork-api.md: ff7617f4bb306926a7b0782751ae82f6ef0c6371
-2026-06-30-session-store-fork-api.zh.md: ecef7ba2985321677b29d3fc7692a8dcb7afb2b6
+2026-06-30-session-store-fork-api.md: a2d169a36a8a0b624abef98377d644d713e5d64c
+2026-06-30-session-store-fork-api.zh.md: 5ebf05e677f2d3676f860220b1cf9ff960565402
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
index ff7617f4bb..a2d169a36a 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
@@ -20,11 +20,11 @@ The store exposes one operation:
 type SessionForkSource = Session | SessionId
 
 class SessionStore extends Service {
-  fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+  fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session
 }
 ```
 
-`boundary` is the inclusive source event `seq` to copy through. When omitted, it defaults to the source session's current last event; on an empty source, omitted `boundary` creates an empty child. Fork-specific validation checks that the requested boundary exists and that the selected prefix's latest turn boundary is not an unmatched `turn/start`. The selected prefix may therefore end at `turn/end` or at a later standalone event, then is deep-cloned into the child seed. The child inherits the source session's `cwd`, stamps `parentSession` to the source id, and sets `seedLength` to the copied prefix length. When `childSessionId` is omitted, `SessionStore` generates one using its existing id policy.
+`boundary` is the branded inclusive source event `seq` to copy through. When omitted, it defaults to the source session's current last event; on an empty source, omitted `boundary` creates an empty child. Fork-specific validation checks that the requested boundary exists and that the selected prefix's latest turn boundary is not an unmatched `turn/start`. The selected prefix may therefore end at `turn/end` or at a later standalone event, then is deep-cloned into the child seed. The child inherits the source session's `cwd`, stamps `parentSession` to the source id, sets logical `isSeeded: true`, and supplies the copied prefix length separately as `inheritedEventCount`. When `childSessionId` is omitted, `SessionStore` generates one using its existing id policy.
 
 An empty prefix is forkable; any non-empty boundary must be a safe existing sequence outside an open turn. Typed errors distinguish missing sources, stale objects, duplicate child ids, invalid boundaries, and prefixes ending during execution. Broader log validation and crash repair remain with their existing owners.
 
@@ -44,6 +44,6 @@ The Host creates the child through the agent registry with the selected seed and
 
 ## Consequences
 
-The public API stays small and discoverable: live session branching is part of `ctx.sessions`, next to `create({ seed })`, rather than a standalone service or a two-step helper pair. Persistence continues to work through existing `session/created` and `session/flush` behavior: a forked child starts life with seeded events, so existing backends persist that seed once and preserve `parentSession` / `seedLength` in the header.
+The public API stays small and discoverable: live session branching is part of `ctx.sessions`, next to `create({ seed })`, rather than a standalone service or a two-step helper pair. Persistence continues to work through existing `session/created` and `session/flush` behavior: a forked child starts life with seeded events, so the JSONL backend persists that seed once and preserves logical `parentSession` / `isSeeded` plus the separate exact cut (encoded as v0 physical `seedLength`).
 
 This decision excludes ACP `session/fork`, unloaded persisted-session forking, model-facing tools, and subagent refactors. If a future ACP method is added, it should advertise the capability only after it has protocol and snapshot coverage; this Agent Note adds no ACP wire behavior, so no ACP snapshot is required. Fork-child replay remains covered by the existing [seed-boundary testing Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md); focused store, Host, carrier, and client tests pin the boundary and reconciliation contracts, while the real Chromium scenario pins the assembled message action and lineage tree.
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
index ecef7ba298..5ebf05e677 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
@@ -20,11 +20,11 @@ store 暴露一个操作：
 type SessionForkSource = Session | SessionId
 
 class SessionStore extends Service {
-  fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+  fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session
 }
 ```
 
-`boundary` 是要复制到的源事件 `seq`（含该序号）。省略时默认为源会话当前的最后一个事件；对空源会话省略 `boundary` 则创建一个空的子会话。fork 特有的校验会检查请求的边界存在，并确认所选前缀最近的轮次边界不是未匹配的 `turn/start`。因此，所选前缀可以结束于 `turn/end` 或更晚的独立事件，随后被深拷贝到子会话的种子中。子会话继承源会话的 `cwd`，将 `parentSession` 设为源会话 id，并将 `seedLength` 设为已复制前缀的长度。省略 `childSessionId` 时，`SessionStore` 使用其现有的 id 策略生成一个。
+`boundary` 是要复制到的品牌化源事件 `seq`（含该序号）。省略时默认为源会话当前的最后一个事件；对空源会话省略 `boundary` 则创建一个空的子会话。fork 特有的校验会检查请求的边界存在，并确认所选前缀最近的轮次边界不是未匹配的 `turn/start`。因此，所选前缀可以结束于 `turn/end` 或更晚的独立事件，随后被深拷贝到子会话的种子中。子会话继承源会话的 `cwd`，将 `parentSession` 设为源会话 id，设置 logical `isSeeded: true`，并把复制前缀的长度单独作为 `inheritedEventCount` 传入。省略 `childSessionId` 时，`SessionStore` 使用其现有的 id 策略生成一个。
 
 空前缀可以被 fork；任何非空边界都必须是位于开放轮次之外且安全、已存在的序号。类型化的错误区分源缺失、对象陈旧、子 id 重复、边界无效和前缀结束于执行过程中等情况。更广泛的日志校验与崩溃恢复仍由其现有的负责方处理。
 
@@ -44,6 +44,6 @@ Host 通过 agent（智能体）注册表，以选定的种子和谱系创建子
 
 ## 后果
 
-公开 API 保持精简且易于发现：活跃会话分支是 `ctx.sessions` 的一部分，紧邻 `create({ seed })`，而非一个独立服务或一对两步辅助函数。持久化继续通过现有的 `session/created` 和 `session/flush` 行为运作：fork 出的子会话创建时便带有种子事件，因此现有后端只需持久化该种子一次，并在 header 中保存 `parentSession`／`seedLength`。
+公开 API 保持精简且易于发现：活跃会话分支是 `ctx.sessions` 的一部分，紧邻 `create({ seed })`，而非一个独立服务或一对两步辅助函数。持久化继续通过现有的 `session/created` 和 `session/flush` 行为运作：fork 出的子会话创建时便带有种子事件，因此 JSONL 后端只需持久化该种子一次，并保留 logical `parentSession`／`isSeeded` 与单独的精确 cut（编码为 v0 物理 `seedLength`）。
 
 本决策排除 ACP（Agent Client Protocol）`session/fork`、对未加载的已持久化会话执行 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备协议与快照覆盖后才声明支持该能力；本 Agent Note 不添加任何 ACP 协议行为，因此不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.zh.md)覆盖；store、Host、载体与客户端的专项测试固定边界和对账约定，真实 Chromium 场景则固定组装后的消息操作与谱系树。
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index 57581fa295..2bd3567191 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.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 .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
-2026-07-21-continuable-background-subagents.md: e1adf8efa19cce8e0632170886770b8d12bc9e3d
-2026-07-21-continuable-background-subagents.zh.md: f62c314320a1dace43f3028b68a1bb7d65203e84
+2026-07-21-continuable-background-subagents.md: 24ab64879fa18f5de9952af2dba321e2cae17477
+2026-07-21-continuable-background-subagents.zh.md: 0cf06f7fe30d0953bb6e7f1a4c96527fa181805a
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
index e1adf8efa1..24ab64879f 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
@@ -71,9 +71,9 @@ Human input uses the same `followup` operation. The UI may display the child tra
 
 ### Durable child handle and cold resume
 
-The continuation manager snapshots every descriptor input with the seam's `snapshotSubagentDescriptor()` (built on [`snapshotJsonValue`](../../../../packages/util/values/src/index.ts)) before Task creation, matching the detached lossless-JSON boundary already used by Agent messages. A child-scoped setup contribution — a prepended one-shot `agent/prompt-submit` listener installed by the in-process driver — appends one model-hidden `subagent/descriptor` event before downstream prompt admission can block or throw. Allowed admission opens the initial child turn afterward; rejected admission leaves the descriptor as a pre-turn log-only fact, and the activation's final required checkpoint persists it. The event carries no `surfaceOp`, remains outside model history, and survives when compaction replaces surface history. A known child id is resumable only when loading that child session yields a supported descriptor in the child's own suffix (after `seedLength`, so a fork seed cannot leak an ancestor's descriptor) and its header identifies the caller as the direct parent.
+The continuation manager snapshots every descriptor input with the seam's `snapshotSubagentDescriptor()` (built on [`snapshotJsonValue`](../../../../packages/util/values/src/index.ts)) before Task creation, matching the detached lossless-JSON boundary already used by Agent messages. A child-scoped setup contribution — a prepended one-shot `agent/prompt-submit` listener installed by the in-process driver — appends one model-hidden `subagent/descriptor` event before downstream prompt admission can block or throw. Allowed admission opens the initial child turn afterward; rejected admission leaves the descriptor as a pre-turn log-only fact, and the activation's final required checkpoint persists it. The event carries no `surfaceOp`, remains outside model history, and survives when compaction replaces surface history. A known child id is resumable only when loading that child session yields a supported descriptor at or after its exact `inheritedEventCount`, so a fork seed cannot leak an ancestor's descriptor, and its header identifies the caller as the direct parent.
 
-The continuable arm of the versioned descriptor (`SUBAGENT_DESCRIPTOR_VERSION` in [descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts)) carries `mode: 'continuable'`, the subagent provider name, resolved child `agentOptions.provider` and `agentOptions.model`, and optional `persona` and `toolFilter`. It does not snapshot the merge-extensible `AgentOptions` object: unrelated extension values cannot make continuation fail merely because they are not JSON. It deliberately omits `subagentDepth`; cold resume relies on the persisted header's `delegationDepth` rather than reconstructing depth from the descriptor. `outputSchema` belongs to one activation's result contract rather than durable child composition. The child header remains authoritative for the child id, `cwd`, `parentSession`, `seedLength`, and `delegationDepth`, while the persisted child transcript owns the fork seed and subsequent history. [`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) takes the maximum of header and runtime values, so reconstructed runtime options may deepen the persisted value but never lower it and a resumed child cannot regain a top-level delegation budget.
+The continuable arm of the versioned descriptor (`SUBAGENT_DESCRIPTOR_VERSION` in [descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts)) carries `mode: 'continuable'`, the subagent provider name, resolved child `agentOptions.provider` and `agentOptions.model`, and optional `persona` and `toolFilter`. It does not snapshot the merge-extensible `AgentOptions` object: unrelated extension values cannot make continuation fail merely because they are not JSON. It deliberately omits `subagentDepth`; cold resume relies on the persisted header's `delegationDepth` rather than reconstructing depth from the descriptor. `outputSchema` belongs to one activation's result contract rather than durable child composition. The child header remains authoritative for the child id, `cwd`, `parentSession`, `isSeeded`, and `delegationDepth`; body-bearing persistence metadata owns the exact `inheritedEventCount`, while the child transcript owns the fork seed and subsequent history. [`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) takes the maximum of header and runtime values, so reconstructed runtime options may deepen the persisted value but never lower it and a resumed child cannot regain a top-level delegation budget.
 
 Cold resume cannot depend on an optional method of `SubagentRun`, because that run has been disposed and is not retained across process restart. A run represents one disposable activation and exposes only activation-scoped operations. `SubagentRun.steer?()` names the confirmed live-only capability so it cannot be confused with service orchestration or the model-facing tool.
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index f62c314320..0cf06f7fe3 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -71,9 +71,9 @@ durable child Session
 
 ### 持久化 child handle 与从持久化存储恢复
 
-继续执行管理器在创建 Task 前，通过 seam 的 `snapshotSubagentDescriptor()`（基于 [`snapshotJsonValue`](../../../../packages/util/values/src/index.ts) 构建）对每项描述符输入建立快照；这一边界与 Agent 消息现有的分离式无损 JSON 边界一致。作用于 child 作用域的 setup contribution——由进程内驱动前置安装的一次性 `agent/prompt-submit` 监听器——会在下游 prompt admission 能够阻止请求或抛出异常之前追加一个对模型隐藏的 `subagent/descriptor` 事件。admission 获准后才会开启 child 的初始轮次；admission 被拒绝时，描述符会作为轮次前的仅日志事实保留，并由该 activation 最终的必需检查点持久化。该事件不携带 `surfaceOp`，不进入模型历史，并在压缩替换 surface 历史时继续保留。只有在加载已知 child id 对应的 child 会话后，能在该 child 自身的后缀中（`seedLength` 之后，因此 fork seed 不会泄露祖先的描述符）得到受支持的描述符，且会话 header 将调用方标识为直接 parent 时，该 id 才可恢复。
+继续执行管理器在创建 Task 前，通过 seam 的 `snapshotSubagentDescriptor()`（基于 [`snapshotJsonValue`](../../../../packages/util/values/src/index.ts) 构建）对每项描述符输入建立快照；这一边界与 Agent 消息现有的分离式无损 JSON 边界一致。作用于 child 作用域的 setup contribution——由进程内驱动前置安装的一次性 `agent/prompt-submit` 监听器——会在下游 prompt admission 能够阻止请求或抛出异常之前追加一个对模型隐藏的 `subagent/descriptor` 事件。admission 获准后才会开启 child 的初始轮次；admission 被拒绝时，描述符会作为轮次前的仅日志事实保留，并由该 activation 最终的必需检查点持久化。该事件不携带 `surfaceOp`，不进入模型历史，并在压缩替换 surface 历史时继续保留。只有在加载已知 child id 对应的 child 会话后，能在其精确 `inheritedEventCount` 位置或之后得到受支持的描述符，从而阻止 fork seed 泄露祖先描述符，且会话 header 将调用方标识为直接 parent 时，该 id 才可恢复。
 
-版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果约定，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
+版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果约定，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`isSeeded` 和 `delegationDepth` 的权威信息；含正文的持久化 metadata 拥有精确 `inheritedEventCount`，child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
 
 从持久化存储恢复不能依赖 `SubagentRun` 的可选方法，因为该 run 已被 dispose，并且进程重启后不会保留。run 表示一次可 dispose 的激活，只暴露作用于当前激活的操作。`SubagentRun.steer?()` 这一名称明确指代提供确认语义且仅适用于在线消息的功能，以免该功能与服务编排或面向模型的工具混淆。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index 05e4629152..67b922e203 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.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 .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
-2026-07-23-session-telemetry-otel-revival.md: 836531f605eee5c0dcdf108e9ee2b2744d6f72aa
-2026-07-23-session-telemetry-otel-revival.zh.md: 9874598a58ff91bd2cc5ef58c771744d3f3d9610
+2026-07-23-session-telemetry-otel-revival.md: 1110db4b0dfcfd68bde97f9964383ddd041f328b
+2026-07-23-session-telemetry-otel-revival.zh.md: 6c046c5f963760638deacacda51f8d94a13e0efd
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
index 836531f605..1110db4b0d 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
@@ -28,7 +28,7 @@ The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry
 
 **Map onto OTel spans (GenAI semantic conventions) instead of logs.** Rejected for this revival: the branch implementation's log mapping is reviewed and shipped-shaped; the span model is lossy for forkable, interruptible sessions and belongs to a future consumer with real span queries to serve.
 
-**Full-log replay when no handoff cursor survived (re-export constructor seeds).** Shipped in the first revival round, then narrowed: adoption now replays from the session's construction boundary (`Session.firstLiveSeq`, the constructor-seed length — a fact the session already validated but did not expose; `header.seedLength` cannot serve, it is the durable fork-lineage value and a resumed session's constructor seed is its full stored log). A resumed session's history already shipped from the previous process under the same id, and a fork's inherited prefix already shipped in the parent's stream — re-exporting either re-billed every resume for its full history and doubled query-time counts on OTLP backends with no native ingest dedupe. Receivers stitch fork lineage via `session.parent_id` + `session.seed_length`. What the narrowing gives up, consistently with the at-most-once stance: a resume no longer backfills records the previous process failed to deliver (telemetry unmounted then, or queued at crash) — the full replay's only real benefit, bought at the common case's expense. A deployment that states a backfill requirement needs the deferred outbox above, not replay. The boundary also swallows the synthetic turn closers `SessionPersistence.load()` writes when repairing a crash-interrupted log (they sit below `firstLiveSeq` despite never existing in the previous process) — deliberate, not incidental: exporting a synthetic closer cannot complete the remote turn whose real tail records died in the crashed process's queue, it can only make an incomplete turn look closed. The wire stream stays faithful to what the crashed process actually shipped; receivers read a never-closed turn on a resumed stream as "the previous process died inside it" (the OTel README states the rule), and a later clean `shutdown` marker attests only to the resumed process's exit. Threading the pre-repair boundary through load/prepare so repairs export as live events would couple three packages to un-ship that signal.
+**Full-log replay when no handoff cursor survived (re-export constructor seeds).** Shipped in the first revival round, then narrowed: adoption now replays from the session's construction boundary (`Session.firstLiveSeq`, the constructor-seed length; `Session.inheritedEventCount` cannot serve because it is the durable fork-lineage cut and a resumed session's constructor seed is its full stored log). A resumed session's history already shipped from the previous process under the same id, and a fork's inherited prefix already shipped in the parent's stream — re-exporting either re-billed every resume for its full history and doubled query-time counts on OTLP backends with no native ingest dedupe. Receivers stitch fork lineage via `session.parent_id` + `session.seed_length`. What the narrowing gives up, consistently with the at-most-once stance: a resume no longer backfills records the previous process failed to deliver (telemetry unmounted then, or queued at crash) — the full replay's only real benefit, bought at the common case's expense. A deployment that states a backfill requirement needs the deferred outbox above, not replay. The boundary also swallows the synthetic turn closers `SessionPersistence.load()` writes when repairing a crash-interrupted log (they sit below `firstLiveSeq` despite never existing in the previous process) — deliberate, not incidental: exporting a synthetic closer cannot complete the remote turn whose real tail records died in the crashed process's queue, it can only make an incomplete turn look closed. The wire stream stays faithful to what the crashed process actually shipped; receivers read a never-closed turn on a resumed stream as "the previous process died inside it" (the OTel README states the rule), and a later clean `shutdown` marker attests only to the resumed process's exit. Threading the pre-repair boundary through load/prepare so repairs export as live events would couple three packages to un-ship that signal.
 
 **Forwarding the seam's turn-boundary `flush()` hint to the OTel provider's `forceFlush()`.** Shipped in the first revival round, then removed: three distinct silent-loss paths shared the wrapper state — a dispose racing an in-flight flush (the SDK's concurrent-flush guard makes shutdown's internal drain skip), overlapping hints displacing the retained promise, and the provider's fixed 30-second flush timeout rejecting while the processor still drains. Every path exists only because the forwarding made this backend the process's second flusher against undocumented SDK internals from the upstream experimental tree; with no `flush()` implemented, the batch processor is the only flusher, its `scheduledDelayMillis` (already deployment-tunable through the `processor` passthrough) governs export cadence, and `shutdown()`'s drain is complete by construction. Reinstate only if a deployment states a turn-boundary latency requirement `scheduledDelayMillis` cannot meet — and then by calling the retained `BatchLogRecordProcessor`'s own `forceFlush()`, never the provider's timeout-wrapped one.
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index 9874598a58..6c046c5f96 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -29,7 +29,7 @@ Status: implemented
 
 **映射到 OTel span（GenAI 语义约定）而非日志。** 本次复活否决：分支实现的日志映射已经过评审、形态可交付；span 模型对可 fork、可中断的会话有损，留给将来真正有 span 查询需求的消费方。
 
-**handoff 游标未存活时全量回放日志（重新导出构造函数种子）。** 首轮复活曾交付此方案，其后收窄：接管操作现在从会话的构造边界起回放（`Session.firstLiveSeq`，即构造函数种子长度，这一事实会话早已校验过却未曾暴露；`header.seedLength` 不能胜任：它是持久保存的 fork 谱系（lineage）值，而恢复会话的构造函数种子是其完整的已存储日志）。恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀也已在父会话的流中发出；再次导出任何一者，都会让每次恢复为其完整历史重复付费，并在没有原生摄取去重的 OTLP 后端上使查询时的计数翻倍。接收端基于 `session.parent_id` + `session.seed_length` 拼接 fork 谱系。此次收窄放弃的内容与至多一次立场一致：恢复不再回填上一个进程未能投递的记录（彼时遥测未挂载，或崩溃时仍在队列中）——这本是全量回放唯一的真实收益，代价却由常见情形承担。提出回填要求的部署需要的是上文已推迟的 outbox，而不是回放。该边界同样吞掉 `SessionPersistence.load()` 修复被崩溃打断的日志时写入的合成轮次关闭事件（它们落在 `firstLiveSeq` 之前，尽管在上一个进程中从未存在过）。这是有意为之，而非附带效果：远端轮次的真实尾部记录已随崩溃进程的队列一同消亡，导出合成关闭事件无法补全该轮次，只会让一个未完成的轮次看起来已经关闭。导出的流忠实于崩溃进程实际发出的内容；接收端会把恢复后的流中一个从未关闭的轮次读作「上一个进程死在了该轮次之内」（OTel README 陈述了这条规则），其后干净的 `shutdown` 标记也只证明恢复后进程自身的退出。若为让修复以实时事件的身份导出而将修复前边界贯穿 load/prepare 传递，将使三个包相互耦合，只为抹除这一信号。
+**handoff 游标未存活时全量回放日志（重新导出构造函数种子）。** 首轮复活曾交付此方案，其后收窄：接管操作现在从会话的构造边界起回放（`Session.firstLiveSeq`，即构造函数种子长度；`Session.inheritedEventCount` 不能胜任，因为它是持久保存的 fork 谱系 cut，而恢复会话的构造函数种子是其完整的已存储日志）。恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀也已在父会话的流中发出；再次导出任何一者，都会让每次恢复为其完整历史重复付费，并在没有原生摄取去重的 OTLP 后端上使查询时的计数翻倍。接收端基于 `session.parent_id` + `session.seed_length` 拼接 fork 谱系。此次收窄放弃的内容与至多一次立场一致：恢复不再回填上一个进程未能投递的记录（彼时遥测未挂载，或崩溃时仍在队列中）——这本是全量回放唯一的真实收益，代价却由常见情形承担。提出回填要求的部署需要的是上文已推迟的 outbox，而不是回放。该边界同样吞掉 `SessionPersistence.load()` 修复被崩溃打断的日志时写入的合成轮次关闭事件（它们落在 `firstLiveSeq` 之前，尽管在上一个进程中从未存在过）。这是有意为之，而非附带效果：远端轮次的真实尾部记录已随崩溃进程的队列一同消亡，导出合成关闭事件无法补全该轮次，只会让一个未完成的轮次看起来已经关闭。导出的流忠实于崩溃进程实际发出的内容；接收端会把恢复后的流中一个从未关闭的轮次读作「上一个进程死在了该轮次之内」（OTel README 陈述了这条规则），其后干净的 `shutdown` 标记也只证明恢复后进程自身的退出。若为让修复以实时事件的身份导出而将修复前边界贯穿 load/prepare 传递，将使三个包相互耦合，只为抹除这一信号。
 
 **将 seam 的轮次边界 `flush()` 提示转发到 OTel 提供方的 `forceFlush()`。** 首轮复活曾交付此转发，其后移除：三条不同的静默丢失路径共用同一份包装层状态——dispose 与进行中的 flush 之间的竞态（SDK 的并发 flush 防护会令 shutdown 的内部排空被跳过）、相互重叠的提示顶掉留存的 promise、以及提供方固定的 30 秒 flush 超时在批处理器仍在排空时便 reject。这些路径存在的唯一原因，是该转发让这个后端成为进程内第二个执行 flush 的组件，面对的还是上游实验性（experimental）源码树中未见诸文档的 SDK 内部行为；不实现 `flush()` 时，批处理器就是唯一执行 flush 的组件，其 `scheduledDelayMillis`（已可由部署方经 `processor` passthrough 调优）决定导出节奏，`shutdown()` 的排空从构造上就是完整的。仅当某个部署提出 `scheduledDelayMillis` 无法满足的轮次边界延迟要求时才恢复此转发——且届时应调用留存的 `BatchLogRecordProcessor` 自身的 `forceFlush()`，绝不调用提供方那个带超时包装的版本。
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.i18n.yaml
index 8a4c76f227..ac6cdbcd01 100644
--- a/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.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 .agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md
-2026-07-25-subagent-policy-inheritance.md: 34751a4e29e48c84d37425857b8b1b56c8d866eb
-2026-07-25-subagent-policy-inheritance.zh.md: 3d5a6c7a88579583a0ab027c52dd3063eed0a8b2
+2026-07-25-subagent-policy-inheritance.md: 6df9ad53f8588018fca53ebae3a9dfba0d4382de
+2026-07-25-subagent-policy-inheritance.zh.md: f3f7328d558ea55379cb95e53bb010f9f2d2c792
diff --git a/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md b/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md
index 34751a4e29..6df9ad53f8 100644
--- a/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md
+++ b/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md
@@ -12,7 +12,7 @@ Sandbox and approval overrides are per-session log folds. An in-process subagent
 
 The delegation boundary snapshots `sandboxPolicy.overrideOf(parent.session)` before its first await, through the shared child-agent helpers (`captureDelegatedPolicyOverrides`/`appendDelegatedPolicyOverrides` in `dsh-subagent`), which the one-shot driver and the [continuable start](2026-08-10-continuable-subagent-policy-inheritance.md) both call. A later parent switch belongs to the parent's future; cancel-and-redelegate takes a new snapshot. The sandbox-policy service is optional, and only the explicit session override is copied, never deployment defaults or one-shot grants. The approval policy is not inherited: the same capture pins every child to `'never'` — the [approvals-pinned decision](2026-08-10-subagent-approval-pinned-never.md) supersedes this note's original approval-override inheritance.
 
-Each captured value becomes a source-tagged `sandbox/mode` or `approval/policy` event appended during the child factory's unpublished setup. The session constructor has already fixed `Session.firstLiveSeq` at the fork-prefix length, so the inherited facts follow fork history, reach telemetry when the child is announced, and leave `SessionHeader.seedLength` at the prefix length. Existing last-event-wins folds therefore make the delegation snapshot beat stale fork history and let a later child switch beat the snapshot. A grandchild folds its parent's logged state, so the rule composes without another inheritance mechanism.
+Each captured value becomes a source-tagged `sandbox/mode` or `approval/policy` event appended during the child factory's unpublished setup. The session constructor has already fixed `Session.firstLiveSeq` after the constructor seed, while `Session.inheritedEventCount` keeps the exact fork-prefix length, so the inherited facts follow fork history and reach telemetry when the child is announced without changing its lineage cut. Existing last-event-wins folds therefore make the delegation snapshot beat stale fork history and let a later child switch beat the snapshot. A grandchild folds its parent's logged state, so the rule composes without another inheritance mechanism.
 
 Ordinary session appends validate the inherited events before publication, and persistence captures the complete unpublished log when the session is announced. Any materialized child log therefore stores the inherited events with its first batch; there is no second policy store, schema field, or query index. The `source: 'delegation'` marker lets approval narration distinguish inheritance from a child-side user switch.
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.zh.md b/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.zh.md
index 3d5a6c7a88..f3f7328d55 100644
--- a/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 委派边界在第一次 await 之前，经由共享的子 agent 辅助函数（`dsh-subagent` 中的 `captureDelegatedPolicyOverrides`／`appendDelegatedPolicyOverrides`）对 `sandboxPolicy.overrideOf(parent.session)` 获取快照；一次性驱动器与[可继续启动](2026-08-10-continuable-subagent-policy-inheritance.zh.md)都会调用这些辅助函数。父级后续的切换属于父级的未来；取消后重新委派会取得新快照。沙箱策略服务为可选，仅复制显式会话覆盖项，绝不复制部署默认值或一次性授权。审批策略不继承：同一次捕获会把每个子 agent 钉定为 `'never'`——[审批钉定决策](2026-08-10-subagent-approval-pinned-never.zh.md)取代了本 note 原先的审批覆盖项继承。
 
-每个捕获值都会成为子 agent 工厂在未发布设置阶段追加的一条带来源标记的 `sandbox/mode` 或 `approval/policy` 事件。会话构造函数已将 `Session.firstLiveSeq` 固定为 fork 前缀的长度，因此继承事实会排在 fork 历史之后，在子 agent 公布时进入遥测，同时让 `SessionHeader.seedLength` 保持为此前缀的长度。因此，既有的末事件胜出折叠会让委派快照压过陈旧的 fork 历史，并让子 agent 后续的切换压过该快照。孙代 agent 会折叠其父级已记录的状态，因此无需另一套继承机制即可组合此规则。
+每个捕获值都会成为子 agent 工厂在未发布设置阶段追加的一条带来源标记的 `sandbox/mode` 或 `approval/policy` 事件。会话构造函数已把 `Session.firstLiveSeq` 固定在 constructor seed 之后，而 `Session.inheritedEventCount` 保留精确的 fork 前缀长度，因此继承事实会排在 fork 历史之后，并在子 agent 公布时进入遥测，却不改变其谱系 cut。因此，既有的末事件胜出折叠会让委派快照压过陈旧的 fork 历史，并让子 agent 后续的切换压过该快照。孙代 agent 会折叠其父级已记录的状态，因此无需另一套继承机制即可组合此规则。
 
 普通的会话追加会在发布前校验继承事件，持久化层则在会话公布时捕获完整的未发布日志。因此，任何已物化的子 agent 日志都会在首批数据中存下继承事件；不存在第二套策略存储、schema 字段或查询索引。`source: 'delegation'` 标记让审批叙述能够区分继承与子 agent 侧的用户切换。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.i18n.yaml
index 5381b7f346..e5d2539eb1 100644
--- a/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.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 .agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md
-2026-08-05-durable-web-schedule.md: bac4a5cfd8965032dad2cf689ca42b1f8e5da1e3
-2026-08-05-durable-web-schedule.zh.md: 266a90d3a56caccda56be9fe648c059939b8155f
+2026-08-05-durable-web-schedule.md: 1e7a343472cce638a7d1476871cec221fa9fd889
+2026-08-05-durable-web-schedule.zh.md: 50f3347a2c312e3c1a2ea28c582a277cc93a614e
diff --git a/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md b/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md
index bac4a5cfd8..1e7a343472 100644
--- a/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md
+++ b/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md
@@ -22,11 +22,11 @@ The user-visible boundary is `session-local`: the original Session runs an on-ti
 | Due while busy | Active create remains in the fold | Owner waits for idle maintenance, queues one follow-up, then appends dispatch | A later ordinary conversation turn |
 | Several Every records are overdue | Each active record retains its earliest unaccepted anchor-aligned target | One decision selects each record's latest occurrence and advances it past now | One ordinary follow-up containing one occurrence per record |
 | Process stopped or Session cold | Active create remains persisted | No timer or background scan; resume rebuilds the owner | Future target waits; overdue target is attempted |
-| Fork | Parent events remain in the inherited prefix | Child fold starts at `seedLength` | Parent work does not become active in the child |
+| Fork | Parent events remain in the inherited prefix | Child fold starts at the exact `inheritedEventCount` | Parent work does not become active in the child |
 
 ### Session-log authority and tools
 
-The version-1 `schedule/change` stream is the only durable Schedule authority. A create record owns a Session-local, non-reused branded id, the trimmed prompt, its rule discriminator, and UTC target. Delete and one-shot dispatch are terminal transitions. Every dispatch stores its id and decision time so the fold advances that record directly past missed occurrences. The strict decoder and pure fold reject unknown versions, extra fields, reused ids, mismatched dispatch shapes, and transitions against inactive records. A normal Session folds its complete stream; a fork folds only events at or after `SessionHeader.seedLength`.
+The version-1 `schedule/change` stream is the only durable Schedule authority. A create record owns a Session-local, non-reused branded id, the trimmed prompt, its rule discriminator, and UTC target. Delete and one-shot dispatch are terminal transitions. Every dispatch stores its id and decision time so the fold advances that record directly past missed occurrences. The strict decoder and pure fold reject unknown versions, extra fields, reused ids, mismatched dispatch shapes, and transitions against inactive records. A normal Session folds its complete stream; a fork folds only events at or after the `inheritedEventCount` passed into projection initialization.
 
 When `ctx.sessionProjections` exists, Schedule registers a strict unit that uses the same transition and publishes the complete active `ScheduleRecord[]`; the shared [projection state decision](../architecture/2026-08-19-session-projection-state-and-client-views.md) owns its initialization and restore contract. Corrupt durable input fails the existing read path rather than yielding a partial array. The browser-safe record vocabulary is exposed through the type-only `@deepseek-ai/dsh-schedule/client` subpath.
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.zh.md b/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.zh.md
index 266a90d3a5..50f3347a2c 100644
--- a/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.zh.md
@@ -22,11 +22,11 @@ Status: implemented
 | 到期时繁忙 | 活动 create 仍在 fold 中 | owner 等待 idle maintenance，排入一个 follow-up，再追加 dispatch | 后续一个普通对话轮次 |
 | 多条 Every 记录逾期 | 每条活动记录都保留最早一个尚未接受且与锚点对齐的目标 | 一次决策选择每条记录的最新发生时点，并将其推进到当前时刻之后 | 一个普通 follow-up，其中每条记录各有一个发生时点 |
 | 进程停止或 Session cold | 活动 create 仍在 persistence 中 | 不存在 timer 或后台扫描；resume 重建 owner | 未来目标继续等待；overdue 目标会被尝试 |
-| fork | 父 event 留在继承前缀 | child fold 从 `seedLength` 开始 | 父工作不会在 child 中变为活动状态 |
+| fork | 父 event 留在继承前缀 | child fold 从精确 `inheritedEventCount` 开始 | 父工作不会在 child 中变为活动状态 |
 
 ### Session 日志权威与工具
 
-版本 1 `schedule/change` stream 是唯一持久的 Schedule 权威。create 记录拥有一个 Session 内不复用的品牌 id、trim 后的提示词、规则判别字段和 UTC 目标。delete 与一次性 dispatch 是终结转换。Every dispatch 会存储 id 与决策时点，使 fold 将该记录直接推进到错过的发生时点之后。严格 decoder 与纯 fold 会拒绝未知版本、额外字段、重复使用的 id、形状不匹配的 dispatch，以及针对非活动记录的转换。普通 Session 折叠完整 stream；fork 只折叠 `SessionHeader.seedLength` 位置及其后的 event。
+版本 1 `schedule/change` stream 是唯一持久的 Schedule 权威。create 记录拥有一个 Session 内不复用的品牌 id、trim 后的提示词、规则判别字段和 UTC 目标。delete 与一次性 dispatch 是终结转换。Every dispatch 会存储 id 与决策时点，使 fold 将该记录直接推进到错过的发生时点之后。严格 decoder 与纯 fold 会拒绝未知版本、额外字段、重复使用的 id、形状不匹配的 dispatch，以及针对非活动记录的转换。普通 Session 折叠完整 stream；fork 只折叠传入 projection 初始化的 `inheritedEventCount` 位置及其后的 event。
 
 `ctx.sessionProjections` 存在时，Schedule 会注册一个复用同一 transition 的严格单元，并发布完整的活动 `ScheduleRecord[]`；共享的 [projection state 决策](../architecture/2026-08-19-session-projection-state-and-client-views.zh.md)拥有其初始化与 restore 约定。损坏的持久输入会使既有读取路径失败，而不会产生部分数组。浏览器安全的记录词汇通过纯类型子路径 `@deepseek-ai/dsh-schedule/client` 暴露。
 
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
index 26fd9e4836..0032116546 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.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 .agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
-2026-06-22-fork-child-replay-seed-boundary.md: cf4a974035b38ee61e4c2d1cab34776b2ad186c8
-2026-06-22-fork-child-replay-seed-boundary.zh.md: bcc60a583a5f9a4d1fd10ec16e90c49c879d295c
+2026-06-22-fork-child-replay-seed-boundary.md: 1fefc3546ebe029ba95318dad3ac2d463a3fe497
+2026-06-22-fork-child-replay-seed-boundary.zh.md: bb43eacf075318dc0101fca2cacb45a03d847764
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
index cf4a974035..1fefc3546e 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
@@ -18,19 +18,19 @@ Deriving the child script from the whole fork-child log therefore replays the **
 
 Record where a session's **inherited** prefix ends, persist it, and have the replay harness derive a child's script from its **own** events only.
 
-### 1. `seedLength` on the session header
+### 1. Lineage metadata and an exact body-owned cut
 
-`SessionHeader` gains an optional `seedLength: number` — how many leading events were inherited via a seed rather than produced by this session. The fork backend stamps it (= the seeded-prefix length) when it creates the child; a fresh spawn leaves it absent (≡ 0). It is threaded through `CreateSessionOptions.meta` (and `CreateAgentOptions.meta`), set in `SessionStore.prepare`.
+`SessionHeader.isSeeded` records whether a Session has inherited lineage without exposing a body coordinate to header-only readers. The exact leading-event count is the separately branded `SessionLogOffset` `inheritedEventCount`; a fork supplies both `isSeeded: true` and the copied-prefix length, while a fresh spawn supplies an unseeded header and cut zero. The cut travels through `CreateSessionOptions`, `CreateAgentOptions`, persistence inspection, and restored Session state.
 
-`seedLength` is **explicit**, never inferred from `seed.length`. A reconstruction (resume/load) seeds the session with its WHOLE stored log, so `seed.length` there is the full length, not the original boundary — the resume path passes the persisted `seedLength` back from the loaded header instead. (Same shape as `createdAt`, which is also explicitly preserved on reconstruction rather than re-defaulted to now.)
+`inheritedEventCount` is **explicit**, never inferred from `seed.length`. A reconstruction (resume/load) seeds the session with its WHOLE stored log, so `seed.length` there is the full length, not the original boundary — the resume path passes the decoded cut beside the logical header instead.
 
 ### 2. JSONL round-trips it
 
-JSONL stores `seedLength` on the header line (`toHeaderLine`/`fromHeaderLine`) and returns it through the shared persistence contract.
+The v0 JSONL header keeps its optional numeric `seedLength` for byte compatibility. `toHeaderLine` / `fromHeaderLine` translate it to and from logical `isSeeded` plus the exact `inheritedEventCount`, which the shared body-bearing persistence values return separately.
 
 ### 3. Replay derives a child script after the boundary
 
-`dsh-llm-replay`'s `parseSessionHeader` now also reads `seedLength` (absent ⇒ 0), and `loadSessionScripts` derives a child's entries from `parseSessionLog(text).slice(seedLength)` — the events at or after the boundary, i.e. the child's own model calls. For a spawn child `seedLength` is 0 and this is a no-op, so spawn scenarios are byte-for-byte unchanged.
+`dsh-llm-replay`'s private v0 parser reads physical `seedLength` into `inheritedEventCount` (absent ⇒ 0), and `loadSessionScripts` derives a child's entries from `parseSessionLog(text).slice(inheritedEventCount)` — the events at or after the boundary, i.e. the child's own model calls. For a spawn child the cut is 0 and this is a no-op, so spawn scenarios are byte-for-byte unchanged.
 
 This closes the routing correctness gap, and two recorded fork scenarios exercise it end to end — see [Record fork and mixed spawn+fork snapshot scenarios](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md).
 
@@ -40,5 +40,5 @@ This closes the routing correctness gap, and two recorded fork scenarios exercis
 
 ## Consequences
 
-- A new persisted header field spans core and the JSONL provider; the subsystems catalog (`persistence.md`) is updated in the same change (its `SessionHeader` / `CreateSessionOptions` `type-equiv` blocks).
-- Spawn replay is unchanged (`seedLength` 0). Fork replay now routes a child to its own script; covered by a regression in `llm-replay`'s tests (a child fixture whose seeded prefix carries a parent chunk — the derived child script must exclude it, proven red without the slice) and a JSONL persistence round trip through the shared coordinator contract.
+- The lineage bit spans logical Session metadata while the exact cut spans only body-bearing core, persistence, query, and replay values; the v0 physical header remains unchanged.
+- Spawn replay is unchanged (cut 0). Fork replay routes a child to its own script; covered by a regression in `llm-replay`'s tests (a child fixture whose seeded prefix carries a parent chunk — the derived child script must exclude it, proven red without the slice) and a JSONL persistence round trip through the shared coordinator contract.
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
index bcc60a583a..bb43eacf07 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
@@ -18,19 +18,19 @@ subagent 脚本由 [`deriveReplayScript`](../../../../packages/test-support/llm-
 
 记录会话**继承**前缀的结束位置，将其持久化，并让回放 harness 仅从子会话**自身**的事件推导脚本。
 
-### 1. 会话头部的 `seedLength`
+### 1. 谱系 metadata 与正文拥有的精确 cut
 
-`SessionHeader` 新增可选字段 `seedLength: number`——表示有多少前导事件是通过 seed 继承而来、而非本会话产生的。fork 后端在创建子会话时设置它（= 播种前缀的长度）；全新的 spawn 子会话不设置（等同于 0）。它通过 `CreateSessionOptions.meta`（及 `CreateAgentOptions.meta`）传递，在 `SessionStore.prepare` 中设置。
+`SessionHeader.isSeeded` 记录 Session 是否具有继承谱系，而不向仅 header 的 reader 暴露正文坐标。精确的前导事件数量是单独品牌化为 `SessionLogOffset` 的 `inheritedEventCount`；fork 同时提供 `isSeeded: true` 与复制前缀的长度，全新的 spawn 则提供 unseeded header 与零 cut。该 cut 经 `CreateSessionOptions`、`CreateAgentOptions`、持久化 inspection 与恢复后的 Session 状态传递。
 
-`seedLength` 是**显式**的，绝不从 `seed.length` 推断。恢复/加载时用会话的完整已存储日志作为 seed，此时 `seed.length` 是全长而非原始边界——恢复路径改为从加载的 header 中取回持久化的 `seedLength`。（做法与 `createdAt` 相同：恢复时显式保留，而非重新默认为当前时间。）
+`inheritedEventCount` 是**显式**的，绝不从 `seed.length` 推断。恢复／加载时用会话的完整已存储日志作为 seed，此时 `seed.length` 是全长而非原始边界——恢复路径改为在 logical header 之外传递解码后的 cut。
 
 ### 2. JSONL 完整往返
 
-JSONL 把 `seedLength` 存在 header 行（`toHeaderLine`/`fromHeaderLine`），并通过共享持久化约定返回它。
+v0 JSONL header 为保持字节兼容而继续携带可选数值 `seedLength`。`toHeaderLine`／`fromHeaderLine` 在它与 logical `isSeeded` 加精确 `inheritedEventCount` 之间转换，共享的含正文持久化值再单独返回该 cut。
 
 ### 3. 回放从边界之后推导子会话脚本
 
-`dsh-llm-replay` 的 `parseSessionHeader` 现在也读取 `seedLength`（缺失则为 0），`loadSessionScripts` 从 `parseSessionLog(text).slice(seedLength)` 推导子会话条目——即边界及之后的事件，也就是子会话自身的模型调用。对 spawn 子会话而言 `seedLength` 为 0，此操作是空操作，spawn 场景逐字节不变。
+`dsh-llm-replay` 的私有 v0 parser 把物理 `seedLength` 读入 `inheritedEventCount`（缺失则为 0），`loadSessionScripts` 从 `parseSessionLog(text).slice(inheritedEventCount)` 推导子会话条目——即边界及之后的事件，也就是子会话自身的模型调用。对 spawn 子会话而言 cut 为 0，此操作是空操作，spawn 场景逐字节不变。
 
 这弥补了路由正确性的缺口，两个已录制的 fork 场景对其进行端到端验证——见[记录 fork 与混合 spawn+fork 快照场景](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)。
 
@@ -40,5 +40,5 @@ JSONL 把 `seedLength` 存在 header 行（`toHeaderLine`/`fromHeaderLine`），
 
 ## 后果
 
-- core 与 JSONL provider 新增一个持久化 header 字段；子系统目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。
-- spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例会失败），以及通过共享 coordinator 约定执行的 JSONL 持久化往返测试。
+- 谱系 bit 横跨 logical Session metadata，精确 cut 则只横跨含正文的 core、持久化、query 与 replay 值；v0 物理 header 保持不变。
+- spawn 回放不变（cut 为 0）。fork 回放将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例会失败），以及通过共享 coordinator 约定执行的 JSONL 持久化往返测试。
diff --git a/apps/cli/tests/profiles/headless/tests/semantic-checkpoint.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/semantic-checkpoint.expected.e2e.ts
index 0d80cba144..498a4e9499 100644
--- a/apps/cli/tests/profiles/headless/tests/semantic-checkpoint.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/semantic-checkpoint.expected.e2e.ts
@@ -5,7 +5,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { normalizeSessionSnapshot, type NormalizeContext } from '@deepseek-ai/dsh-session-snapshot'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { createUserMessage, ToolCallId , createMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionSeq, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { describe, expect, it } from 'vitest'
 
@@ -29,17 +29,18 @@ async function seedInterruptedSession(root: string, cwd: string): Promise<string
     id: sessionId,
     createdAt: 1,
     cwd,
+    isSeeded: false,
     delegationDepth: 0,
   }
   const events: SessionEvent[] = [
-    { type: 'turn/start', seq: 0, time: 10, data: { turn: 1 } },
-    { type: 'user/message', seq: 1, time: 11, data: createUserMessage({
+    { type: 'turn/start', seq: SessionSeq(0), time: 10, data: { turn: 1 } },
+    { type: 'user/message', seq: SessionSeq(1), time: 11, data: createUserMessage({
       content: [{ type: 'text', text: 'Perform one side-effecting remote mutation.' }], source: { kind: 'user' },
     }), surfaceOp: 'append' },
-    { type: 'step/start', seq: 2, time: 12, data: { turn: 1, step: 1 } },
+    { type: 'step/start', seq: SessionSeq(2), time: 12, data: { turn: 1, step: 1 } },
     {
       type: 'assistant/message',
-      seq: 3,
+      seq: SessionSeq(3),
       time: 13,
       data: {
         turn: 1,
@@ -57,7 +58,7 @@ async function seedInterruptedSession(root: string, cwd: string): Promise<string
     },
     {
       type: 'tool/call',
-      seq: 4,
+      seq: SessionSeq(4),
       time: 14,
       data: {
         turn: 1,
diff --git a/apps/cli/tests/profiles/headless/tests/session-format-guard.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/session-format-guard.expected.e2e.ts
index aafe9af344..a1f5d0ff9e 100644
--- a/apps/cli/tests/profiles/headless/tests/session-format-guard.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/session-format-guard.expected.e2e.ts
@@ -13,6 +13,7 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-l
 import SessionStore, {
   SESSION_FORMAT_VERSION,
   SessionId,
+  SessionSeq,
   type SessionEvent,
   type SessionHeader,
 } from '@deepseek-ai/dsh-session'
@@ -32,7 +33,7 @@ async function seedSession(root: string, cwd: string, version: number, events: S
   const ctx = new Context()
   await ctx.plugin(SessionStore)
   await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
-  const meta: SessionHeader = { version, id: sessionId, createdAt: 1, cwd }
+  const meta: SessionHeader = { version, id: sessionId, createdAt: 1, cwd, isSeeded: false }
   try {
     await ctx.sessionPersistence.create(meta)
     await ctx.sessionPersistence.append(sessionId, events)
@@ -46,8 +47,8 @@ async function seedSession(root: string, cwd: string, version: number, events: S
 
 function closedTurn(): SessionEvent[] {
   return [
-    { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-    { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+    { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
 }
 
@@ -92,7 +93,7 @@ describe('session format guard through the assembled app', () => {
       prepare: async (runCwd) => {
         sessionPath = await seedSession(join(runCwd, '.sessions'), runCwd, SESSION_FORMAT_VERSION, [
           ...closedTurn(),
-          { type: 'future/event', seq: 2, time: 3, data: { payload: 1 } } as unknown as SessionEvent,
+          { type: 'future/event', seq: SessionSeq(2), time: 3, data: { payload: 1 } } as unknown as SessionEvent,
         ])
       },
     })
diff --git a/apps/cli/tests/profiles/headless/tests/subagent-diagnostic.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/subagent-diagnostic.expected.e2e.ts
index 22bca50b83..e3c80f9219 100644
--- a/apps/cli/tests/profiles/headless/tests/subagent-diagnostic.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/subagent-diagnostic.expected.e2e.ts
@@ -11,7 +11,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { normalizeSessionSnapshot, type NormalizeContext } from '@deepseek-ai/dsh-session-snapshot'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionSeq, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { describe, expect, it } from 'vitest'
 
@@ -40,12 +40,13 @@ async function seedDescriptorlessChild(root: string, cwd: string): Promise<void>
     id: parentId,
     createdAt: 1,
     cwd,
+    isSeeded: false,
     delegationDepth: 0,
   }
   const parentEvents: SessionEvent[] = [
-    { type: 'turn/start', seq: 0, time: 10, data: { turn: 1 } },
-    { type: 'user/message', seq: 1, time: 11, data: createUserMessage({ content: [{ type: 'text', text: 'Start a background job.' }], source: { kind: 'user' } }), surfaceOp: 'append' },
-    { type: 'turn/end', seq: 2, time: 12, data: { turn: 1, reason: { kind: 'completed' } } },
+    { type: 'turn/start', seq: SessionSeq(0), time: 10, data: { turn: 1 } },
+    { type: 'user/message', seq: SessionSeq(1), time: 11, data: createUserMessage({ content: [{ type: 'text', text: 'Start a background job.' }], source: { kind: 'user' } }), surfaceOp: 'append' },
+    { type: 'turn/end', seq: SessionSeq(2), time: 12, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
   const childMeta: SessionHeader = {
     version: SESSION_FORMAT_VERSION,
@@ -53,12 +54,13 @@ async function seedDescriptorlessChild(root: string, cwd: string): Promise<void>
     createdAt: 2,
     cwd,
     parentSession: parentId,
+    isSeeded: false,
     origin: 'subagent',
     delegationDepth: 1,
   }
   const childEvents: SessionEvent[] = [
-    { type: 'turn/start', seq: 0, time: 20, data: { turn: 1 } },
-    { type: 'turn/end', seq: 1, time: 21, data: { turn: 1, reason: { kind: 'interrupted' } } },
+    { type: 'turn/start', seq: SessionSeq(0), time: 20, data: { turn: 1 } },
+    { type: 'turn/end', seq: SessionSeq(1), time: 21, data: { turn: 1, reason: { kind: 'interrupted' } } },
   ]
   try {
     await ctx.sessionPersistence.create(parentMeta)
diff --git a/apps/cli/tests/profiles/headless/tests/subagent-inheritance.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/subagent-inheritance.expected.e2e.ts
index 3536082391..9f9da8707d 100644
--- a/apps/cli/tests/profiles/headless/tests/subagent-inheritance.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/subagent-inheritance.expected.e2e.ts
@@ -10,7 +10,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { normalizeSessionSnapshot, type NormalizeContext } from '@deepseek-ai/dsh-session-snapshot'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionSeq, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { describe, expect, it } from 'vitest'
 
@@ -36,15 +36,16 @@ async function seedReadOnlyParent(root: string, cwd: string): Promise<void> {
     id: sessionId,
     createdAt: 1,
     cwd,
+    isSeeded: false,
     delegationDepth: 0,
   }
   const events: SessionEvent[] = [
-    { type: 'turn/start', seq: 0, time: 10, data: { turn: 1 } },
-    { type: 'user/message', seq: 1, time: 11, data: createUserMessage({ content: [{ type: 'text', text: 'Tighten this session to read-only.' }], source: { kind: 'user' } }), surfaceOp: 'append' },
-    { type: 'sandbox/mode', seq: 2, time: 12, data: { mode: 'read-only' } },
+    { type: 'turn/start', seq: SessionSeq(0), time: 10, data: { turn: 1 } },
+    { type: 'user/message', seq: SessionSeq(1), time: 11, data: createUserMessage({ content: [{ type: 'text', text: 'Tighten this session to read-only.' }], source: { kind: 'user' } }), surfaceOp: 'append' },
+    { type: 'sandbox/mode', seq: SessionSeq(2), time: 12, data: { mode: 'read-only' } },
     {
       type: 'request/header',
-      seq: 3,
+      seq: SessionSeq(3),
       time: 13,
       data: {
         header: {
@@ -57,7 +58,7 @@ async function seedReadOnlyParent(root: string, cwd: string): Promise<void> {
         reason: 'initial',
       },
     },
-    { type: 'turn/end', seq: 4, time: 14, data: { turn: 1, reason: { kind: 'completed' } } },
+    { type: 'turn/end', seq: SessionSeq(4), time: 14, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
   try {
     await ctx.sessionPersistence.create(meta)
diff --git a/apps/cli/tests/profiles/headless/tests/workspace-context-resume.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/workspace-context-resume.expected.e2e.ts
index 043c7f4514..2fded92b5b 100644
--- a/apps/cli/tests/profiles/headless/tests/workspace-context-resume.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/workspace-context-resume.expected.e2e.ts
@@ -14,6 +14,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import SessionStore, {
   SESSION_FORMAT_VERSION,
   SessionId,
+  SessionSeq,
   type SessionEvent,
   type SessionHeader,
 } from '@deepseek-ai/dsh-session'
@@ -53,6 +54,7 @@ async function seedVisibleBaseline(
     id: sessionId,
     createdAt: 1,
     cwd,
+    isSeeded: false,
     delegationDepth: 0,
   }
   const files = options.files ?? [{ name: 'AGENTS.md', content: oldInstruction }]
@@ -69,17 +71,17 @@ async function seedVisibleBaseline(
       : { instructionFileCandidates: options.instructionFileCandidates },
   })
   const events: SessionEvent[] = [
-    { type: 'turn/start', seq: 0, time: 10, data: { turn: 1 } },
+    { type: 'turn/start', seq: SessionSeq(0), time: 10, data: { turn: 1 } },
     {
       type: 'user/message',
-      seq: 1,
+      seq: SessionSeq(1),
       time: 11,
       data: createUserMessage({ content: [{ type: 'text', text: 'Remember the workspace instruction.' }], source: { kind: 'user' } }),
       surfaceOp: 'append',
     },
     {
       type: 'user/message',
-      seq: 2,
+      seq: SessionSeq(2),
       time: 12,
       data: createUserMessage({
         content: [{ type: 'text', text: baseline.text }],
@@ -98,7 +100,7 @@ async function seedVisibleBaseline(
       }),
       surfaceOp: 'append',
     },
-    { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'completed' } } },
+    { type: 'turn/end', seq: SessionSeq(3), time: 13, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
   try {
     await ctx.sessionPersistence.create(meta)
diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts
index 0af082c324..6c2ac3db7b 100644
--- a/apps/cli/tests/web-agent-presets.e2e.ts
+++ b/apps/cli/tests/web-agent-presets.e2e.ts
@@ -6,7 +6,7 @@ import { dirname, join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
 import { boot, healProfilesModuleFallback, loadOverlayPatches, loadProfile } from '@deepseek-ai/dsh-app-boot'
 import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
@@ -655,9 +655,11 @@ describe('a forked session', () => {
     const inherited = ctx.sessionProjections.stateOf(parent.agent.session, 'agentPreset') ?? undefined
     const child = await ctx.agents.create({
       sessionId: SessionId('preset-fork-child'),
+      seed: [],
+      inheritedEventCount: SessionLogOffset(0),
       meta: {
         parentSession: SessionId('preset-fork-parent'),
-        seedLength: 0,
+        isSeeded: true,
         ...inherited === undefined ? {} : { agentPreset: inherited },
       },
       setup: agentCtx => ctx.agentPresets.mount(agentCtx, inherited).then(() => undefined),
@@ -685,7 +687,7 @@ describe('a delegated child', () => {
     // Exactly what an in-process subagent driver's creation window does.
     const child = await parent.agent.ctx.agents.create({
       sessionId: SessionId('preset-child'),
-      meta: childSessionMeta(parent.agent, 1, 0),
+      meta: childSessionMeta(parent.agent, 1, false),
       setup: (agentCtx) => {
         applyChildComposition(agentCtx, parent.agent, {})
       },
@@ -711,7 +713,7 @@ describe('a delegated child', () => {
     await ctx.agentPresets.recompose(parent.agent.ctx, 'minimal')
     const child = await parent.agent.ctx.agents.create({
       sessionId: SessionId('preset-child-switch'),
-      meta: childSessionMeta(parent.agent, 1, 0),
+      meta: childSessionMeta(parent.agent, 1, false),
       setup: (agentCtx) => {
         applyChildComposition(agentCtx, parent.agent, {})
       },
diff --git a/apps/web/tests/agent-preset-selection.e2e.ts b/apps/web/tests/agent-preset-selection.e2e.ts
index 367b83634d..99437f7f8c 100644
--- a/apps/web/tests/agent-preset-selection.e2e.ts
+++ b/apps/web/tests/agent-preset-selection.e2e.ts
@@ -15,8 +15,9 @@ import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { MessageId } from '@deepseek-ai/dsh-llm'
 import {
-  SESSION_FORMAT_VERSION, SessionId as sessionId, type SessionEvent, type SessionHeader, type SessionId,
+  SESSION_FORMAT_VERSION, SessionId as sessionId, SessionSeq, type SessionHeader, type SessionId,
 } from '@deepseek-ai/dsh-session'
 import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent'
 import {
@@ -116,6 +117,7 @@ async function seedSubagent(scaffold: WebScaffold, parentId: SessionId): Promise
     createdAt,
     cwd: scaffold.workspaceCwd,
     parentSession: parentId,
+    isSeeded: false,
     origin: 'subagent',
     delegationDepth: 1,
     agentPreset: 'minimal',
@@ -124,15 +126,17 @@ async function seedSubagent(scaffold: WebScaffold, parentId: SessionId): Promise
   await scaffold.ctx.sessionPersistence.append(childId, [
     {
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: createdAt,
-      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+      data: { turn: 1 },
     },
     {
       type: 'user/message',
-      seq: 1,
+      seq: SessionSeq(1),
       time: createdAt + 1,
       data: {
+        id: MessageId(`legacy-message:${childId}:1`),
+        role: 'user',
         content: [{ type: 'text', text: 'Check the session-header action order.' }],
         source: { kind: 'user' },
       },
@@ -140,7 +144,7 @@ async function seedSubagent(scaffold: WebScaffold, parentId: SessionId): Promise
     },
     {
       type: 'subagent/descriptor',
-      seq: 2,
+      seq: SessionSeq(2),
       time: createdAt + 2,
       data: snapshotSubagentDescriptor({
         mode: 'one-shot', provider: 'spawn', label: 'header order probe',
@@ -148,11 +152,11 @@ async function seedSubagent(scaffold: WebScaffold, parentId: SessionId): Promise
     },
     {
       type: 'turn/end',
-      seq: 3,
+      seq: SessionSeq(3),
       time: createdAt + 3,
       data: { turn: 1, reason: { kind: 'completed' } },
     },
-  ] as SessionEvent[])
+  ])
 }
 
 /**
diff --git a/apps/web/tests/chat-long-interactions.e2e.ts b/apps/web/tests/chat-long-interactions.e2e.ts
index 15d598a58f..b8e9e4c042 100644
--- a/apps/web/tests/chat-long-interactions.e2e.ts
+++ b/apps/web/tests/chat-long-interactions.e2e.ts
@@ -311,7 +311,7 @@ describe('web e2e: long Chat interaction contract', () => {
     const child = scaffold.ctx.agents.list()
       .find(agent => agent.session.header.parentSession === SessionId(SESSION_ID))
     if (child === undefined) throw new Error('message branch did not create a child session')
-    expect(child.session.header.seedLength).toBe(boundary.seq + 1)
+    expect(child.session.inheritedEventCount).toBe(boundary.seq + 1)
     expect(child.session.snapshotEvents().some(event => carries(event, branchAssistantMarker))).toBe(true)
     expect(child.session.snapshotEvents().some(event => carries(event, FIXTURE.markers.user(BRANCH_TURN + 1)))).toBe(false)
     expect(child.session.snapshotEvents().some(event => carries(event, FIXTURE.markers.user(FIXTURE.turns)))).toBe(false)
diff --git a/apps/web/tests/complex-history.perf.ts b/apps/web/tests/complex-history.perf.ts
index 564334b1f3..4ba4d4b727 100644
--- a/apps/web/tests/complex-history.perf.ts
+++ b/apps/web/tests/complex-history.perf.ts
@@ -17,7 +17,7 @@ import {
   createUserMessage,
 } from '@deepseek-ai/dsh-llm'
 import type { ReplayEntry, ReplayOverrideDoc } from '@deepseek-ai/dsh-llm-replay'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionSeq } from '@deepseek-ai/dsh-session'
 import {
   SESSION_FORMAT_VERSION,
   Session,
@@ -187,7 +187,7 @@ function text(value: string): { type: 'text'; text: string }[] {
   return [{ type: 'text', text: value }]
 }
 
-function appendTitle(session: Session, title: string, messageSeq: number): void {
+function appendTitle(session: Session, title: string, messageSeq: SessionSeq): void {
   session.append('session/title', {
     title,
     messageSeqs: [messageSeq],
diff --git a/apps/web/tests/reference-composer.e2e.ts b/apps/web/tests/reference-composer.e2e.ts
index dc84191180..3587272a12 100644
--- a/apps/web/tests/reference-composer.e2e.ts
+++ b/apps/web/tests/reference-composer.e2e.ts
@@ -12,6 +12,7 @@ import {
   SESSION_FORMAT_VERSION,
   Session,
   SessionId,
+  SessionSeq,
 } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-session-reference/types'
 import type {} from '@deepseek-ai/dsh-session-title'
@@ -80,7 +81,7 @@ function targetSessionFixture(): string {
       references: [{
         sessionId: SOURCE_SESSION_ID,
         label: 'Research notes',
-        capturedThroughSeq: 4,
+        capturedThroughSeq: SessionSeq(4),
         compacted: false,
         originalMessages: 2,
         retainedMessages: 2,
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 5a60a049ca..95a7118560 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -67,6 +67,7 @@ import SessionStore, {
   packChunkRuns,
   SESSION_FORMAT_VERSION,
   SessionId,
+  SessionSeq,
   type Session,
   type SessionEvent,
   type SessionHeader,
@@ -801,8 +802,20 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
  * in-memory record-mode harvest, so the on-disk zstd default never matters.
  */
 function rawSessionLog(session: Session): string {
+  const header = session.header
   return [
-    JSON.stringify({ type: 'session', ...session.header }),
+    JSON.stringify({
+      type: 'session',
+      version: header.version,
+      id: header.id,
+      createdAt: header.createdAt,
+      ...header.cwd === undefined ? {} : { cwd: header.cwd },
+      ...header.parentSession === undefined ? {} : { parentSession: header.parentSession },
+      ...header.isSeeded ? { seedLength: Number(session.inheritedEventCount) } : {},
+      ...header.origin === undefined ? {} : { origin: header.origin },
+      ...header.delegationDepth === undefined ? {} : { delegationDepth: header.delegationDepth },
+      ...header.agentPreset === undefined ? {} : { agentPreset: header.agentPreset },
+    }),
     ...packChunkRuns(session.snapshotEvents()).map(record => JSON.stringify(record)),
     '',
   ].join('\n')
@@ -1030,6 +1043,7 @@ export async function seedSession(
     id: SessionId(id),
     createdAt: Date.now() - 60_000,
     cwd: scaffold.workspaceCwd,
+    isSeeded: false,
     delegationDepth: 0,
     ...agentPreset === undefined ? {} : { agentPreset },
   }
@@ -1054,11 +1068,12 @@ export async function seedBlankSession(
     id: SessionId(id),
     createdAt: Date.now() - 60_000,
     cwd,
+    isSeeded: false,
     delegationDepth: 0,
   }
   await persistSeedSession(scaffold, meta, [{
     type: 'session/end-seed',
-    seq: 0,
+    seq: SessionSeq(0),
     time: meta.createdAt,
     data: {},
   }])
diff --git a/apps/web/tests/schedule-after.e2e.ts b/apps/web/tests/schedule-after.e2e.ts
index 72b98105aa..28c3425941 100644
--- a/apps/web/tests/schedule-after.e2e.ts
+++ b/apps/web/tests/schedule-after.e2e.ts
@@ -10,7 +10,7 @@ import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent'
 import { composeEntries, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
 import { ToolCallId, createUserMessage, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
-import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionId, SessionLogOffset, type SessionEvent } from '@deepseek-ai/dsh-session'
 import {
   ScheduleId,
   createEveryScheduleRecord,
@@ -615,8 +615,12 @@ describe.skipIf(MODE === 'record')('web e2e: active Schedule catalog', () => {
     await workspace.attachSession(CATALOG_SESSION_ID)
 
     // Seed the zero-I/O list view before the Session is opened.
-    const catalog = await scaffold.ctx.sessionPersistence.readFrom(CATALOG_SESSION_ID, 0)
-    scaffold.ctx.sessionProjectionCache.coldSnapshot(catalog.meta, catalog.events)
+    const catalog = await scaffold.ctx.sessionPersistence.readFrom(CATALOG_SESSION_ID, SessionLogOffset(0))
+    scaffold.ctx.sessionProjectionCache.coldSnapshot(
+      catalog.meta,
+      catalog.inheritedEventCount,
+      catalog.events,
+    )
 
     browser = await chromium.launch()
     page = await browser.newPage({
diff --git a/apps/web/tests/subagent-conversation.e2e.ts b/apps/web/tests/subagent-conversation.e2e.ts
index 92750e5d41..56b96adc4c 100644
--- a/apps/web/tests/subagent-conversation.e2e.ts
+++ b/apps/web/tests/subagent-conversation.e2e.ts
@@ -5,8 +5,9 @@ import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { MessageId } from '@deepseek-ai/dsh-llm'
 import {
-  SESSION_FORMAT_VERSION, SessionId as sessionId, type SessionEvent, type SessionHeader, type SessionId,
+  SESSION_FORMAT_VERSION, SessionId as sessionId, SessionLogOffset, SessionSeq, type SessionEvent, type SessionHeader, type SessionId,
 } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-agent'
 import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent'
@@ -66,9 +67,10 @@ async function waitForAgentToSettle(scaffold: WebScaffold, id: SessionId): Promi
 async function waitForCacheRow(
   scaffold: WebScaffold,
   header: SessionHeader,
+  inheritedEventCount: SessionLogOffset,
 ): Promise<void> {
   const deadline = Date.now() + 10_000
-  while (scaffold.ctx.sessionProjectionCache.cachedSnapshot(header) === undefined) {
+  while (scaffold.ctx.sessionProjectionCache.cachedSnapshot(header, inheritedEventCount) === undefined) {
     if (Date.now() >= deadline) throw new Error(`cache row for "${header.id}" did not land`)
     await new Promise<void>(resolve => setTimeout(resolve, 10))
   }
@@ -136,6 +138,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       createdAt: oneShotAt,
       cwd: scaffold.workspaceCwd,
       parentSession: parent.id,
+      isSeeded: false,
       origin: 'subagent',
       delegationDepth: 1,
     }
@@ -143,15 +146,17 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
     const oneShotEvents = [
       {
         type: 'turn/start',
-        seq: 0,
+        seq: SessionSeq(0),
         time: oneShotAt,
-        data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+        data: { turn: 1 },
       },
       {
         type: 'user/message',
-        seq: 1,
+        seq: SessionSeq(1),
         time: oneShotAt + 1,
         data: {
+          id: MessageId(`legacy-message:${oneShotId}:1`),
+          role: 'user',
           content: [{ type: 'text', text: 'Review the event sourcing explanation.' }],
           source: { kind: 'user' },
         },
@@ -159,7 +164,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       },
       {
         type: 'subagent/descriptor',
-        seq: 2,
+        seq: SessionSeq(2),
         time: oneShotAt + 2,
         data: snapshotSubagentDescriptor({
           mode: 'one-shot', provider: 'spawn', label: ONE_SHOT_LABEL,
@@ -167,14 +172,14 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       },
       {
         type: 'turn/end',
-        seq: 3,
+        seq: SessionSeq(3),
         time: oneShotAt + oneShotDurationMs,
         data: { turn: 1, reason: { kind: 'completed' } },
       },
-    ] as SessionEvent[]
+    ] satisfies SessionEvent[]
     await scaffold.ctx.sessionPersistence.append(oneShotId, oneShotEvents)
-    scaffold.ctx.sessionProjectionCache.coldSnapshot(oneShotHeader, oneShotEvents)
-    await waitForCacheRow(scaffold, oneShotHeader)
+    scaffold.ctx.sessionProjectionCache.coldSnapshot(oneShotHeader, SessionLogOffset(0), oneShotEvents)
+    await waitForCacheRow(scaffold, oneShotHeader, SessionLogOffset(0))
     grandchildId = sessionId('recorded-grandchild')
     const authoredAt = Date.now()
     const grandchildHeader: SessionHeader = {
@@ -183,6 +188,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       createdAt: authoredAt,
       cwd: scaffold.workspaceCwd,
       parentSession: childId,
+      isSeeded: false,
       origin: 'subagent',
       delegationDepth: 2,
     }
@@ -190,15 +196,17 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
     const grandchildEvents = [
       {
         type: 'turn/start',
-        seq: 0,
+        seq: SessionSeq(0),
         time: authoredAt,
-        data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+        data: { turn: 1 },
       },
       {
         type: 'user/message',
-        seq: 1,
+        seq: SessionSeq(1),
         time: authoredAt + 1,
         data: {
+          id: MessageId(`legacy-message:${grandchildId}:1`),
+          role: 'user',
           content: [{ type: 'text', text: NESTED_PROMPT }],
           source: { kind: 'user' },
         },
@@ -206,7 +214,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       },
       {
         type: 'subagent/descriptor',
-        seq: 2,
+        seq: SessionSeq(2),
         time: authoredAt + 2,
         data: snapshotSubagentDescriptor({
           mode: 'continuable', provider: 'spawn', label: NESTED_LABEL,
@@ -214,14 +222,14 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       },
       {
         type: 'turn/end',
-        seq: 3,
+        seq: SessionSeq(3),
         time: authoredAt + 3,
         data: { turn: 1, reason: { kind: 'completed' } },
       },
-    ] as SessionEvent[]
+    ] satisfies SessionEvent[]
     await scaffold.ctx.sessionPersistence.append(grandchildId, grandchildEvents)
-    scaffold.ctx.sessionProjectionCache.coldSnapshot(grandchildHeader, grandchildEvents)
-    await waitForCacheRow(scaffold, grandchildHeader)
+    scaffold.ctx.sessionProjectionCache.coldSnapshot(grandchildHeader, SessionLogOffset(0), grandchildEvents)
+    await waitForCacheRow(scaffold, grandchildHeader, SessionLogOffset(0))
     expect(scaffold.ctx.agents.get(childId)).toBeUndefined()
     expect(scaffold.ctx.agents.get(oneShotId)).toBeUndefined()
     expect(scaffold.ctx.agents.get(grandchildId)).toBeUndefined()
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 7075380d74..19563b4b27 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: f9eb7ae0bc634e655462412e7dd5d341b7a449a2
-config-catalog.zh.md: 827f39d068de067aefa4dfc77fc53c3db74b5336
+config-catalog.md: ec62912c76ad336a7bd7e966be7921c9938a211c
+config-catalog.zh.md: e785cacb15652e4162066cbdae478870cf61bc4e
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index f9eb7ae0bc..ec62912c76 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -215,7 +215,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/api/session-controller/src/index.ts:67`](../packages/api/session-controller/src/index.ts)
+Source: [`packages/api/session-controller/src/index.ts:68`](../packages/api/session-controller/src/index.ts)
 
 <a id="deepseek-aidsh-api-settings-controller"></a>
 
@@ -457,7 +457,7 @@ export interface ToolResultPruneConfig {
 }
 ```
 
-Source: [`packages/compaction/compaction-tool-result-pruner/src/types.ts:4`](../packages/compaction/compaction-tool-result-pruner/src/types.ts)
+Source: [`packages/compaction/compaction-tool-result-pruner/src/types.ts:5`](../packages/compaction/compaction-tool-result-pruner/src/types.ts)
 
 <a id="deepseek-aidsh-cordis-host-runner"></a>
 
@@ -763,7 +763,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/goal/goal/src/index.ts:171`](../packages/goal/goal/src/index.ts)
+Source: [`packages/goal/goal/src/index.ts:172`](../packages/goal/goal/src/index.ts)
 
 <a id="deepseek-aidsh-headless"></a>
 
@@ -779,7 +779,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/bundle/headless/src/index.ts:33`](../packages/bundle/headless/src/index.ts)
+Source: [`packages/bundle/headless/src/index.ts:34`](../packages/bundle/headless/src/index.ts)
 
 <a id="deepseek-aidsh-hooks-claude-code"></a>
 
@@ -1355,7 +1355,7 @@ export interface ReplayModelConfig {
 
 Depends on: [`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
 
-Source: [`packages/test-support/llm-replay/src/index.ts:919`](../packages/test-support/llm-replay/src/index.ts)
+Source: [`packages/test-support/llm-replay/src/index.ts:924`](../packages/test-support/llm-replay/src/index.ts)
 
 <a id="deepseek-aidsh-llm-retry"></a>
 
@@ -1499,7 +1499,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/feedback/message-feedback/src/index.ts:49`](../packages/feedback/message-feedback/src/index.ts)
+Source: [`packages/feedback/message-feedback/src/index.ts:50`](../packages/feedback/message-feedback/src/index.ts)
 
 <a id="deepseek-aidsh-permission-presets"></a>
 
@@ -1800,7 +1800,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session/session-log-deepseek/src/index.ts:23`](../packages/session/session-log-deepseek/src/index.ts)
+Source: [`packages/session/session-log-deepseek/src/index.ts:36`](../packages/session/session-log-deepseek/src/index.ts)
 
 <a id="deepseek-aidsh-session-log-export"></a>
 
@@ -1858,7 +1858,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-Source: [`packages/session/session-persistence-jsonl/src/index.ts:62`](../packages/session/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session/session-persistence-jsonl/src/index.ts:70`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 <a id="deepseek-aidsh-session-projection-cache"></a>
 
@@ -1882,7 +1882,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session/session-projection-cache/src/index.ts:48`](../packages/session/session-projection-cache/src/index.ts)
+Source: [`packages/session/session-projection-cache/src/index.ts:55`](../packages/session/session-projection-cache/src/index.ts)
 
 <a id="deepseek-aidsh-session-query-sqlite"></a>
 
@@ -1928,7 +1928,7 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 
 Depends on: [`SessionQueryConfig`](../packages/session-query/session-query/src/index.ts)
 
-Source: [`packages/session-query/session-query-sqlite/src/index.ts:89`](../packages/session-query/session-query-sqlite/src/index.ts)
+Source: [`packages/session-query/session-query-sqlite/src/index.ts:96`](../packages/session-query/session-query-sqlite/src/index.ts)
 
 <a id="deepseek-aidsh-session-reference"></a>
 
@@ -2014,7 +2014,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session/session-title/src/index.ts:55`](../packages/session/session-title/src/index.ts)
+Source: [`packages/session/session-title/src/index.ts:56`](../packages/session/session-title/src/index.ts)
 
 <a id="deepseek-aidsh-session-title-all-prompts-llm"></a>
 
@@ -2583,7 +2583,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/context/time-context/src/index.ts:48`](../packages/context/time-context/src/index.ts)
+Source: [`packages/context/time-context/src/index.ts:49`](../packages/context/time-context/src/index.ts)
 
 <a id="deepseek-aidsh-tmux-context"></a>
 
@@ -2612,7 +2612,7 @@ Requires: `sessionProjections`
 export type TokenMeterConfig = Record<string, never>
 ```
 
-Source: [`packages/llm/token-meter/src/types.ts:12`](../packages/llm/token-meter/src/types.ts)
+Source: [`packages/llm/token-meter/src/types.ts:13`](../packages/llm/token-meter/src/types.ts)
 
 <a id="deepseek-aidsh-tool-bash"></a>
 
@@ -2959,7 +2959,7 @@ export interface Config {
 
 Depends on: [`AgentOptions`](subsystems/core.md)
 
-Source: [`packages/subagent/tool-subagent/src/index.ts:46`](../packages/subagent/tool-subagent/src/index.ts)
+Source: [`packages/subagent/tool-subagent/src/index.ts:47`](../packages/subagent/tool-subagent/src/index.ts)
 
 <a id="deepseek-aidsh-tool-terminal"></a>
 
@@ -3128,7 +3128,7 @@ export interface Config {
 export type ApprovalPolicy = 'ask' | 'never'
 ```
 
-Source: [`packages/interaction/user-approval/src/index.ts:126`](../packages/interaction/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:127`](../packages/interaction/user-approval/src/index.ts)
 
 <a id="deepseek-aidsh-web"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 827f39d068..e785cacb15 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -217,7 +217,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/api/session-controller/src/index.ts:67`](../packages/api/session-controller/src/index.ts)
+来源：[`packages/api/session-controller/src/index.ts:68`](../packages/api/session-controller/src/index.ts)
 
 <a id="deepseek-aidsh-api-settings-controller"></a>
 
@@ -459,7 +459,7 @@ export interface ToolResultPruneConfig {
 }
 ```
 
-来源：[`packages/compaction/compaction-tool-result-pruner/src/types.ts:4`](../packages/compaction/compaction-tool-result-pruner/src/types.ts)
+来源：[`packages/compaction/compaction-tool-result-pruner/src/types.ts:5`](../packages/compaction/compaction-tool-result-pruner/src/types.ts)
 
 <a id="deepseek-aidsh-cordis-host-runner"></a>
 
@@ -765,7 +765,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/goal/goal/src/index.ts:171`](../packages/goal/goal/src/index.ts)
+来源：[`packages/goal/goal/src/index.ts:172`](../packages/goal/goal/src/index.ts)
 
 <a id="deepseek-aidsh-headless"></a>
 
@@ -1357,7 +1357,7 @@ export interface ReplayModelConfig {
 
 依赖：[`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
 
-来源：[`packages/test-support/llm-replay/src/index.ts:919`](../packages/test-support/llm-replay/src/index.ts)
+来源：[`packages/test-support/llm-replay/src/index.ts:924`](../packages/test-support/llm-replay/src/index.ts)
 
 <a id="deepseek-aidsh-llm-retry"></a>
 
@@ -1501,7 +1501,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/feedback/message-feedback/src/index.ts:49`](../packages/feedback/message-feedback/src/index.ts)
+来源：[`packages/feedback/message-feedback/src/index.ts:50`](../packages/feedback/message-feedback/src/index.ts)
 
 <a id="deepseek-aidsh-permission-presets"></a>
 
@@ -1802,7 +1802,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/session/session-log-deepseek/src/index.ts:23`](../packages/session/session-log-deepseek/src/index.ts)
+来源：[`packages/session/session-log-deepseek/src/index.ts:36`](../packages/session/session-log-deepseek/src/index.ts)
 
 <a id="deepseek-aidsh-session-log-export"></a>
 
@@ -1860,7 +1860,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-来源：[`packages/session/session-persistence-jsonl/src/index.ts:62`](../packages/session/session-persistence-jsonl/src/index.ts)
+来源：[`packages/session/session-persistence-jsonl/src/index.ts:70`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 <a id="deepseek-aidsh-session-projection-cache"></a>
 
@@ -1884,7 +1884,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/session/session-projection-cache/src/index.ts:48`](../packages/session/session-projection-cache/src/index.ts)
+来源：[`packages/session/session-projection-cache/src/index.ts:55`](../packages/session/session-projection-cache/src/index.ts)
 
 <a id="deepseek-aidsh-session-query-sqlite"></a>
 
@@ -1930,7 +1930,7 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 
 依赖：[`SessionQueryConfig`](../packages/session-query/session-query/src/index.ts)
 
-来源：[`packages/session-query/session-query-sqlite/src/index.ts:89`](../packages/session-query/session-query-sqlite/src/index.ts)
+来源：[`packages/session-query/session-query-sqlite/src/index.ts:96`](../packages/session-query/session-query-sqlite/src/index.ts)
 
 <a id="deepseek-aidsh-session-reference"></a>
 
@@ -2016,7 +2016,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/session/session-title/src/index.ts:55`](../packages/session/session-title/src/index.ts)
+来源：[`packages/session/session-title/src/index.ts:56`](../packages/session/session-title/src/index.ts)
 
 <a id="deepseek-aidsh-session-title-all-prompts-llm"></a>
 
@@ -2614,7 +2614,7 @@ export interface Config {
 export type TokenMeterConfig = Record<string, never>
 ```
 
-来源：[`packages/llm/token-meter/src/types.ts:12`](../packages/llm/token-meter/src/types.ts)
+来源：[`packages/llm/token-meter/src/types.ts:13`](../packages/llm/token-meter/src/types.ts)
 
 <a id="deepseek-aidsh-tool-bash"></a>
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 2ba3190cff..28dc25a1c8 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: f9606dcf399519f0c62b6403f300b66e80e47d36
-event-producer-consumer.zh.md: f9e4d35e6ed213046957b5e7fc1e03a334de9992
+event-producer-consumer.md: bdfb3f23e817dadebb090df154af8e1ebf018ee8
+event-producer-consumer.zh.md: 3fe1fe737cb7e99bb8e3a8641dc7bbd7b11b74a4
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index f9606dcf39..bdfb3f23e8 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -21,14 +21,14 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:503`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:509`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:516`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:542`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:522`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:549`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:528`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:535`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
@@ -45,7 +45,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:67`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
 | `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
 | `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index f9e4d35e6e..3fe1fe737c 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -23,14 +23,14 @@
 | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:503`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:509`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:516`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:542`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:522`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:549`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:528`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:535`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
@@ -47,7 +47,7 @@
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:67`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
 | `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
 | `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index c5520d4dd2..68394c63b7 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.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 docs/persistence-catalog.md
-persistence-catalog.md: fd5b3a4a377069fb7b1fbc37b78d11ec037073a4
-persistence-catalog.zh.md: 9d8fc88a44da1620e2de9aa066b9d6c6204b29b1
+persistence-catalog.md: 2fb2b020841a42da6f7505928a87868fc43bc559
+persistence-catalog.zh.md: 4014fd2c10e20193ea68a5f6c761c99b4569b032
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index fd5b3a4a37..2fb2b02084 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -40,7 +40,7 @@ export type SurfaceEventType =
  */
 export type SurfaceOp =
   | 'append'
-  | { op: 'replace'; start: number; end: number }
+  | { op: 'replace'; start: SessionSeq; end: SessionSeq }
 
 /**
  * One immutable entry in the session log.
@@ -59,7 +59,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
   [K in SessionEventType]: {
     type: K
     /** Monotonic sequence number within the session. */
-    seq: number
+    seq: SessionSeq
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
@@ -83,14 +83,14 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * provider stream; when the field is absent, the event does not record which
      * earlier events produced the message.
      */
-    sourceEventSeqs?: number[]
+    sourceEventSeqs?: SessionSeq[]
     /** How this event entered the surface; absent for non-surface events. */
     surfaceOp?: SurfaceOp
   } : object)
 }[T]
 ```
 
-Sources: [`packages/core/session/src/types.ts:323`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:330`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:359`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:391`](../packages/core/session/src/types.ts)
+Sources: [`packages/core/session/src/types.ts:366`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:373`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:402`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:434`](../packages/core/session/src/types.ts)
 
 ## Events
 
@@ -200,7 +200,7 @@ Source: [`packages/interaction/user-approval/src/types.ts:55`](../packages/inter
 }
 ```
 
-Source: [`packages/interaction/user-approval/src/index.ts:32`](../packages/interaction/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:33`](../packages/interaction/user-approval/src/index.ts)
 
 ### `assistant/*`
 
@@ -215,7 +215,7 @@ Source: [`packages/interaction/user-approval/src/index.ts:32`](../packages/inter
 
 Types: [StreamChunk](subsystems/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:246`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:289`](../packages/core/session/src/types.ts)
 
 <a id="assistantmessage--surface"></a>
 
@@ -237,7 +237,7 @@ Source: [`packages/core/session/src/types.ts:246`](../packages/core/session/src/
 
 Types: [TokenUsage](subsystems/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:257`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:300`](../packages/core/session/src/types.ts)
 
 ### `command/*`
 
@@ -256,11 +256,11 @@ Source: [`packages/core/session/src/types.ts:257`](../packages/core/session/src/
   commandId: CommandId
   kind: 'success' | 'error'
   text?: string
-  sourceEventSeq?: number
+  sourceEventSeq?: import('@deepseek-ai/dsh-session/types').SessionSeq
 }
 ```
 
-Source: [`packages/interaction/commands/src/types.ts:103`](../packages/interaction/commands/src/types.ts)
+Source: [`packages/interaction/commands/src/types.ts:104`](../packages/interaction/commands/src/types.ts)
 
 <a id="commandrun--log-only"></a>
 
@@ -280,7 +280,7 @@ Source: [`packages/interaction/commands/src/types.ts:103`](../packages/interacti
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/interaction/commands/src/types.ts:96`](../packages/interaction/commands/src/types.ts)
+Source: [`packages/interaction/commands/src/types.ts:97`](../packages/interaction/commands/src/types.ts)
 
 ### `compaction/*`
 
@@ -296,7 +296,7 @@ Source: [`packages/interaction/commands/src/types.ts:96`](../packages/interactio
 'compaction/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
 ```
 
-Source: [`packages/compaction/compaction/src/types.ts:71`](../packages/compaction/compaction/src/types.ts)
+Source: [`packages/compaction/compaction/src/types.ts:72`](../packages/compaction/compaction/src/types.ts)
 
 <a id="compactionprune--log-only"></a>
 
@@ -314,15 +314,15 @@ Source: [`packages/compaction/compaction/src/types.ts:71`](../packages/compactio
  */
 'compaction/prune': {
   /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
-  shadowedRange: { start: number; end: number }
+  shadowedRange: { start: SessionSeq; end: SessionSeq }
   /** The seqs of all shadowed surface nodes, in surface order. */
-  shadowedSeqs: number[]
+  shadowedSeqs: SessionSeq[]
   /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
   shadowedTokenCount: number
 }
 ```
 
-Source: [`packages/compaction/compaction/src/types.ts:81`](../packages/compaction/compaction/src/types.ts)
+Source: [`packages/compaction/compaction/src/types.ts:82`](../packages/compaction/compaction/src/types.ts)
 
 <a id="compactionstart--log-only"></a>
 
@@ -337,7 +337,7 @@ Source: [`packages/compaction/compaction/src/types.ts:81`](../packages/compactio
 'compaction/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
 ```
 
-Source: [`packages/compaction/compaction/src/types.ts:23`](../packages/compaction/compaction/src/types.ts)
+Source: [`packages/compaction/compaction/src/types.ts:24`](../packages/compaction/compaction/src/types.ts)
 
 <a id="compactionsummary--log-only"></a>
 
@@ -357,8 +357,8 @@ Source: [`packages/compaction/compaction/src/types.ts:23`](../packages/compactio
   compactionId: CompactionId
   sourceCommandId?: CommandId
   summary: ContentBlock[]
-  shadowedRange: { start: number; end: number }
-  shadowedSeqs: number[]
+  shadowedRange: { start: SessionSeq; end: SessionSeq }
+  shadowedSeqs: SessionSeq[]
   shadowedTokenCount: number
   /** The provider route that wrote the summary. */
   provider: string
@@ -391,7 +391,7 @@ Source: [`packages/compaction/compaction/src/types.ts:23`](../packages/compactio
 
 Types: [ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
-Source: [`packages/compaction/compaction/src/types.ts:33`](../packages/compaction/compaction/src/types.ts)
+Source: [`packages/compaction/compaction/src/types.ts:34`](../packages/compaction/compaction/src/types.ts)
 
 ### `feedback/*`
 
@@ -563,7 +563,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:46`](../packages/plan/plan-mode/s
 'request/context': RequestContext
 ```
 
-Source: [`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:339`](../packages/core/session/src/types.ts)
 
 <a id="requestheader--log-only"></a>
 
@@ -582,7 +582,7 @@ Source: [`packages/core/session/src/types.ts:296`](../packages/core/session/src/
 }
 ```
 
-Source: [`packages/core/session/src/types.ts:286`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:329`](../packages/core/session/src/types.ts)
 
 ### `sandbox/*`
 
@@ -657,7 +657,7 @@ Source: [`packages/schedule/schedule/src/types.ts:219`](../packages/schedule/sch
 'session/end-seed': Record<string, never>
 ```
 
-Source: [`packages/core/session/src/types.ts:319`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:362`](../packages/core/session/src/types.ts)
 
 <a id="sessiontitle--log-only"></a>
 
@@ -673,7 +673,7 @@ Source: [`packages/core/session/src/types.ts:319`](../packages/core/session/src/
 
 Types: [SessionTitleEventData](subsystems/session-title.md)
 
-Source: [`packages/session/session-title/src/index.ts:76`](../packages/session/session-title/src/index.ts)
+Source: [`packages/session/session-title/src/index.ts:77`](../packages/session/session-title/src/index.ts)
 
 <a id="sessiontitle-llm-request--log-only"></a>
 
@@ -686,7 +686,7 @@ Source: [`packages/session/session-title/src/index.ts:76`](../packages/session/s
 
 Types: [SessionTitleLlmRequestEventData](subsystems/session-title.md)
 
-Source: [`packages/session/session-title-llm/src/index.ts:44`](../packages/session/session-title-llm/src/index.ts)
+Source: [`packages/session/session-title-llm/src/index.ts:45`](../packages/session/session-title-llm/src/index.ts)
 
 ### `session-log-deepseek/*`
 
@@ -700,11 +700,11 @@ Source: [`packages/session/session-title-llm/src/index.ts:44`](../packages/sessi
   /** Session identity the accepted delivery carried; inherited fork markers retain the parent's id. */
   sessionId: import('@deepseek-ai/dsh-session/types').SessionId
   /** Last canonical event included in the accepted request. */
-  throughSeq: number
+  throughSeq: import('@deepseek-ai/dsh-session/types').SessionSeq
 }
 ```
 
-Source: [`packages/session/session-log-deepseek/src/types.ts:26`](../packages/session/session-log-deepseek/src/types.ts)
+Source: [`packages/session/session-log-deepseek/src/types.ts:57`](../packages/session/session-log-deepseek/src/types.ts)
 
 ### `step/*`
 
@@ -717,7 +717,7 @@ Source: [`packages/session/session-log-deepseek/src/types.ts:26`](../packages/se
 'step/end': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:236`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
 
 <a id="stepstart--log-only"></a>
 
@@ -728,7 +728,7 @@ Source: [`packages/core/session/src/types.ts:236`](../packages/core/session/src/
 'step/start': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:234`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts)
 
 ### `subagent/*`
 
@@ -859,7 +859,7 @@ Source: [`packages/todo/tool-todo/src/types.ts:31`](../packages/todo/tool-todo/s
 
 Types: [ToolCallId](subsystems/core.md)
 
-Source: [`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:306`](../packages/core/session/src/types.ts)
 
 <a id="toolcode-dispatch--log-only"></a>
 
@@ -934,7 +934,7 @@ Source: [`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types
 }
 ```
 
-Source: [`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:318`](../packages/core/session/src/types.ts)
 
 ### `tool-workflow/*`
 
@@ -1014,7 +1014,7 @@ Source: [`packages/workflow/tool-workflow/src/types.ts:47`](../packages/workflow
 
 Types: [TurnEndReason](subsystems/session.md)
 
-Source: [`packages/core/session/src/types.ts:232`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
 
 <a id="turnstart--log-only"></a>
 
@@ -1030,7 +1030,7 @@ Source: [`packages/core/session/src/types.ts:232`](../packages/core/session/src/
 'turn/start': { turn: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:223`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts)
 
 ### `user/*`
 
@@ -1049,7 +1049,7 @@ Source: [`packages/core/session/src/types.ts:223`](../packages/core/session/src/
 'user/message': UserMessage
 ```
 
-Source: [`packages/core/session/src/types.ts:244`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:287`](../packages/core/session/src/types.ts)
 
 ### `web/*`
 
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 9d8fc88a44..4014fd2c10 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -42,7 +42,7 @@ export type SurfaceEventType =
  */
 export type SurfaceOp =
   | 'append'
-  | { op: 'replace'; start: number; end: number }
+  | { op: 'replace'; start: SessionSeq; end: SessionSeq }
 
 /**
  * One immutable entry in the session log.
@@ -61,7 +61,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
   [K in SessionEventType]: {
     type: K
     /** Monotonic sequence number within the session. */
-    seq: number
+    seq: SessionSeq
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
@@ -85,14 +85,14 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * provider stream; when the field is absent, the event does not record which
      * earlier events produced the message.
      */
-    sourceEventSeqs?: number[]
+    sourceEventSeqs?: SessionSeq[]
     /** How this event entered the surface; absent for non-surface events. */
     surfaceOp?: SurfaceOp
   } : object)
 }[T]
 ```
 
-来源：[`packages/core/session/src/types.ts:323`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:330`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:359`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:391`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:366`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:373`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:402`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:434`](../packages/core/session/src/types.ts)
 
 ## 事件
 
@@ -217,7 +217,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[StreamChunk](subsystems/llm-streaming.zh.md)
 
-来源：[`packages/core/session/src/types.ts:246`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:289`](../packages/core/session/src/types.ts)
 
 <a id="assistantmessage--surface"></a>
 
@@ -239,7 +239,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[TokenUsage](subsystems/llm-streaming.zh.md)
 
-来源：[`packages/core/session/src/types.ts:257`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:300`](../packages/core/session/src/types.ts)
 
 ### `command/*`
 
@@ -258,11 +258,11 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
   commandId: CommandId
   kind: 'success' | 'error'
   text?: string
-  sourceEventSeq?: number
+  sourceEventSeq?: import('@deepseek-ai/dsh-session/types').SessionSeq
 }
 ```
 
-来源：[`packages/interaction/commands/src/types.ts:103`](../packages/interaction/commands/src/types.ts)
+来源：[`packages/interaction/commands/src/types.ts:104`](../packages/interaction/commands/src/types.ts)
 
 <a id="commandrun--log-only"></a>
 
@@ -282,7 +282,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-来源：[`packages/interaction/commands/src/types.ts:96`](../packages/interaction/commands/src/types.ts)
+来源：[`packages/interaction/commands/src/types.ts:97`](../packages/interaction/commands/src/types.ts)
 
 ### `compaction/*`
 
@@ -298,7 +298,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'compaction/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
 ```
 
-来源：[`packages/compaction/compaction/src/types.ts:71`](../packages/compaction/compaction/src/types.ts)
+来源：[`packages/compaction/compaction/src/types.ts:72`](../packages/compaction/compaction/src/types.ts)
 
 <a id="compactionprune--log-only"></a>
 
@@ -316,15 +316,15 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  */
 'compaction/prune': {
   /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
-  shadowedRange: { start: number; end: number }
+  shadowedRange: { start: SessionSeq; end: SessionSeq }
   /** The seqs of all shadowed surface nodes, in surface order. */
-  shadowedSeqs: number[]
+  shadowedSeqs: SessionSeq[]
   /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
   shadowedTokenCount: number
 }
 ```
 
-来源：[`packages/compaction/compaction/src/types.ts:81`](../packages/compaction/compaction/src/types.ts)
+来源：[`packages/compaction/compaction/src/types.ts:82`](../packages/compaction/compaction/src/types.ts)
 
 <a id="compactionstart--log-only"></a>
 
@@ -339,7 +339,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'compaction/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
 ```
 
-来源：[`packages/compaction/compaction/src/types.ts:23`](../packages/compaction/compaction/src/types.ts)
+来源：[`packages/compaction/compaction/src/types.ts:24`](../packages/compaction/compaction/src/types.ts)
 
 <a id="compactionsummary--log-only"></a>
 
@@ -359,8 +359,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
   compactionId: CompactionId
   sourceCommandId?: CommandId
   summary: ContentBlock[]
-  shadowedRange: { start: number; end: number }
-  shadowedSeqs: number[]
+  shadowedRange: { start: SessionSeq; end: SessionSeq }
+  shadowedSeqs: SessionSeq[]
   shadowedTokenCount: number
   /** The provider route that wrote the summary. */
   provider: string
@@ -393,7 +393,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[ContentBlock](subsystems/core.zh.md) · [TokenUsage](subsystems/llm-streaming.zh.md)
 
-来源：[`packages/compaction/compaction/src/types.ts:33`](../packages/compaction/compaction/src/types.ts)
+来源：[`packages/compaction/compaction/src/types.ts:34`](../packages/compaction/compaction/src/types.ts)
 
 ### `feedback/*`
 
@@ -565,7 +565,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'request/context': RequestContext
 ```
 
-来源：[`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:339`](../packages/core/session/src/types.ts)
 
 <a id="requestheader--log-only"></a>
 
@@ -584,7 +584,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/core/session/src/types.ts:286`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:329`](../packages/core/session/src/types.ts)
 
 ### `sandbox/*`
 
@@ -659,7 +659,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'session/end-seed': Record<string, never>
 ```
 
-来源：[`packages/core/session/src/types.ts:319`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:362`](../packages/core/session/src/types.ts)
 
 <a id="sessiontitle--log-only"></a>
 
@@ -675,7 +675,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[SessionTitleEventData](subsystems/session-title.zh.md)
 
-来源：[`packages/session/session-title/src/index.ts:76`](../packages/session/session-title/src/index.ts)
+来源：[`packages/session/session-title/src/index.ts:77`](../packages/session/session-title/src/index.ts)
 
 <a id="sessiontitle-llm-request--log-only"></a>
 
@@ -688,7 +688,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[SessionTitleLlmRequestEventData](subsystems/session-title.zh.md)
 
-来源：[`packages/session/session-title-llm/src/index.ts:44`](../packages/session/session-title-llm/src/index.ts)
+来源：[`packages/session/session-title-llm/src/index.ts:45`](../packages/session/session-title-llm/src/index.ts)
 
 ### `session-log-deepseek/*`
 
@@ -702,11 +702,11 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
   /** Session identity the accepted delivery carried; inherited fork markers retain the parent's id. */
   sessionId: import('@deepseek-ai/dsh-session/types').SessionId
   /** Last canonical event included in the accepted request. */
-  throughSeq: number
+  throughSeq: import('@deepseek-ai/dsh-session/types').SessionSeq
 }
 ```
 
-来源：[`packages/session/session-log-deepseek/src/types.ts:26`](../packages/session/session-log-deepseek/src/types.ts)
+来源：[`packages/session/session-log-deepseek/src/types.ts:57`](../packages/session/session-log-deepseek/src/types.ts)
 
 ### `step/*`
 
@@ -719,7 +719,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'step/end': { turn: number; step: number }
 ```
 
-来源：[`packages/core/session/src/types.ts:236`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
 
 <a id="stepstart--log-only"></a>
 
@@ -730,7 +730,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'step/start': { turn: number; step: number }
 ```
 
-来源：[`packages/core/session/src/types.ts:234`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts)
 
 ### `subagent/*`
 
@@ -861,7 +861,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[ToolCallId](subsystems/core.zh.md)
 
-来源：[`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:306`](../packages/core/session/src/types.ts)
 
 <a id="toolcode-dispatch--log-only"></a>
 
@@ -936,7 +936,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:318`](../packages/core/session/src/types.ts)
 
 ### `tool-workflow/*`
 
@@ -1016,7 +1016,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[TurnEndReason](subsystems/session.zh.md)
 
-来源：[`packages/core/session/src/types.ts:232`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
 
 <a id="turnstart--log-only"></a>
 
@@ -1032,7 +1032,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'turn/start': { turn: number }
 ```
 
-来源：[`packages/core/session/src/types.ts:223`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts)
 
 ### `user/*`
 
@@ -1051,7 +1051,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'user/message': UserMessage
 ```
 
-来源：[`packages/core/session/src/types.ts:244`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:287`](../packages/core/session/src/types.ts)
 
 ### `web/*`
 
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index 17bf825901..50447d69ca 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: f3760558b04253701915a240375f13e096bc0c51
-commands.zh.md: 2b4377b76b55203d84a956f66879ab2c50a9fd23
+commands.md: 46d3b736afd3a72d1119c9744cd592a86b9cbc29
+commands.zh.md: db8d6e722e3a1742887aaa4023ab67b9ed914552
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index f3760558b0..46d3b736af 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -83,7 +83,7 @@ type CommandResult =
     readonly kind: 'success'
     readonly text?: string
     /** Earlier authoritative domain event that owns a richer presentation. */
-    readonly sourceEventSeq?: number
+    readonly sourceEventSeq?: SessionSeq
   }
   | { readonly kind: 'error'; readonly text: string }
 ```
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index 2b4377b76b..db8d6e722e 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -83,7 +83,7 @@ type CommandResult =
     readonly kind: 'success'
     readonly text?: string
     /** Earlier authoritative domain event that owns a richer presentation. */
-    readonly sourceEventSeq?: number
+    readonly sourceEventSeq?: SessionSeq
   }
   | { readonly kind: 'error'; readonly text: string }
 ```
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 4a2a20d79a..93a8216e4b 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 03642b32cc3cb3caf743d908e9c988c1a3c8fa1e
-compaction.zh.md: af37c4824cc4b01515400049525fbd7b91d018f3
+compaction.md: b49957a5f476a02ccd12b791f287a9675073c0ae
+compaction.zh.md: 4b4c6845b8ff48bce019b352a811f968628cbdbf
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 03642b32cc..b49957a5f4 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -34,11 +34,11 @@ interface CompactionResult {
   /** Human command that initiated this compaction, when it was manual. */
   sourceCommandId?: CommandId
   /** The seq of the appended `compaction/start` event. */
-  startSeq: number
+  startSeq: SessionSeq
   /** The seq of the appended `compaction/summary` event. */
-  summarySeq: number
+  summarySeq: SessionSeq
   /** The seq of the appended `compaction/end` event. */
-  endSeq: number
+  endSeq: SessionSeq
   /** The summary content blocks produced by the backend. */
   summary: ContentBlock[]
   /**
@@ -49,9 +49,9 @@ interface CompactionResult {
    * can be GREATER than `end`. {@link CompactionResult.shadowedSeqs} is the
    * authoritative set of shadowed nodes, in surface order.
    */
-  shadowedRange: { start: number; end: number }
+  shadowedRange: { start: SessionSeq; end: SessionSeq }
   /** The seqs of all shadowed surface nodes, in surface order. */
-  shadowedSeqs: number[]
+  shadowedSeqs: SessionSeq[]
   /** Estimated token count of the shadowed content. */
   shadowedTokenCount: number
 }
@@ -95,9 +95,9 @@ The optional tool-result pruning service reports each durable content replacemen
 /** Cited source event and size accounting for one landed surface replacement. */
 interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
-  readonly originalSeq: number
+  readonly originalSeq: SessionSeq
   /** Newly appended pruned tool-result event. */
-  readonly replacementSeq: number
+  readonly replacementSeq: SessionSeq
   /** Tool call shared by the original and replacement. */
   readonly callId: ToolCallId
   /** Original text size in Unicode code points. */
@@ -187,10 +187,10 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sour
  * @throws when compaction is active or the range is missing, reversed, or unbalanced.
  * @returns the appended event seqs, summary, replaced range, and token accounting.
  */
-abstract compactRegion( start: number, end: number, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
+abstract compactRegion( start: SessionSeq, end: SessionSeq, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Types: [CommandId](commands.md)
+Types: [CommandId](commands.md) · [SessionSeq](session.md)
 
 Source: [`packages/compaction/compaction/src/index.ts`](../../packages/compaction/compaction/src/index.ts)
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index af37c4824c..4b4c6845b8 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -34,11 +34,11 @@ interface CompactionResult {
   /** Human command that initiated this compaction, when it was manual. */
   sourceCommandId?: CommandId
   /** The seq of the appended `compaction/start` event. */
-  startSeq: number
+  startSeq: SessionSeq
   /** The seq of the appended `compaction/summary` event. */
-  summarySeq: number
+  summarySeq: SessionSeq
   /** The seq of the appended `compaction/end` event. */
-  endSeq: number
+  endSeq: SessionSeq
   /** The summary content blocks produced by the backend. */
   summary: ContentBlock[]
   /**
@@ -49,9 +49,9 @@ interface CompactionResult {
    * can be GREATER than `end`. {@link CompactionResult.shadowedSeqs} is the
    * authoritative set of shadowed nodes, in surface order.
    */
-  shadowedRange: { start: number; end: number }
+  shadowedRange: { start: SessionSeq; end: SessionSeq }
   /** The seqs of all shadowed surface nodes, in surface order. */
-  shadowedSeqs: number[]
+  shadowedSeqs: SessionSeq[]
   /** Estimated token count of the shadowed content. */
   shadowedTokenCount: number
 }
@@ -95,9 +95,9 @@ type ManualCompactionErrorCode =
 /** Cited source event and size accounting for one landed surface replacement. */
 interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
-  readonly originalSeq: number
+  readonly originalSeq: SessionSeq
   /** Newly appended pruned tool-result event. */
-  readonly replacementSeq: number
+  readonly replacementSeq: SessionSeq
   /** Tool call shared by the original and replacement. */
   readonly callId: ToolCallId
   /** Original text size in Unicode code points. */
@@ -187,10 +187,10 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sour
  * @throws when compaction is active or the range is missing, reversed, or unbalanced.
  * @returns the appended event seqs, summary, replaced range, and token accounting.
  */
-abstract compactRegion( start: number, end: number, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
+abstract compactRegion( start: SessionSeq, end: SessionSeq, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Types: [CommandId](commands.zh.md)
+Types: [CommandId](commands.zh.md) · [SessionSeq](session.zh.md)
 
 Source: [`packages/compaction/compaction/src/index.ts`](../../packages/compaction/compaction/src/index.ts)
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 6f08cfb825..a60f0c783f 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 124d30a5abeddd81edd2eb03a9bb213487b6a38e
-core.zh.md: c2d67eabb3b223d3f1d20c42f01280f16656ebef
+core.md: a59a692573c2e2756e60626268314a8ade6c546e
+core.zh.md: acea4966a30ab03c24f1aea9bcd2d33a6271a28d
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 124d30a5ab..a59a692573 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -46,7 +46,7 @@ interface AgentHandle {
 }
 ```
 
-`CreateAgentOptions` carries the shared identity and everything a fresh agent needs before publication: session metadata (`meta` — validated `cwd`, fork lineage, seed boundary, origin classification, delegation depth), an optional `seed` replay prefix for forks, per-agent `AgentOptions`, a creation-only cancellation `signal`, and `setup`. `ResumeAgentOptions` is the persisted-identity counterpart: `resumeSessionId`, `agentOptions`, `signal`, and `setup`. The `setup` callback (`AgentSetup`) composes the agent's scoped world while both ids are still unpublished — everything registered through `agentCtx` exists before `agent/created` and the first prompt assembly — and may return a synchronous commit invoked immediately before publication; a setup rejection, commit throw, or owner disposal rolls the transaction back without publishing either id.
+`CreateAgentOptions` carries the shared identity and everything a fresh agent needs before publication: session metadata (`meta` — validated `cwd`, fork lineage, the `isSeeded` marker, origin classification, delegation depth, and `agentPreset`), the exact fork cut in sibling field `inheritedEventCount`, an optional `seed` replay prefix, per-agent `AgentOptions`, a creation-only cancellation `signal`, and `setup`. `ResumeAgentOptions` is the persisted-identity counterpart: `resumeSessionId`, `agentOptions`, `signal`, and `setup`. The `setup` callback (`AgentSetup`) composes the agent's scoped world while both ids are still unpublished — everything registered through `agentCtx` exists before `agent/created` and the first prompt assembly — and may return a synchronous commit invoked immediately before publication; a setup rejection, commit throw, or owner disposal rolls the transaction back without publishing either id.
 
 `AgentFactory` is the creation interface behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers use `ctx.agents` without depending on the concrete loop package. The exact `create`/`resume` signatures and rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index c2d67eabb3..acea4966a3 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -48,7 +48,7 @@ interface AgentHandle {
 }
 ```
 
-`CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应项：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose（资源释放）都会回滚事务，两个 id 均不发布。
+`CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、`isSeeded` 标记、来源分类、委派深度与 `agentPreset`）、同级字段 `inheritedEventCount` 所表示的精确 fork cut、可选的 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应项：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose（资源释放）都会回滚事务，两个 id 均不发布。
 
 `AgentFactory` 是注册表背后的创建接口：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方使用 `ctx.agents` 时无需依赖具体循环包。确切的 `create`/`resume` 签名及回滚约定见下方[生成区块](#ctxagents--agentregistry)。
 
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 757092f100..ec456511f9 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: cd7eaa126ea16b17526223498d1fa1591792747c
-persistence.zh.md: c96aa87f738e5607c699dfa97e6d2b237767b76d
+persistence.md: b61ddee8d12854b330b967a09a1a685d763f0041
+persistence.zh.md: 08cc35d987360138ec096b70f8c6b11b5cba4c55
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index cd7eaa126e..b61ddee8d1 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -40,7 +40,7 @@ interface SessionLocation {
 
 ## `SessionHeader` — metadata beside the log
 
-Per-session metadata travels **separately** from the event log: format version, cwd, lineage, and the seed boundary are storage concerns, not conversation events, so they stay out of `SessionEventMap` and never reach `deriveMessages()`. The header is attached to a `Session` via `session.header`.
+Per-session metadata travels **separately** from the event log: the header carries format version, cwd, and the `isSeeded` lineage bit, while body-bearing storage values carry the exact inherited cut beside it. Neither belongs to `SessionEventMap` or reaches `deriveMessages()`. The logical header is attached through `session.header`; the Session exposes its cut as `inheritedEventCount`.
 
 Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
 
@@ -64,10 +64,10 @@ interface SessionHeader {
   /** The session this one was forked from (seed lineage), if any. */
   readonly parentSession?: SessionId
   /**
-   * How many leading events were inherited through a seed. Persisting this
-   * boundary lets resume and replay distinguish parent history from child work.
+   * Whether this Session contains a fork-inherited event prefix. The exact prefix
+   * length is Session state rather than ordinary header metadata.
    */
-  readonly seedLength?: number
+  readonly isSeeded: boolean
   /**
    * Coarse product classification for a session created as a subagent child.
    * This is presentation metadata, not proof that the child is continuable.
@@ -95,7 +95,7 @@ A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupp
 
 ## `CreateSessionOptions` — seeding and metadata
 
-Creating a `Session` through the store takes a `seed` (initial replay or fork history) and `meta` (the storage-level fields the store folds into a `SessionHeader`). The store fills in `version`/`id` and defaults `createdAt`; the caller may supply the validated absolute `cwd`, the `parentSession` lineage, the `seedLength` seed boundary, the optional coarse `origin`, the `delegationDepth`, the `agentPreset` the agent was composed from, and an existing `createdAt`. `origin: 'subagent'` lets product navigation hide duplicate child rows; it does not prove that a descriptor is valid or that the child can resume.
+Creating a `Session` through the store takes a `seed` (initial replay or fork history), an optional exact `inheritedEventCount`, and `meta` (the storage-level fields the store folds into a `SessionHeader`). The store fills in `version`/`id` and defaults `createdAt`; the caller may supply the validated absolute `cwd`, `parentSession` lineage, `isSeeded` lineage bit, optional coarse `origin`, `delegationDepth`, `agentPreset`, and an existing `createdAt`. A seeded creation requires both an explicit seed and exact cut because child-owned setup events may follow the inherited prefix. `origin: 'subagent'` lets product navigation hide duplicate child rows; it does not prove that a descriptor is valid or that the child can resume.
 
 ```ts type-equiv
 /**
@@ -107,14 +107,19 @@ interface CreateSessionOptions {
   /** Initial replay or fork history supplied at construction. */
   readonly seed?: readonly SessionEvent[]
   /**
-   * Storage metadata read once before publication. `seedLength` is explicit
-   * because a resumed seed contains the full stored log, not only its inherited prefix.
+   * Exact fork-inherited prefix length when `meta.isSeeded` is true. A
+   * constructor seed may also contain child-owned setup events after this cut.
+   */
+  readonly inheritedEventCount?: SessionLogOffset
+  /**
+   * Storage metadata read once before publication. `isSeeded` marks fork
+   * lineage; supplying replay history alone does not make it inherited.
    */
   readonly meta?: {
     readonly cwd?: string
     readonly parentSession?: SessionId
     readonly createdAt?: number
-    readonly seedLength?: number
+    readonly isSeeded?: boolean
     readonly origin?: 'subagent'
     readonly delegationDepth?: number
     readonly agentPreset?: string
@@ -122,7 +127,21 @@ interface CreateSessionOptions {
 }
 ```
 
-Replay/fork is therefore `ctx.sessions.create(id, { seed: seedEvents })`; resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
+Plain replay is `ctx.sessions.create(id, { seed: seedEvents })`; a fork additionally supplies `inheritedEventCount` and `meta.isSeeded: true`. Resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
+
+## `SessionStorageMetadata` — logical header and inherited cut
+
+Every persistence result that reads a Session body carries `SessionStorageMetadata`: the current logical header plus the separately validated inherited-event cut. Header-only listing intentionally returns only `SessionHeader`.
+
+```ts type-equiv
+/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
+interface SessionStorageMetadata {
+  /** Validated immutable Session header. */
+  readonly meta: SessionHeader
+  /** Number of leading events inherited from the Session's fork parent. */
+  readonly inheritedEventCount: SessionLogOffset
+}
+```
 
 ## `SessionRawArtifact` — verbatim stored artifact text
 
@@ -130,9 +149,7 @@ A backend's own artifact text for one session, byte-identical to what it durably
 
 ```ts type-equiv
 /** A backend's own raw artifact text for one session, verbatim. */
-interface SessionRawArtifact {
-  /** The session header parsed from the artifact's own first line. */
-  readonly meta: SessionHeader
+interface SessionRawArtifact extends SessionStorageMetadata {
   /** The artifact's base filename on disk, without any physical encoding suffix. */
   readonly filename: string
   /** The artifact's full text content, decoded from the backend's physical encoding. */
@@ -154,6 +171,8 @@ interface RestoredSessionOptions {
   readonly seed: SessionEvent[]
   /** Fresh detached storage metadata to validate and freeze in place. */
   readonly meta: SessionHeader
+  /** Exact number of fork-inherited leading events decoded from storage. */
+  readonly inheritedEventCount: SessionLogOffset
   /** Select the persistence ownership-transfer path. */
   readonly seedSource: 'persistence'
 }
@@ -198,14 +217,26 @@ declare class SessionPreparation implements Disposable {
 
 ```ts type-equiv
 /** Immutable logical session prepared from persistence or a live owner. */
-interface SessionInspection {
-  /** Validated immutable session metadata. */
-  readonly meta: SessionHeader
+interface SessionInspection extends SessionStorageMetadata {
   /** Validated contiguous logical event log. */
   readonly events: readonly SessionEvent[]
 }
 ```
 
+## Detached stored-log suffixes
+
+`readFrom` returns a detached `SessionEventSuffix` anchored by the requested `fromSeq`. Its event list may start above zero or be empty, so it is not a complete `SessionInspection` and must not be restored as a whole Session.
+
+```ts type-equiv
+/** Detached logical suffix returned by one explicit stored-log offset read. */
+interface SessionEventSuffix extends SessionStorageMetadata {
+  /** First requested log offset; {@link events} contains only seqs at or after it. */
+  readonly fromSeq: SessionLogOffset
+  /** Valid contiguous stored events at or after {@link fromSeq}; not a complete Session log when the offset is nonzero. */
+  readonly events: readonly SessionEvent[]
+}
+```
+
 ## Lightweight source revisions
 
 Consumers of derived state compare a cheap opaque revision before loading a full event log. The persistence backend owns its representation and changes it transactionally with append or mutating load repair; callers compare it only for equality.
@@ -281,8 +312,10 @@ readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | unde
  * created-but-never-appended session is absent from {@link list}
  * — abandoned sessions leave nothing behind.
  * @param meta - the immutable header (id, version, cwd, lineage) to record.
+ * @param inheritedEventCount - exact fork-inherited prefix length. Required
+ * for a seeded header and omitted only for an unseeded header.
  */
-abstract create(meta: SessionHeader): Promise<void>
+abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>
 
 /**
  * Ensure a live session has a durable header even when it has no events.
@@ -297,6 +330,8 @@ ensureMaterialized(_session: Session): Promise<void>
  * seq contracts: the first event's `seq` MUST equal the stored next-seq
  * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
  * serializable `event.data` with an error naming the offending event type.
+ * A seeded session's first materializing batch must reach its complete
+ * inherited prefix.
  * @param id - the session the batch belongs to.
  * @param events - the contiguous batch to persist, in seq order.
  */
@@ -371,11 +406,11 @@ abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSes
  * forward. The primitive bounds what is returned and refolded, not every
  * backend's physical read.
  * @param id - the persisted session to read.
- * @param fromSeq - first event seq to include; a non-negative safe integer.
+ * @param fromSeq - first event offset to include.
  * @param signal - optional cancellation for queued and backend read work.
- * @returns the header and the stored events with `seq >= fromSeq`.
+ * @returns storage metadata, the requested offset, and stored events with `seq >= fromSeq`.
  */
-abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>
 
 /**
  * Lightweight listing from metadata, without a full-log parse.
@@ -397,7 +432,7 @@ abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
 abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [Session](session.md) · [SessionEvent](session.md) · [SessionId](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md) · [SessionId](core.md) · [SessionLogOffset](session.md)
 
 Source: [`packages/session/session-persistence/src/index.ts`](../../packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index c96aa87f73..08cc35d987 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -40,7 +40,7 @@ interface SessionLocation {
 
 ## `SessionHeader`：日志旁的元数据
 
-每个会话的元数据与事件日志**分开**存储：格式版本、cwd、血统与 seed 边界是存储层关注点而非对话事件，因此不进入 `SessionEventMap`，也不会到达 `deriveMessages()`。header 通过 `session.header` 附加到 `Session` 上。
+每个会话的元数据与事件日志**分开**存储：header 携带格式版本、cwd 与 `isSeeded` 谱系 bit，含正文的存储值则在其旁边单独携带精确 inherited cut。二者都不进入 `SessionEventMap`，也不会到达 `deriveMessages()`。logical header 通过 `session.header` 附加，Session 则以 `inheritedEventCount` 暴露其 cut。
 
 源码：[`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
 
@@ -64,10 +64,10 @@ interface SessionHeader {
   /** The session this one was forked from (seed lineage), if any. */
   readonly parentSession?: SessionId
   /**
-   * How many leading events were inherited through a seed. Persisting this
-   * boundary lets resume and replay distinguish parent history from child work.
+   * Whether this Session contains a fork-inherited event prefix. The exact prefix
+   * length is Session state rather than ordinary header metadata.
    */
-  readonly seedLength?: number
+  readonly isSeeded: boolean
   /**
    * Coarse product classification for a session created as a subagent child.
    * This is presentation metadata, not proof that the child is continuable.
@@ -95,7 +95,7 @@ interface SessionHeader {
 
 ## `CreateSessionOptions`：seed 与元数据
 
-通过 store 创建 `Session` 时会接收 `seed`（初始回放或 fork 历史）与 `meta`（store 整合进 `SessionHeader` 的存储层字段）。store 填充 `version`/`id` 并为 `createdAt` 提供默认值；调用方可以提供已校验的绝对 `cwd`、`parentSession` 谱系、`seedLength` 种子边界、可选的粗粒度 `origin`、`delegationDepth`、用于组装该 agent（智能体）的 `agentPreset` 以及已有的 `createdAt`。`origin: 'subagent'` 让产品导航能够隐藏重复的 child 行；它不证明描述符有效，也不证明 child 可以恢复。
+通过 store 创建 `Session` 时会接收 `seed`（初始回放或 fork 历史）、可选的精确 `inheritedEventCount` 与 `meta`（store 整合进 `SessionHeader` 的存储层字段）。store 填充 `version`/`id` 并为 `createdAt` 提供默认值；调用方可以提供已校验的绝对 `cwd`、`parentSession` 谱系、`isSeeded` 谱系标记、可选的粗粒度 `origin`、`delegationDepth`、用于组装该 agent（智能体）的 `agentPreset` 以及已有的 `createdAt`。seeded 创建必须同时显式提供 seed 与精确 cut，因为继承前缀之后还可能存在 child-owned setup event。`origin: 'subagent'` 让产品导航能够隐藏重复的 child 行；它不证明描述符有效，也不证明 child 可以恢复。
 
 ```ts type-equiv
 /**
@@ -107,14 +107,19 @@ interface CreateSessionOptions {
   /** Initial replay or fork history supplied at construction. */
   readonly seed?: readonly SessionEvent[]
   /**
-   * Storage metadata read once before publication. `seedLength` is explicit
-   * because a resumed seed contains the full stored log, not only its inherited prefix.
+   * Exact fork-inherited prefix length when `meta.isSeeded` is true. A
+   * constructor seed may also contain child-owned setup events after this cut.
+   */
+  readonly inheritedEventCount?: SessionLogOffset
+  /**
+   * Storage metadata read once before publication. `isSeeded` marks fork
+   * lineage; supplying replay history alone does not make it inherited.
    */
   readonly meta?: {
     readonly cwd?: string
     readonly parentSession?: SessionId
     readonly createdAt?: number
-    readonly seedLength?: number
+    readonly isSeeded?: boolean
     readonly origin?: 'subagent'
     readonly delegationDepth?: number
     readonly agentPreset?: string
@@ -122,7 +127,21 @@ interface CreateSessionOptions {
 }
 ```
 
-因此，回放/fork 的调用方式为 `ctx.sessions.create(id, { seed: seedEvents })`；将一个*持久化*会话恢复为活跃 agent 的调用方式为 `ctx.agents.resume({ resumeSessionId })`。
+因此，普通回放的调用方式为 `ctx.sessions.create(id, { seed: seedEvents })`；fork 还会提供 `inheritedEventCount` 与 `meta.isSeeded: true`。将一个*持久化*会话恢复为活跃 agent 的调用方式为 `ctx.agents.resume({ resumeSessionId })`。
+
+## `SessionStorageMetadata`：逻辑 header 与继承 cut
+
+每个读取 Session 正文的持久化结果都携带 `SessionStorageMetadata`：当前逻辑 header，以及单独校验的继承事件 cut。仅 header 的列表操作有意只返回 `SessionHeader`。
+
+```ts type-equiv
+/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
+interface SessionStorageMetadata {
+  /** Validated immutable Session header. */
+  readonly meta: SessionHeader
+  /** Number of leading events inherited from the Session's fork parent. */
+  readonly inheritedEventCount: SessionLogOffset
+}
+```
 
 ## `SessionRawArtifact`——逐字存储工件文本
 
@@ -130,9 +149,7 @@ interface CreateSessionOptions {
 
 ```ts type-equiv
 /** A backend's own raw artifact text for one session, verbatim. */
-interface SessionRawArtifact {
-  /** The session header parsed from the artifact's own first line. */
-  readonly meta: SessionHeader
+interface SessionRawArtifact extends SessionStorageMetadata {
   /** The artifact's base filename on disk, without any physical encoding suffix. */
   readonly filename: string
   /** The artifact's full text content, decoded from the backend's physical encoding. */
@@ -154,6 +171,8 @@ interface RestoredSessionOptions {
   readonly seed: SessionEvent[]
   /** Fresh detached storage metadata to validate and freeze in place. */
   readonly meta: SessionHeader
+  /** Exact number of fork-inherited leading events decoded from storage. */
+  readonly inheritedEventCount: SessionLogOffset
   /** Select the persistence ownership-transfer path. */
   readonly seedSource: 'persistence'
 }
@@ -198,14 +217,26 @@ declare class SessionPreparation implements Disposable {
 
 ```ts type-equiv
 /** Immutable logical session prepared from persistence or a live owner. */
-interface SessionInspection {
-  /** Validated immutable session metadata. */
-  readonly meta: SessionHeader
+interface SessionInspection extends SessionStorageMetadata {
   /** Validated contiguous logical event log. */
   readonly events: readonly SessionEvent[]
 }
 ```
 
+## 分离的持久日志后缀
+
+`readFrom` 返回以请求的 `fromSeq` 为锚点、与其他状态分离的 `SessionEventSuffix`。其事件列表可能从非零位置开始，也可能为空，因此它不是完整的 `SessionInspection`，不得作为完整 Session 恢复。
+
+```ts type-equiv
+/** Detached logical suffix returned by one explicit stored-log offset read. */
+interface SessionEventSuffix extends SessionStorageMetadata {
+  /** First requested log offset; {@link events} contains only seqs at or after it. */
+  readonly fromSeq: SessionLogOffset
+  /** Valid contiguous stored events at or after {@link fromSeq}; not a complete Session log when the offset is nonzero. */
+  readonly events: readonly SessionEvent[]
+}
+```
+
 ## 轻量源修订号
 
 派生状态的消费方会在加载完整事件日志之前比较一个低开销的不透明修订号。其表示由持久化后端拥有，并随 append 或会修改数据的 load 修复以事务方式改变；调用方仅比较修订号是否相等。
@@ -281,8 +312,10 @@ readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | unde
  * created-but-never-appended session is absent from {@link list}
  * — abandoned sessions leave nothing behind.
  * @param meta - the immutable header (id, version, cwd, lineage) to record.
+ * @param inheritedEventCount - exact fork-inherited prefix length. Required
+ * for a seeded header and omitted only for an unseeded header.
  */
-abstract create(meta: SessionHeader): Promise<void>
+abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>
 
 /**
  * Ensure a live session has a durable header even when it has no events.
@@ -297,6 +330,8 @@ ensureMaterialized(_session: Session): Promise<void>
  * seq contracts: the first event's `seq` MUST equal the stored next-seq
  * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
  * serializable `event.data` with an error naming the offending event type.
+ * A seeded session's first materializing batch must reach its complete
+ * inherited prefix.
  * @param id - the session the batch belongs to.
  * @param events - the contiguous batch to persist, in seq order.
  */
@@ -371,11 +406,11 @@ abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSes
  * forward. The primitive bounds what is returned and refolded, not every
  * backend's physical read.
  * @param id - the persisted session to read.
- * @param fromSeq - first event seq to include; a non-negative safe integer.
+ * @param fromSeq - first event offset to include.
  * @param signal - optional cancellation for queued and backend read work.
- * @returns the header and the stored events with `seq >= fromSeq`.
+ * @returns storage metadata, the requested offset, and stored events with `seq >= fromSeq`.
  */
-abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>
 
 /**
  * Lightweight listing from metadata, without a full-log parse.
@@ -397,7 +432,7 @@ abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
 abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [Session](session.zh.md) · [SessionEvent](session.zh.md) · [SessionId](core.zh.md)
+Types: [Session](session.zh.md) · [SessionEvent](session.zh.md) · [SessionId](core.zh.md) · [SessionLogOffset](session.zh.md)
 
 Source: [`packages/session/session-persistence/src/index.ts`](../../packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/schedule.i18n.yaml b/docs/subsystems/schedule.i18n.yaml
index 37a91f5c75..547a308dd8 100644
--- a/docs/subsystems/schedule.i18n.yaml
+++ b/docs/subsystems/schedule.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 docs/subsystems/schedule.md
-schedule.md: f98cf319d588f805e4630ca572f10c3c45e94b79
-schedule.zh.md: bee816be9cc49943f5815d4d13869b27e30380d5
+schedule.md: 40aa3592dec89fe8daa45beb630076e0476d2b16
+schedule.zh.md: 53a36ee9b51545ca74ac6166ef31d1e002d1f1f2
diff --git a/docs/subsystems/schedule.md b/docs/subsystems/schedule.md
index f98cf319d5..40aa3592de 100644
--- a/docs/subsystems/schedule.md
+++ b/docs/subsystems/schedule.md
@@ -149,7 +149,7 @@ type ScheduleDispatchChange = OneShotScheduleDispatchChange | EveryScheduleDispa
 type ScheduleChange = ScheduleCreateChange | ScheduleDeleteChange | ScheduleDispatchChange
 ```
 
-The strict decoder and fold reject unknown versions, extra fields, reused ids, mismatched one-shot or Every dispatch shapes, and delete or dispatch transitions against inactive records. A normal Session folds its complete event stream. A fork folds only events at or after `SessionHeader.seedLength`, so it retains history without adopting the parent Session's active reminders. The Schedule projection derives that boundary from the immutable header passed to `init(header)`, uses the shared transition, and persists both active records and used-id history so cached restore preserves strict replay. The `schedule/change` declaration and source location are also indexed in the [persistence catalog](../persistence-catalog.md#schedulechange--log-only).
+The strict decoder and fold reject unknown versions, extra fields, reused ids, mismatched one-shot or Every dispatch shapes, and delete or dispatch transitions against inactive records. A normal Session folds its complete event stream. A fork folds only events at or after its exact `inheritedEventCount`, so it retains history without adopting the parent Session's active reminders. Projection initialization receives that cut beside the immutable header, uses the shared transition, and persists both the cut, active records, and used-id history so cached restore preserves strict replay. The `schedule/change` declaration and source location are also indexed in the [persistence catalog](../persistence-catalog.md#schedulechange--log-only).
 
 ## Active views and management
 
diff --git a/docs/subsystems/schedule.zh.md b/docs/subsystems/schedule.zh.md
index bee816be9c..53a36ee9b5 100644
--- a/docs/subsystems/schedule.zh.md
+++ b/docs/subsystems/schedule.zh.md
@@ -149,7 +149,7 @@ type ScheduleDispatchChange = OneShotScheduleDispatchChange | EveryScheduleDispa
 type ScheduleChange = ScheduleCreateChange | ScheduleDeleteChange | ScheduleDispatchChange
 ```
 
-严格 decoder 与 fold 会拒绝未知版本、额外字段、复用 id、不匹配的一次性提醒或 Every dispatch 形状，以及针对非活动记录的 delete 或 dispatch 转换。普通 Session 折叠完整事件流。fork 只折叠 `SessionHeader.seedLength` 位置及其后的事件，因此保留历史，但不会接管父 Session 的活动提醒。Schedule projection 从传给 `init(header)` 的不可变 header 派生该边界，复用共享 transition，并持久化活动记录与已使用 id 历史，使缓存恢复继续保持严格回放。`schedule/change` 声明和源码位置也编入[持久化目录](../persistence-catalog.zh.md#schedulechange--log-only)。
+严格 decoder 与 fold 会拒绝未知版本、额外字段、复用 id、不匹配的一次性提醒或 Every dispatch 形状，以及针对非活动记录的 delete 或 dispatch 转换。普通 Session 折叠完整事件流。fork 只折叠精确 `inheritedEventCount` 位置及其后的事件，因此保留历史，但不会接管父 Session 的活动提醒。Projection 初始化会在不可变 header 旁接收该 cut，复用共享 transition，并持久化 cut、活动记录与已使用 id 历史，使缓存恢复继续保持严格回放。`schedule/change` 声明和源码位置也编入[持久化目录](../persistence-catalog.zh.md#schedulechange--log-only)。
 
 ## 活动视图与管理
 
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index 1cad3ee1f0..fd7e96441a 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
-session-projection.md: b5bacc4846a9a9709bb8c102aaa78810a2752110
-session-projection.zh.md: 36653721a125ceef13bff8b1a4562e7981a45696
+session-projection.md: c8a5d4c1b05d830be3224e2e04db1762fe4b3c8f
+session-projection.zh.md: d46c4f1589f57e560d70871d011245a3547c7825
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index b5bacc4846..c8a5d4c1b0 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -30,9 +30,10 @@ interface ProjectionDefinition<
   /**
    * State for the empty log and its immutable Session metadata.
    * @param header - immutable metadata for the Session being projected.
+   * @param inheritedEventCount - exact fork-inherited prefix length.
    * @returns the initial state.
    */
-  init(header: SessionHeader): NoInfer<S>
+  init(header: SessionHeader, inheritedEventCount: SessionLogOffset): NoInfer<S>
   /**
    * Pure transition: previous state + one committed event → next state. A
    * unit uninterested in an event MUST return the same state reference — an
@@ -78,7 +79,7 @@ The whole-value event rule is load-bearing: a state-carrying log event carries t
  */
 interface ProjectionSnapshot {
   /** Seq of the last event the values reflect; -1 for an empty log. */
-  asOfSeq: number
+  asOfSeq: SessionSeqCursor
   /** Whole current client value per registered key. */
   values: Partial<SessionProjectionMap>
 }
@@ -94,7 +95,7 @@ type ProjectionChangeListener = (
   session: Session,
   key: Extract<keyof SessionProjectionMap, string>,
   value: unknown,
-  seq: number,
+  seq: SessionSeq,
 ) => void
 ```
 
@@ -128,11 +129,13 @@ The persisted projection cache service. Opens the `session_projcache` domain at
  * paths (the history tail baseline) supersede these values whenever a
  * session is actually opened.
  * @param meta - the listed session's header (identity witness; no log read).
+ * @param inheritedEventCount - exact inherited prefix length that completes
+ * the checkpoint identity.
  * @param keys - optional projection keys required by the caller's audience.
  * @returns the cut (`asOfSeq` = lowest served-row watermark), or
  *   `undefined` when no usable row exists for this lifecycle.
  */
-cachedSnapshot( meta: SessionHeader, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot | undefined
+cachedSnapshot( meta: SessionHeader, inheritedEventCount: SessionLogOffset, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot | undefined
 
 /**
  * Hydrate projection cells for an already-prepared Session without another
@@ -140,11 +143,10 @@ cachedSnapshot( meta: SessionHeader, keys?: readonly Extract<keyof SessionProjec
  * advances every unit to the observation cut. No checkpoint is written
  * because the logical observation may contain recovery events not yet durable.
  * @param session - exact unpublished Session retained by persistence.
- * @param meta - observed lifecycle header.
  * @param events - exact logical event prefix represented by the observation.
  * @returns all projection values at the event cut.
  */
-hydratePrepared( session: Session, meta: SessionHeader, events: readonly SessionEvent[], ): ProjectionSnapshot
+hydratePrepared( session: Session, events: readonly SessionEvent[], ): ProjectionSnapshot
 
 /**
  * Durably checkpoint one live session NOW (all mandatory points call
@@ -166,13 +168,14 @@ async write(session: Session): Promise<void>
  * The caller supplies the complete log in seq order: this service never
  * consults the persistence layer.
  * @param meta - the stored session header (identity witness).
+ * @param inheritedEventCount - exact inherited prefix length for projection initialization and identity.
  * @param events - the session's complete log, in seq order.
  * @returns the projection cut at the log end.
  */
-coldSnapshot(meta: SessionHeader, events: readonly SessionEvent[]): ProjectionSnapshot
+coldSnapshot( meta: SessionHeader, inheritedEventCount: SessionLogOffset, events: readonly SessionEvent[], ): ProjectionSnapshot
 ```
 
-Types: [Session](session.md) · [SessionEvent](session.md) · [SessionHeader](persistence.md)
+Types: [Session](session.md) · [SessionEvent](session.md) · [SessionHeader](persistence.md) · [SessionLogOffset](session.md)
 
 Source: [`packages/session/session-projection-cache/src/index.ts`](../../packages/session/session-projection-cache/src/index.ts)
 
@@ -272,7 +275,7 @@ checkpoint(session: Session): ProjectionCheckpoint
  *   when no unit is registered (no read needed — {@link restore} would
  *   serve empty values regardless).
  */
-restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
+restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined
 
 /**
  * View a checkpoint's rows without any log read: for every registered
@@ -306,11 +309,12 @@ viewCheckpoint( checkpoint: ProjectionCheckpoint, keys?: readonly Extract<keyof
  * @param events - the stored events with `seq >= baseSeq`, in seq order.
  * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
  * @param header - immutable metadata for the Session being restored.
+ * @param inheritedEventCount - exact fork-inherited prefix length supplied to unit initialization.
  * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
  *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
  *   refreshed checkpoint rows at that cut, ready for a durable write-back.
  */
-restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number, header: SessionHeader, ): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
+restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, header: SessionHeader, inheritedEventCount: SessionLogOffset, ): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 
 /**
  * Restore an exact cut and install its states on the supplied prepared Session.
@@ -322,10 +326,10 @@ restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], base
  * @param baseSeq - first supplied event sequence.
  * @returns all projection values at the supplied cut.
  */
-hydrate( session: Session, checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number, ): ProjectionSnapshot
+hydrate( session: Session, checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, ): ProjectionSnapshot
 ```
 
-Types: [Session](session.md) · [SessionEvent](session.md) · [SessionHeader](persistence.md)
+Types: [Session](session.md) · [SessionEvent](session.md) · [SessionHeader](persistence.md) · [SessionLogOffset](session.md)
 
 Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index 36653721a1..d46c4f1589 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -30,9 +30,10 @@ interface ProjectionDefinition<
   /**
    * State for the empty log and its immutable Session metadata.
    * @param header - immutable metadata for the Session being projected.
+   * @param inheritedEventCount - exact fork-inherited prefix length.
    * @returns the initial state.
    */
-  init(header: SessionHeader): NoInfer<S>
+  init(header: SessionHeader, inheritedEventCount: SessionLogOffset): NoInfer<S>
   /**
    * Pure transition: previous state + one committed event → next state. A
    * unit uninterested in an event MUST return the same state reference — an
@@ -78,7 +79,7 @@ interface ProjectionDefinition<
  */
 interface ProjectionSnapshot {
   /** Seq of the last event the values reflect; -1 for an empty log. */
-  asOfSeq: number
+  asOfSeq: SessionSeqCursor
   /** Whole current client value per registered key. */
   values: Partial<SessionProjectionMap>
 }
@@ -94,7 +95,7 @@ type ProjectionChangeListener = (
   session: Session,
   key: Extract<keyof SessionProjectionMap, string>,
   value: unknown,
-  seq: number,
+  seq: SessionSeq,
 ) => void
 ```
 
@@ -128,11 +129,13 @@ The persisted projection cache service. Opens the `session_projcache` domain at
  * paths (the history tail baseline) supersede these values whenever a
  * session is actually opened.
  * @param meta - the listed session's header (identity witness; no log read).
+ * @param inheritedEventCount - exact inherited prefix length that completes
+ * the checkpoint identity.
  * @param keys - optional projection keys required by the caller's audience.
  * @returns the cut (`asOfSeq` = lowest served-row watermark), or
  *   `undefined` when no usable row exists for this lifecycle.
  */
-cachedSnapshot( meta: SessionHeader, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot | undefined
+cachedSnapshot( meta: SessionHeader, inheritedEventCount: SessionLogOffset, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot | undefined
 
 /**
  * Hydrate projection cells for an already-prepared Session without another
@@ -140,11 +143,10 @@ cachedSnapshot( meta: SessionHeader, keys?: readonly Extract<keyof SessionProjec
  * advances every unit to the observation cut. No checkpoint is written
  * because the logical observation may contain recovery events not yet durable.
  * @param session - exact unpublished Session retained by persistence.
- * @param meta - observed lifecycle header.
  * @param events - exact logical event prefix represented by the observation.
  * @returns all projection values at the event cut.
  */
-hydratePrepared( session: Session, meta: SessionHeader, events: readonly SessionEvent[], ): ProjectionSnapshot
+hydratePrepared( session: Session, events: readonly SessionEvent[], ): ProjectionSnapshot
 
 /**
  * Durably checkpoint one live session NOW (all mandatory points call
@@ -166,13 +168,14 @@ async write(session: Session): Promise<void>
  * The caller supplies the complete log in seq order: this service never
  * consults the persistence layer.
  * @param meta - the stored session header (identity witness).
+ * @param inheritedEventCount - exact inherited prefix length for projection initialization and identity.
  * @param events - the session's complete log, in seq order.
  * @returns the projection cut at the log end.
  */
-coldSnapshot(meta: SessionHeader, events: readonly SessionEvent[]): ProjectionSnapshot
+coldSnapshot( meta: SessionHeader, inheritedEventCount: SessionLogOffset, events: readonly SessionEvent[], ): ProjectionSnapshot
 ```
 
-Types: [Session](session.zh.md) · [SessionEvent](session.zh.md) · [SessionHeader](persistence.zh.md)
+Types: [Session](session.zh.md) · [SessionEvent](session.zh.md) · [SessionHeader](persistence.zh.md) · [SessionLogOffset](session.zh.md)
 
 Source: [`packages/session/session-projection-cache/src/index.ts`](../../packages/session/session-projection-cache/src/index.ts)
 
@@ -272,7 +275,7 @@ checkpoint(session: Session): ProjectionCheckpoint
  *   when no unit is registered (no read needed — {@link restore} would
  *   serve empty values regardless).
  */
-restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
+restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined
 
 /**
  * View a checkpoint's rows without any log read: for every registered
@@ -306,11 +309,12 @@ viewCheckpoint( checkpoint: ProjectionCheckpoint, keys?: readonly Extract<keyof
  * @param events - the stored events with `seq >= baseSeq`, in seq order.
  * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
  * @param header - immutable metadata for the Session being restored.
+ * @param inheritedEventCount - exact fork-inherited prefix length supplied to unit initialization.
  * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
  *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
  *   refreshed checkpoint rows at that cut, ready for a durable write-back.
  */
-restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number, header: SessionHeader, ): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
+restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, header: SessionHeader, inheritedEventCount: SessionLogOffset, ): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 
 /**
  * Restore an exact cut and install its states on the supplied prepared Session.
@@ -322,10 +326,10 @@ restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], base
  * @param baseSeq - first supplied event sequence.
  * @returns all projection values at the supplied cut.
  */
-hydrate( session: Session, checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number, ): ProjectionSnapshot
+hydrate( session: Session, checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, ): ProjectionSnapshot
 ```
 
-Types: [Session](session.zh.md) · [SessionEvent](session.zh.md) · [SessionHeader](persistence.zh.md)
+Types: [Session](session.zh.md) · [SessionEvent](session.zh.md) · [SessionHeader](persistence.zh.md) · [SessionLogOffset](session.zh.md)
 
 Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index 1283d95440..6ade7bbe1b 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/subsystems/session-query.md
-session-query.md: 74fb3e15514afd32c594b083732153a1f03b21d5
-session-query.zh.md: fee4c29f67bf850fa9ed07d869308844e84b2bb4
+session-query.md: 4317fa3d706dd40c596114a396ba746da67a979f
+session-query.zh.md: 4b67706aea3d3f73304e4c8ad0c689a4c77a13a1
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index 74fb3e1551..4317fa3d70 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -34,6 +34,8 @@ interface SessionRecord {
 interface SessionLogSnapshot {
   /** Cloned session header selected from the same observation as `events`. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Cloned contiguous raw events after persistence repair and replay validation. */
   events: SessionEvent[]
 }
@@ -44,8 +46,10 @@ interface SessionLogSnapshot {
 interface SessionSurfaceSnapshot {
   /** Cloned session header selected from the same corpus observation as `events`. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Highest raw-log seq included in the observation, or `null` for an empty log. */
-  capturedThroughSeq: number | null
+  capturedThroughSeq: OptionalSessionSeq
   /** Cloned current surface events in model-history order. */
   events: SurfaceEvent[]
 }
@@ -90,7 +94,7 @@ interface SessionEventRecord {
   /** Session that owns the event. */
   sessionId: SessionId
   /** Monotonic event seq within the session. */
-  seq: number
+  seq: SessionSeq
   /** Discriminant of the session event. */
   type: SessionEventType
   /** Event timestamp in Unix epoch milliseconds. */
@@ -266,7 +270,7 @@ interface SessionEventReadRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
   /** Target event seq. */
-  seq: number
+  seq: SessionSeq
   /** Number of preceding raw events to include. */
   before?: number
   /** Number of following raw events to include. */
@@ -279,14 +283,16 @@ interface SessionEventReadRequest {
 interface SessionEventWindow {
   /** Cloned header for the live-preferred source read. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Full cloned target event. */
   target: SessionEvent
   /** Full cloned events from `startSeq` through `endSeq`. */
   events: SessionEvent[]
   /** First seq included in `events`. */
-  startSeq: number
+  startSeq: SessionSeq
   /** Last seq included in `events`. */
-  endSeq: number
+  endSeq: SessionSeq
 }
 ```
 
@@ -300,7 +306,7 @@ interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
   /** Target event seq. */
-  seq: number
+  seq: SessionSeq
 }
 ```
 
@@ -310,15 +316,15 @@ interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
   /** Immediate positional replacement event, when the target was shadowed. */
-  replacedBy?: number
+  replacedBy?: SessionSeq
   /** Positional replacers from the immediate replacement to the final replacement. */
-  replacementChain: number[]
+  replacementChain: SessionSeq[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
-  replacedEventSeqs: number[]
+  replacedEventSeqs: SessionSeq[]
   /** Earlier events cited directly as sources, in their recorded order. */
-  sourceEventSeqs: number[]
+  sourceEventSeqs: SessionSeq[]
   /** Later events that directly cite the target as a source, in log order. */
-  derivedEventSeqs: number[]
+  derivedEventSeqs: SessionSeq[]
 }
 ```
 
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index fee4c29f67..4b67706aea 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -34,6 +34,8 @@ interface SessionRecord {
 interface SessionLogSnapshot {
   /** Cloned session header selected from the same observation as `events`. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Cloned contiguous raw events after persistence repair and replay validation. */
   events: SessionEvent[]
 }
@@ -44,8 +46,10 @@ interface SessionLogSnapshot {
 interface SessionSurfaceSnapshot {
   /** Cloned session header selected from the same corpus observation as `events`. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Highest raw-log seq included in the observation, or `null` for an empty log. */
-  capturedThroughSeq: number | null
+  capturedThroughSeq: OptionalSessionSeq
   /** Cloned current surface events in model-history order. */
   events: SurfaceEvent[]
 }
@@ -90,7 +94,7 @@ interface SessionEventRecord {
   /** Session that owns the event. */
   sessionId: SessionId
   /** Monotonic event seq within the session. */
-  seq: number
+  seq: SessionSeq
   /** Discriminant of the session event. */
   type: SessionEventType
   /** Event timestamp in Unix epoch milliseconds. */
@@ -266,7 +270,7 @@ interface SessionEventReadRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
   /** Target event seq. */
-  seq: number
+  seq: SessionSeq
   /** Number of preceding raw events to include. */
   before?: number
   /** Number of following raw events to include. */
@@ -279,14 +283,16 @@ interface SessionEventReadRequest {
 interface SessionEventWindow {
   /** Cloned header for the live-preferred source read. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Full cloned target event. */
   target: SessionEvent
   /** Full cloned events from `startSeq` through `endSeq`. */
   events: SessionEvent[]
   /** First seq included in `events`. */
-  startSeq: number
+  startSeq: SessionSeq
   /** Last seq included in `events`. */
-  endSeq: number
+  endSeq: SessionSeq
 }
 ```
 
@@ -300,7 +306,7 @@ interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
   /** Target event seq. */
-  seq: number
+  seq: SessionSeq
 }
 ```
 
@@ -310,15 +316,15 @@ interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
   /** Immediate positional replacement event, when the target was shadowed. */
-  replacedBy?: number
+  replacedBy?: SessionSeq
   /** Positional replacers from the immediate replacement to the final replacement. */
-  replacementChain: number[]
+  replacementChain: SessionSeq[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
-  replacedEventSeqs: number[]
+  replacedEventSeqs: SessionSeq[]
   /** Earlier events cited directly as sources, in their recorded order. */
-  sourceEventSeqs: number[]
+  sourceEventSeqs: SessionSeq[]
   /** Later events that directly cite the target as a source, in log order. */
-  derivedEventSeqs: number[]
+  derivedEventSeqs: SessionSeq[]
 }
 ```
 
diff --git a/docs/subsystems/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml
index 23a1ccdfa9..63292c20f0 100644
--- a/docs/subsystems/session-title.i18n.yaml
+++ b/docs/subsystems/session-title.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 docs/subsystems/session-title.md
-session-title.md: 05d20c2d7b278dd0663e50d86f1cd22b64852e81
-session-title.zh.md: 2eaa296871bd90e1708f2cf27298b7bbc1efa2c0
+session-title.md: 20ed32b4a08127e7193433673d22f0dea3a90c46
+session-title.zh.md: c01d5d4bf177169069bbe0a39ef533ada0f7c36a
diff --git a/docs/subsystems/session-title.md b/docs/subsystems/session-title.md
index 05d20c2d7b..20ed32b4a0 100644
--- a/docs/subsystems/session-title.md
+++ b/docs/subsystems/session-title.md
@@ -46,7 +46,7 @@ interface SessionTitleEventData {
   /** Normalized non-empty title text. */
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
-  readonly messageSeqs: number[]
+  readonly messageSeqs: SessionSeq[]
   /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
@@ -56,7 +56,7 @@ interface SessionTitleEventData {
 /** Latest folded title plus the title event's durable envelope facts. */
 interface SessionTitleSnapshot extends SessionTitleEventData {
   /** Seq of the latest `session/title` event. */
-  readonly eventSeq: number
+  readonly eventSeq: SessionSeq
   /** Timestamp of the latest `session/title` event. */
   readonly updatedAt: number
 }
@@ -72,7 +72,7 @@ interface SessionTitleLlmRequestEventData {
   /** Registered title-provider identity responsible for the request. */
   readonly titleProvider: SessionTitleProviderId
   /** Exact human `user/message` seqs represented in `messages`. */
-  readonly messageSeqs: number[]
+  readonly messageSeqs: SessionSeq[]
   /** Exact auxiliary LLM route. */
   readonly route: SessionTitleModelProvenance
   /** Exact auxiliary system prompt. */
@@ -92,7 +92,7 @@ The service snapshots eligible messages through one revision. A provider returns
 /** One eligible human text message exposed to title providers. */
 interface SessionTitleUserMessage {
   /** Source `user/message` event seq. */
-  readonly seq: number
+  readonly seq: SessionSeq
   /** Exact concatenated text-block content. */
   readonly text: string
 }
@@ -123,7 +123,7 @@ interface SessionTitleProviderResult {
   /** Proposed title text. */
   readonly title: string
   /** Exact seqs from `request.messages` used by this result. */
-  readonly messageSeqs: readonly number[]
+  readonly messageSeqs: readonly SessionSeq[]
   /** Auxiliary LLM route, when generation used a model. */
   readonly model?: SessionTitleModelProvenance
 }
diff --git a/docs/subsystems/session-title.zh.md b/docs/subsystems/session-title.zh.md
index 2eaa296871..c01d5d4bf1 100644
--- a/docs/subsystems/session-title.zh.md
+++ b/docs/subsystems/session-title.zh.md
@@ -46,7 +46,7 @@ interface SessionTitleEventData {
   /** Normalized non-empty title text. */
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
-  readonly messageSeqs: number[]
+  readonly messageSeqs: SessionSeq[]
   /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
@@ -56,7 +56,7 @@ interface SessionTitleEventData {
 /** Latest folded title plus the title event's durable envelope facts. */
 interface SessionTitleSnapshot extends SessionTitleEventData {
   /** Seq of the latest `session/title` event. */
-  readonly eventSeq: number
+  readonly eventSeq: SessionSeq
   /** Timestamp of the latest `session/title` event. */
   readonly updatedAt: number
 }
@@ -72,7 +72,7 @@ interface SessionTitleLlmRequestEventData {
   /** Registered title-provider identity responsible for the request. */
   readonly titleProvider: SessionTitleProviderId
   /** Exact human `user/message` seqs represented in `messages`. */
-  readonly messageSeqs: number[]
+  readonly messageSeqs: SessionSeq[]
   /** Exact auxiliary LLM route. */
   readonly route: SessionTitleModelProvenance
   /** Exact auxiliary system prompt. */
@@ -92,7 +92,7 @@ interface SessionTitleLlmRequestEventData {
 /** One eligible human text message exposed to title providers. */
 interface SessionTitleUserMessage {
   /** Source `user/message` event seq. */
-  readonly seq: number
+  readonly seq: SessionSeq
   /** Exact concatenated text-block content. */
   readonly text: string
 }
@@ -123,7 +123,7 @@ interface SessionTitleProviderResult {
   /** Proposed title text. */
   readonly title: string
   /** Exact seqs from `request.messages` used by this result. */
-  readonly messageSeqs: readonly number[]
+  readonly messageSeqs: readonly SessionSeq[]
   /** Auxiliary LLM route, when generation used a model. */
   readonly model?: SessionTitleModelProvenance
 }
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 6998ba0cbe..51e2da2af5 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: fbeb501b9ba6283a41c108fc07fc8787ed9e68a4
-session.zh.md: daf25d74bc5bd039a7d8b1a1882c2ec197136ce3
+session.md: 40012d1fc7b5be602dd3783f1df24f8f61f8a969
+session.zh.md: 9d4f6c3ce90913e5236b011e025d8299b3192a57
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index fbeb501b9b..40012d1fc7 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -179,6 +179,28 @@ interface RequestContext {
 
 A proper discriminated union over `type` (not independent `type`/`data` unions), so `switch (event.type)` narrows `event.data` without casts. `seq` is the monotonic position in the log (`seq = log.length`); `time` is epoch ms.
 
+```ts type-equiv
+/** Sequence number of one existing event in a Session log. */
+type SessionSeq = BrandedNumber<'SessionSeq'>
+```
+
+```ts type-equiv
+/** A Session log gap, prefix length, or read offset, which may equal the event count. */
+type SessionLogOffset = BrandedNumber<'SessionLogOffset'>
+```
+
+```ts type-equiv
+/** Inclusive Session event watermark, or `-1` before any event exists. */
+type SessionSeqCursor = SessionSeq | -1
+```
+
+```ts type-equiv
+/** One existing Session event position, or explicit absence. */
+type OptionalSessionSeq = SessionSeq | null
+```
+
+`SessionSeq(value)` and `SessionLogOffset(value)` admit only non-negative safe integers and reject negative zero. They add compile-time brands without changing the serialized number; arithmetic returns an ordinary `number` that callers must admit again through the constructor for its intended role.
+
 ```ts type-equiv
 /**
  * One immutable entry in the session log.
@@ -197,7 +219,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
   [K in SessionEventType]: {
     type: K
     /** Monotonic sequence number within the session. */
-    seq: number
+    seq: SessionSeq
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
@@ -221,7 +243,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * provider stream; when the field is absent, the event does not record which
      * earlier events produced the message.
      */
-    sourceEventSeqs?: number[]
+    sourceEventSeqs?: SessionSeq[]
     /** How this event entered the surface; absent for non-surface events. */
     surfaceOp?: SurfaceOp
   } : object)
@@ -268,7 +290,7 @@ type SurfaceEventType =
  */
 type SurfaceOp =
   | 'append'
-  | { op: 'replace'; start: number; end: number }
+  | { op: 'replace'; start: SessionSeq; end: SessionSeq }
 ```
 
 `'append'` is the normal tail-append path. `replace` shadows surface entries from `start` through `end` inclusive (both must be valid surface seqs; `start === end` replaces a single entry) and inserts the new event in their place.
@@ -288,7 +310,7 @@ interface SurfaceIntent {
    * absent, the event does not record which earlier events produced the message.
    * Other surface events require a non-empty set when this field is present.
    */
-  sourceEventSeqs?: number[]
+  sourceEventSeqs?: SessionSeq[]
 }
 ```
 
@@ -306,7 +328,7 @@ Only `assistant/message` may carry a present empty `sourceEventSeqs`; when the f
 /** Readonly live projection of the message-producing session events. */
 interface SessionSurface {
   /** Current surface event sequences in model-visible order. */
-  readonly nodes: readonly number[]
+  readonly nodes: readonly SessionSeq[]
   /** Monotonic count of committed positional replacements. */
   readonly replaceGeneration: number
 }
@@ -320,13 +342,13 @@ interface SessionSurface {
 /** One replacement operation observed while folding a session surface. */
 interface SurfaceFoldReplacement {
   /** Seq of the event that replaced the prior surface range. */
-  seq: number
+  seq: SessionSeq
   /** Declared inclusive start seq of the replaced surface range. */
-  start: number
+  start: SessionSeq
   /** Declared inclusive end seq of the replaced surface range. */
-  end: number
+  end: SessionSeq
   /** Actual surface entries removed by the operation, in surface order. */
-  shadowedSeqs: number[]
+  shadowedSeqs: SessionSeq[]
 }
 ```
 
@@ -334,7 +356,7 @@ interface SurfaceFoldReplacement {
 /** Complete result of replaying the surface operations in a session log. */
 interface SurfaceFoldResult {
   /** Current surface event sequences in model-visible order. */
-  nodes: number[]
+  nodes: SessionSeq[]
   /** Replacement operations in event order. */
   replacements: SurfaceFoldReplacement[]
 }
@@ -358,13 +380,15 @@ declare class Session {
   get surface(): SessionSurface;
   /**
    * Detached, deep-frozen creation metadata (format version, cwd, lineage,
-   * seed boundary). Supplied by the store via `ctx.sessions.create()`. When a
+   * and whether fork history exists). Supplied by the store via `ctx.sessions.create()`. When a
    * `Session` is created without a store-owned header, a minimal header is
    * synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
    * `session.header` is always present. Kept out of the event log — it is a
    * storage concern, not replayable conversation state.
    */
   readonly header: SessionHeader;
+  /** Number of leading events inherited from this Session's fork parent. */
+  readonly inheritedEventCount: SessionLogOffset;
   /** The session identity, derived from its durable header's single copy. */
   get id(): SessionId;
   /**
@@ -373,9 +397,9 @@ declare class Session {
    * construction — replay, fork, or resume — and were never published on the
    * `session/event` firehose (constructor seeds do not emit), so consumers
    * that replay the log as a publication substitute (telemetry adoption)
-   * start here. Distinct from `header.seedLength`, the DURABLE fork-lineage
-   * boundary: a resumed session's constructor seed is its full stored log,
-   * while its header keeps the original fork value — this field is the
+   * start here. Distinct from {@link inheritedEventCount}, the DURABLE
+   * fork-lineage cut: a resumed session's constructor seed is its full stored
+   * log, while the inherited count keeps the original fork value — this field is the
    * in-process construction fact.
    *
    * Not persisted itself: a seeded session projects it into the log as the
@@ -389,16 +413,22 @@ declare class Session {
    * store attaches and therefore does not publish either. Otherwise this seq
    * holds an ordinary published write.
   */
-  readonly firstLiveSeq: number;
+  readonly firstLiveSeq: SessionLogOffset;
   /**
    * 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.
+   * @param inheritedEventCount - exact fork-inherited prefix length for a seeded header.
    * @returns a detached session.
    */
-  static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;
+  static create(
+    id: SessionId,
+    seed?: readonly SessionEvent[],
+    header?: SessionHeader,
+    inheritedEventCount?: SessionLogOffset,
+  ): Session;
   /**
    * Restore a detached session by taking ownership of fresh persistence values.
    * The storage format, event envelopes, sequence continuity, surface transitions,
@@ -406,15 +436,21 @@ declare class Session {
    * @param id - restored session identity.
    * @param seed - fresh detached events whose ownership is transferred.
    * @param header - fresh detached metadata whose ownership is transferred.
+   * @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
    * @returns a restored detached session.
    */
-  static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;
+  static fromRestore(
+    id: SessionId,
+    seed: readonly SessionEvent[],
+    header: SessionHeader,
+    inheritedEventCount: SessionLogOffset,
+  ): Session;
   /**
    * Return the immutable event stored at one exact sequence number.
    * @param seq - event sequence number.
    * @returns the accepted event, or undefined when the log does not contain it.
    */
-  eventAt(seq: number): SessionEvent | undefined;
+  eventAt(seq: SessionSeq): SessionEvent | undefined;
   /**
    * Materialize an immutable snapshot of a half-open event sequence range.
    * A full current snapshot is reused until the next append; every previously
@@ -423,9 +459,23 @@ declare class Session {
    * @param toSeqExclusive - non-negative exclusive sequence number; defaults to the current end.
    * @returns a frozen array of the selected deeply frozen events.
    */
-  snapshotEvents(fromSeq: number = 0, toSeqExclusive: number = this.log.length): readonly SessionEvent[];
+  snapshotEvents(
+    fromSeq: SessionLogOffset = SessionLogOffset(0),
+    toSeqExclusive: SessionLogOffset = this.seq,
+  ): readonly SessionEvent[];
+  /**
+   * Return this Session's events after its fork-inherited prefix.
+   * @returns a fresh array containing child-owned events in log order.
+   */
+  ownEvents(): readonly SessionEvent[];
+  /**
+   * Whether one existing event position is outside the fork-inherited prefix.
+   * @param seq - event position in this Session.
+   * @returns true when the event belongs to this Session rather than its parent.
+   */
+  isOwnSeq(seq: SessionSeq): boolean;
   /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
-  get seq(): number;
+  get seq(): SessionLogOffset;
   /**
    * Append one typed event to the log and synchronously notify observers via
    * the store-owned, module-private publication hooks. The hot path never blocks
@@ -525,7 +575,7 @@ Everything else (`turn/*`, `step/*`, plugin-owned `llm/retry`) is structural and
 
 `ctx.sessions.create(id, { seed, meta })` is the low-level replay/fork primitive. For ordinary live-session forks, `SessionStore` exposes one policy API:
 
-- `fork(source, boundary?, childSessionId?)` accepts a live `Session` object or live `SessionId`, selects source events through the inclusive `boundary` seq (default: current last event), requires the selected prefix to end outside an open turn, then creates a live child session with deep-cloned seed events plus child metadata (`parentSession`, `seedLength`, and inherited `cwd`).
+- `fork(source, boundary?, childSessionId?)` accepts a live `Session` object or live `SessionId`, selects source events through the inclusive `SessionSeq` boundary (default: current last event), requires the selected prefix to end outside an open turn, then creates a live child session with deep-cloned seed events, `parentSession`, `isSeeded: true`, the exact `inheritedEventCount`, and inherited `cwd`.
 
 An explicit `boundary` lets callers fork from any stable between-turn position, including a previous `turn/end` or a later standalone log-only event, even if the source has newer events or an open current turn. The API rejects a prefix that ends inside an open turn instead of clipping silently. Broader execution-relation sanity stays in the existing `dsh-invariants` plugin and persistence repair path rather than being duplicated in `fork()`. `dsh-subagent-fork-in-process` keeps its completed-prefix clipping because tool-time delegation usually starts while the parent turn is open; ordinary session branching should make the requested boundary explicit.
 
@@ -574,7 +624,7 @@ The optional `dsh-session/invariant` companion enforces the relations owned by c
 
 ## The end-seed boundary: `session/end-seed`
 
-A seeded session — resume, fork, or replay — appends this log-only event immediately after its constructor seed, as its first live write. Events before it have smaller seq values and came from the seed. It is the durable projection of `firstLiveSeq`: that field answers where this lifecycle's writes start for a consumer holding the object, while the event answers the same question for one holding only stored bytes. The payload is empty, so position and `time` carry the whole meaning, and it produces no message. `Session`'s constructor is the only legitimate writer.
+A Session constructed with an explicit seed — restore, fork, or replay — appends this log-only event immediately after that constructor seed, as its first live write. Events before it have smaller seq values and came through construction. It is the durable projection of `firstLiveSeq`: that field answers where this lifecycle's writes start for a consumer holding the object, while the event answers the same question for one holding only stored bytes. It does not define fork ownership; `isSeeded` plus `inheritedEventCount` do. The payload is empty, so position and `time` carry the whole meaning, and it produces no message. `Session`'s constructor is the only legitimate writer.
 
 An explicitly supplied empty seed writes `session/end-seed` at seq 0, which distinguishes an empty resumed session from a fresh one. A seed already ending in `session/end-seed` is not re-marked, so reopening an untouched session does not grow its log per pickup. Locate the LAST `session/end-seed` in stored history rather than assuming one exists at `firstLiveSeq`: after a pickup with no work, the event has a smaller seq than the next lifecycle's `firstLiveSeq`.
 
@@ -630,7 +680,7 @@ resolveAgent(sessionId: SessionId): Promise<ApiSessionAgentResult>
  * @param signal - optional caller cancellation for persistence reads.
  * @returns the current attached state or persisted header and event prefix.
  */
-inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionHeader; events: readonly SessionEvent[] }>
+inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionInspection>
 
 /**
  * Read all visible Session rows without resuming an Agent.
@@ -750,7 +800,7 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionH
 @Remote({ mode: 'stream' }) control(signal: AbortSignal): AsyncIterable<SessionControlFrame>
 ```
 
-Types: [SessionHeader](persistence.md) · [SessionId](core.md) · [SessionSearchRequest](session-query.md)
+Types: [SessionId](core.md) · [SessionInspection](persistence.md) · [SessionSearchRequest](session-query.md)
 
 Source: [`packages/api/session-controller/src/index.ts`](../../packages/api/session-controller/src/index.ts)
 
@@ -883,7 +933,7 @@ list(): Session[]
  *   `SessionStore`'s id policy.
  * @returns The created live child session.
  */
-fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session
 ```
 
 Types: [CreateSessionOptions](persistence.md) · [PrepareSessionOptions](persistence.md) · [SessionId](core.md)
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index daf25d74bc..9d4f6c3ce9 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -179,6 +179,28 @@ interface RequestContext {
 
 基于 `type` 的真正可辨识联合（而非独立的 `type`/`data` 联合），因此 `switch (event.type)` 能直接收窄 `event.data`，无需类型断言。`seq` 是日志中的单调递增位置（`seq = log.length`）；`time` 为 epoch 毫秒。
 
+```ts type-equiv
+/** Sequence number of one existing event in a Session log. */
+type SessionSeq = BrandedNumber<'SessionSeq'>
+```
+
+```ts type-equiv
+/** A Session log gap, prefix length, or read offset, which may equal the event count. */
+type SessionLogOffset = BrandedNumber<'SessionLogOffset'>
+```
+
+```ts type-equiv
+/** Inclusive Session event watermark, or `-1` before any event exists. */
+type SessionSeqCursor = SessionSeq | -1
+```
+
+```ts type-equiv
+/** One existing Session event position, or explicit absence. */
+type OptionalSessionSeq = SessionSeq | null
+```
+
+`SessionSeq(value)` 与 `SessionLogOffset(value)` 只接纳非负安全整数，并拒绝负零。它们仅添加编译期品牌，不改变序列化后的数值；算术会返回普通 `number`，调用方必须按结果的预期角色通过对应构造器重新接纳。
+
 ```ts type-equiv
 /**
  * One immutable entry in the session log.
@@ -197,7 +219,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
   [K in SessionEventType]: {
     type: K
     /** Monotonic sequence number within the session. */
-    seq: number
+    seq: SessionSeq
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
@@ -221,7 +243,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * provider stream; when the field is absent, the event does not record which
      * earlier events produced the message.
      */
-    sourceEventSeqs?: number[]
+    sourceEventSeqs?: SessionSeq[]
     /** How this event entered the surface; absent for non-surface events. */
     surfaceOp?: SurfaceOp
   } : object)
@@ -270,7 +292,7 @@ type SurfaceEventType =
  */
 type SurfaceOp =
   | 'append'
-  | { op: 'replace'; start: number; end: number }
+  | { op: 'replace'; start: SessionSeq; end: SessionSeq }
 ```
 
 `'append'` 是常规的尾部追加路径。`replace` 会遮蔽从 `start` 到 `end`（含两端）的 surface 条目（两者都必须是有效的 surface seq；`start === end` 时仅替换单个条目），并在原位置插入新事件。
@@ -290,7 +312,7 @@ interface SurfaceIntent {
    * absent, the event does not record which earlier events produced the message.
    * Other surface events require a non-empty set when this field is present.
    */
-  sourceEventSeqs?: number[]
+  sourceEventSeqs?: SessionSeq[]
 }
 ```
 
@@ -308,7 +330,7 @@ interface SurfaceIntent {
 /** Readonly live projection of the message-producing session events. */
 interface SessionSurface {
   /** Current surface event sequences in model-visible order. */
-  readonly nodes: readonly number[]
+  readonly nodes: readonly SessionSeq[]
   /** Monotonic count of committed positional replacements. */
   readonly replaceGeneration: number
 }
@@ -322,13 +344,13 @@ interface SessionSurface {
 /** One replacement operation observed while folding a session surface. */
 interface SurfaceFoldReplacement {
   /** Seq of the event that replaced the prior surface range. */
-  seq: number
+  seq: SessionSeq
   /** Declared inclusive start seq of the replaced surface range. */
-  start: number
+  start: SessionSeq
   /** Declared inclusive end seq of the replaced surface range. */
-  end: number
+  end: SessionSeq
   /** Actual surface entries removed by the operation, in surface order. */
-  shadowedSeqs: number[]
+  shadowedSeqs: SessionSeq[]
 }
 ```
 
@@ -336,7 +358,7 @@ interface SurfaceFoldReplacement {
 /** Complete result of replaying the surface operations in a session log. */
 interface SurfaceFoldResult {
   /** Current surface event sequences in model-visible order. */
-  nodes: number[]
+  nodes: SessionSeq[]
   /** Replacement operations in event order. */
   replacements: SurfaceFoldReplacement[]
 }
@@ -360,13 +382,15 @@ declare class Session {
   get surface(): SessionSurface;
   /**
    * Detached, deep-frozen creation metadata (format version, cwd, lineage,
-   * seed boundary). Supplied by the store via `ctx.sessions.create()`. When a
+   * and whether fork history exists). Supplied by the store via `ctx.sessions.create()`. When a
    * `Session` is created without a store-owned header, a minimal header is
    * synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
    * `session.header` is always present. Kept out of the event log — it is a
    * storage concern, not replayable conversation state.
    */
   readonly header: SessionHeader;
+  /** Number of leading events inherited from this Session's fork parent. */
+  readonly inheritedEventCount: SessionLogOffset;
   /** The session identity, derived from its durable header's single copy. */
   get id(): SessionId;
   /**
@@ -375,9 +399,9 @@ declare class Session {
    * construction — replay, fork, or resume — and were never published on the
    * `session/event` firehose (constructor seeds do not emit), so consumers
    * that replay the log as a publication substitute (telemetry adoption)
-   * start here. Distinct from `header.seedLength`, the DURABLE fork-lineage
-   * boundary: a resumed session's constructor seed is its full stored log,
-   * while its header keeps the original fork value — this field is the
+   * start here. Distinct from {@link inheritedEventCount}, the DURABLE
+   * fork-lineage cut: a resumed session's constructor seed is its full stored
+   * log, while the inherited count keeps the original fork value — this field is the
    * in-process construction fact.
    *
    * Not persisted itself: a seeded session projects it into the log as the
@@ -391,16 +415,22 @@ declare class Session {
    * store attaches and therefore does not publish either. Otherwise this seq
    * holds an ordinary published write.
   */
-  readonly firstLiveSeq: number;
+  readonly firstLiveSeq: SessionLogOffset;
   /**
    * 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.
+   * @param inheritedEventCount - exact fork-inherited prefix length for a seeded header.
    * @returns a detached session.
    */
-  static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;
+  static create(
+    id: SessionId,
+    seed?: readonly SessionEvent[],
+    header?: SessionHeader,
+    inheritedEventCount?: SessionLogOffset,
+  ): Session;
   /**
    * Restore a detached session by taking ownership of fresh persistence values.
    * The storage format, event envelopes, sequence continuity, surface transitions,
@@ -408,15 +438,21 @@ declare class Session {
    * @param id - restored session identity.
    * @param seed - fresh detached events whose ownership is transferred.
    * @param header - fresh detached metadata whose ownership is transferred.
+   * @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
    * @returns a restored detached session.
    */
-  static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;
+  static fromRestore(
+    id: SessionId,
+    seed: readonly SessionEvent[],
+    header: SessionHeader,
+    inheritedEventCount: SessionLogOffset,
+  ): Session;
   /**
    * Return the immutable event stored at one exact sequence number.
    * @param seq - event sequence number.
    * @returns the accepted event, or undefined when the log does not contain it.
    */
-  eventAt(seq: number): SessionEvent | undefined;
+  eventAt(seq: SessionSeq): SessionEvent | undefined;
   /**
    * Materialize an immutable snapshot of a half-open event sequence range.
    * A full current snapshot is reused until the next append; every previously
@@ -425,9 +461,23 @@ declare class Session {
    * @param toSeqExclusive - non-negative exclusive sequence number; defaults to the current end.
    * @returns a frozen array of the selected deeply frozen events.
    */
-  snapshotEvents(fromSeq: number = 0, toSeqExclusive: number = this.log.length): readonly SessionEvent[];
+  snapshotEvents(
+    fromSeq: SessionLogOffset = SessionLogOffset(0),
+    toSeqExclusive: SessionLogOffset = this.seq,
+  ): readonly SessionEvent[];
+  /**
+   * Return this Session's events after its fork-inherited prefix.
+   * @returns a fresh array containing child-owned events in log order.
+   */
+  ownEvents(): readonly SessionEvent[];
+  /**
+   * Whether one existing event position is outside the fork-inherited prefix.
+   * @param seq - event position in this Session.
+   * @returns true when the event belongs to this Session rather than its parent.
+   */
+  isOwnSeq(seq: SessionSeq): boolean;
   /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
-  get seq(): number;
+  get seq(): SessionLogOffset;
   /**
    * Append one typed event to the log and synchronously notify observers via
    * the store-owned, module-private publication hooks. The hot path never blocks
@@ -527,7 +577,7 @@ declare class Session {
 
 `ctx.sessions.create(id, { seed, meta })` 是底层的回放/fork 原语。对于普通的活跃会话 fork，`SessionStore` 暴露一个策略 API：
 
-- `fork(source, boundary?, childSessionId?)` 接受一个活跃的 `Session` 对象或活跃的 `SessionId`，选取到 `boundary` seq（含）为止的源事件（默认为当前最后一个事件），要求所选前缀结束时没有开放轮次，然后创建一个活跃的子会话，包含深克隆的种子事件和子会话元数据（`parentSession`、`seedLength` 及继承的 `cwd`）。
+- `fork(source, boundary?, childSessionId?)` 接受一个活跃的 `Session` 对象或活跃的 `SessionId`，选取到 `SessionSeq` boundary（含）为止的源事件（默认为当前最后一个事件），要求所选前缀结束时没有开放轮次，然后创建一个活跃的子会话，包含深克隆的 seed event、`parentSession`、`isSeeded: true`、精确 `inheritedEventCount` 及继承的 `cwd`。
 
 显式 `boundary` 允许调用者从任意稳定的轮次间位置 fork，包括之前的 `turn/end` 或更晚的独立纯日志事件，即使源会话有更新的事件或正在进行的轮次。API 拒绝结束于开放轮次内的前缀，而不是静默截断。更广泛的执行关系健全性检查留在既有的 `dsh-invariants` 插件和持久化修复路径中，不在 `fork()` 中重复。`dsh-subagent-fork-in-process` 保留其已完成前缀截断逻辑，因为工具调用时的委托通常在父轮次仍然打开时启动；普通的会话分支应显式指定请求的 boundary。
 
@@ -578,7 +628,7 @@ interface TurnEndReasonMap {
 
 ## 种子结束边界：`session/end-seed`
 
-带种子的会话（恢复、fork 或回放）紧接构造种子之后追加这个仅日志事件，作为自己的第一次实时写入。在它之前的事件具有更小的 seq，且来自种子。它是 `firstLiveSeq` 的持久投影：该字段为持有对象的消费方回答本生命周期的写入从哪里开始，该事件则为只持有存储字节的消费方回答同一问题。payload 为空，因此位置与 `time` 承载全部含义，且不产生任何消息。`Session` 的构造函数是唯一合法的写入方。
+用显式 seed 构造的 Session（restore、fork 或 replay）会紧接该 constructor seed 之后追加这个仅日志事件，作为自己的第一次实时写入。在它之前的事件具有更小的 seq，且经由构造进入。它是 `firstLiveSeq` 的持久投影：该字段为持有对象的 consumer 回答本 lifecycle 的写入从哪里开始，该事件则为只持有存储字节的 consumer 回答同一问题。它不定义 fork ownership；`isSeeded` 与 `inheritedEventCount` 才定义。payload 为空，因此位置与 `time` 承载全部含义，且不产生任何消息。`Session` 的构造函数是唯一合法的写入方。
 
 显式传入的空种子会在 seq 0 写入 `session/end-seed`，从而把从空日志恢复的会话与全新会话区分开来。种子本身已以 `session/end-seed` 结尾时不会重复标记，因此重新打开一个未被改动的会话不会每次拾起都增长日志。应定位存储历史中的最后一条 `session/end-seed`，而不是假定 `firstLiveSeq` 处一定有一条：在一次没有产生工作的拾起之后，该事件的 seq 会小于下一个生命周期的 `firstLiveSeq`。
 
@@ -634,7 +684,7 @@ resolveAgent(sessionId: SessionId): Promise<ApiSessionAgentResult>
  * @param signal - optional caller cancellation for persistence reads.
  * @returns the current attached state or persisted header and event prefix.
  */
-inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionHeader; events: readonly SessionEvent[] }>
+inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionInspection>
 
 /**
  * Read all visible Session rows without resuming an Agent.
@@ -754,7 +804,7 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionH
 @Remote({ mode: 'stream' }) control(signal: AbortSignal): AsyncIterable<SessionControlFrame>
 ```
 
-Types: [SessionHeader](persistence.zh.md) · [SessionId](core.zh.md) · [SessionSearchRequest](session-query.zh.md)
+Types: [SessionId](core.zh.md) · [SessionInspection](persistence.zh.md) · [SessionSearchRequest](session-query.zh.md)
 
 Source: [`packages/api/session-controller/src/index.ts`](../../packages/api/session-controller/src/index.ts)
 
@@ -887,7 +937,7 @@ list(): Session[]
  *   `SessionStore`'s id policy.
  * @returns The created live child session.
  */
-fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session
 ```
 
 Types: [CreateSessionOptions](persistence.zh.md) · [PrepareSessionOptions](persistence.zh.md) · [SessionId](core.zh.md)
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index ef1494e405..e3b15dc2d8 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: 109f8569879c0578f804569d1105c03250ad3bf5
-subagent.zh.md: 649a3796f9f199306e45ea9653bb38df8683a518
+subagent.md: 5369ed85b5382dcb07df3e458a99124107ad5e51
+subagent.zh.md: 7495890531c6faa604a96edf443543840f69ae2c
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 109f856987..5369ed85b5 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -258,7 +258,7 @@ interface ContinuableCreateSpec {
 
 The descriptor (`SubagentDescriptorData` in [descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts)) is a mode-discriminated durable identity for every session-backed subagent. Both modes carry the provider name. A `one-shot` descriptor optionally carries a caller-owned display `label`; a `continuable` descriptor requires the delegation `description` as its durable creation label and additionally snapshots resolved child `agentOptions.provider`/`model`/`reasoningEffort` and optional `persona`/`toolFilter` for cold resume. It never snapshots the merge-extensible `AgentOptions` object, so an unrelated extension value cannot break continuation and a later composition input is a deliberate version change. It omits `subagentDepth` (cold resume trusts the persisted header's `delegationDepth` as the monotone floor) and `outputSchema` (one run or Activation's result contract, not durable identity).
 
-A local one-shot provider appends the descriptor inside the child's initial turn before its first request. The continuation manager appends the descriptor after any provider-supplied lineage and before the initial prompt is admitted; `header.seedLength` remains the fork-lineage boundary: resume-time descriptor authority reads the child's own suffix, while the list-serving identity projection folds `subagent/descriptor` last-wins so the child's own descriptor overrides a fork-seeded ancestor's. The event is log-only: no `surfaceOp`, never in model history, and retained across compaction by the append-only log. Malformed current-version descriptors are corrupt; unsupported versions cannot be classified by this runtime.
+A local one-shot provider appends the descriptor inside the child's initial turn before its first request. The continuation manager appends the descriptor after any provider-supplied lineage and before the initial prompt is admitted; `Session.inheritedEventCount` remains the fork-lineage boundary: resume-time descriptor authority reads the child's own suffix, while the list-serving identity projection folds `subagent/descriptor` last-wins so the child's own descriptor overrides a fork-seeded ancestor's. A seeded cold list skips a cache hint until an authoritative observation supplies that exact cut. The event is log-only: no `surfaceOp`, never in model history, and retained across compaction by the append-only log. Malformed current-version descriptors are corrupt; unsupported versions cannot be classified by this runtime.
 
 ## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 649a3796f9..7495890531 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -258,7 +258,7 @@ interface ContinuableCreateSpec {
 
 描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model`／`reasoningEffort` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果约定，而非持久化身份）。
 
-本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始提示词获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
+本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始提示词获准之前追加描述符；`Session.inheritedEventCount` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。seeded cold list 会跳过 cache hint，直到权威 observation 提供该精确 cut。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
diff --git a/docs/subsystems/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml
index 4028e567f5..14e3c7a5a4 100644
--- a/docs/subsystems/token-meter.i18n.yaml
+++ b/docs/subsystems/token-meter.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 docs/subsystems/token-meter.md
-token-meter.md: 9c4a1e4b95ffd84f65f7a73e208be245378a3301
-token-meter.zh.md: d9e2e7f773041ccb6d1e4c3cc4d81a342db0cc01
+token-meter.md: 2265f5073efbd2953e4f399ad58a026772b60006
+token-meter.zh.md: b1d9d66dc804fecace15489e61c1d080c096932d
diff --git a/docs/subsystems/token-meter.md b/docs/subsystems/token-meter.md
index 9c4a1e4b95..2265f5073e 100644
--- a/docs/subsystems/token-meter.md
+++ b/docs/subsystems/token-meter.md
@@ -12,7 +12,7 @@ Source: [`packages/llm/token-meter/src/types.ts`](../../packages/llm/token-meter
 /** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
 interface TokenMeasurement {
   /** Number of durable events consumed; equal to the next unread event seq. */
-  readonly logRevision: number
+  readonly logRevision: SessionLogOffset
   /** Provider or heuristic anchor used for this measurement. */
   readonly baseline: TokenMeasurementBaseline
   /** Signed repricing of current surface content relative to the baseline anchor. */
@@ -34,7 +34,7 @@ Every measurement resolves the effective envelope's routed provider/model to tha
 /** One token-priced node in the current ordered session surface. */
 interface TokenSurfaceNode {
   /** Durable sequence number of the surface event. */
-  readonly seq: number
+  readonly seq: SessionSeq
   /**
    * Request-pressure tokens for the exact message projected by this node under
    * the measured route: image occurrences carry the route's declared visual
diff --git a/docs/subsystems/token-meter.zh.md b/docs/subsystems/token-meter.zh.md
index d9e2e7f773..b1d9d66dc8 100644
--- a/docs/subsystems/token-meter.zh.md
+++ b/docs/subsystems/token-meter.zh.md
@@ -12,7 +12,7 @@
 /** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
 interface TokenMeasurement {
   /** Number of durable events consumed; equal to the next unread event seq. */
-  readonly logRevision: number
+  readonly logRevision: SessionLogOffset
   /** Provider or heuristic anchor used for this measurement. */
   readonly baseline: TokenMeasurementBaseline
   /** Signed repricing of current surface content relative to the baseline anchor. */
@@ -34,7 +34,7 @@ interface TokenMeasurement {
 /** One token-priced node in the current ordered session surface. */
 interface TokenSurfaceNode {
   /** Durable sequence number of the surface event. */
-  readonly seq: number
+  readonly seq: SessionSeq
   /**
    * Request-pressure tokens for the exact message projected by this node under
    * the measured route: image occurrences carry the route's declared visual
diff --git a/packages/acp/acp/tests/bridge.spec.ts b/packages/acp/acp/tests/bridge.spec.ts
index 55e56a25b0..5dec9b3786 100644
--- a/packages/acp/acp/tests/bridge.spec.ts
+++ b/packages/acp/acp/tests/bridge.spec.ts
@@ -254,6 +254,7 @@ describe('automation-only ACP bridge', () => {
       id: sessionId,
       createdAt: 1,
       cwd: process.cwd(),
+      isSeeded: false,
     }])
     const resume = vi.spyOn(harness.ctx.agents, 'resume')
 
@@ -363,14 +364,14 @@ describe('automation-only ACP bridge', () => {
     const active = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
     const persistence = harness.ctx.get('sessionPersistence')!
     vi.spyOn(persistence, 'list').mockResolvedValue([
-      { version: 0, id: SessionId(active.sessionId), createdAt: 9, cwd: process.cwd() },
-      { version: 0, id: SessionId('subagent'), createdAt: 8, cwd: '/missing/filter', origin: 'subagent' },
-      { version: 0, id: SessionId('fork'), createdAt: 7, cwd: '/missing/filter', parentSession: SessionId('parent') },
-      { version: 0, id: SessionId('no-cwd'), createdAt: 6 },
-      { version: 0, id: SessionId('relative'), createdAt: 5, cwd: 'relative' },
-      { version: 0, id: SessionId('other'), createdAt: 4, cwd: '/missing/other' },
-      { version: 0, id: SessionId('valid-b'), createdAt: 3, cwd: '/missing/filter' },
-      { version: 0, id: SessionId('valid-a'), createdAt: 3, cwd: '/missing/filter' },
+      { version: 0, id: SessionId(active.sessionId), createdAt: 9, cwd: process.cwd(), isSeeded: false },
+      { version: 0, id: SessionId('subagent'), createdAt: 8, cwd: '/missing/filter', isSeeded: false, origin: 'subagent' },
+      { version: 0, id: SessionId('fork'), createdAt: 7, cwd: '/missing/filter', isSeeded: true, parentSession: SessionId('parent') },
+      { version: 0, id: SessionId('no-cwd'), createdAt: 6, isSeeded: false },
+      { version: 0, id: SessionId('relative'), createdAt: 5, cwd: 'relative', isSeeded: false },
+      { version: 0, id: SessionId('other'), createdAt: 4, cwd: '/missing/other', isSeeded: false },
+      { version: 0, id: SessionId('valid-b'), createdAt: 3, cwd: '/missing/filter', isSeeded: false },
+      { version: 0, id: SessionId('valid-a'), createdAt: 3, cwd: '/missing/filter', isSeeded: false },
     ])
 
     await expect(harness.client.listSessions({ cwd: 'relative' })).rejects.toThrow(/absolute path/)
diff --git a/packages/acp/acp/tests/updates.spec.ts b/packages/acp/acp/tests/updates.spec.ts
index 832403c6db..fe070086c1 100644
--- a/packages/acp/acp/tests/updates.spec.ts
+++ b/packages/acp/acp/tests/updates.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import type { Context } from '@deepseek-ai/cordis'
 import { ToolCallId, MessageId } from '@deepseek-ai/dsh-llm'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
 import { assistantUpdates, toolCallUpdate, toolResultUpdate } from '../src/updates.ts'
 
 /** Minimal committed assistant event for pure update projection tests. */
@@ -11,7 +11,7 @@ function assistantEvent(
 ): SessionEvent<'assistant/message'> {
   return {
     type: 'assistant/message',
-    seq: 0,
+    seq: SessionSeq(0),
     time: 0,
     data: {
       turn: 1,
@@ -57,13 +57,13 @@ describe('standard ACP update projection', () => {
   it('preserves malformed tool input and projects a failed result without hidden content', async () => {
     const call = toolCallUpdate({
       type: 'tool/call',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 0,
       data: { turn: 1, step: 1, callId: ToolCallId('call-bad'), name: 'broken', arguments: '{' },
     })
     const result = await toolResultUpdate({ get: () => undefined } as unknown as Context, {
       type: 'tool/result',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 0,
       data: {
         turn: 1,
diff --git a/packages/api/session-controller/src/agent.ts b/packages/api/session-controller/src/agent.ts
index c17929af5c..b1f1872662 100644
--- a/packages/api/session-controller/src/agent.ts
+++ b/packages/api/session-controller/src/agent.ts
@@ -9,7 +9,8 @@ import type {
 import type {} from '@deepseek-ai/dsh-agent-default-model'
 import type {} from '@deepseek-ai/dsh-agent-presets'
 import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
-import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence'
 import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
 import type {} from '@deepseek-ai/dsh-typert-registry'
@@ -112,7 +113,7 @@ export async function inspectApiSession(
   ctx: Context,
   sessionId: SessionId,
   signal?: AbortSignal,
-): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+): Promise<SessionInspection> {
   try {
     using observation = await ctx.sessionQuery.observeSession(sessionId, {
       ...(signal === undefined ? {} : { signal }),
@@ -121,7 +122,11 @@ export async function inspectApiSession(
     if (observation.header.cwd === undefined) {
       throw new ApiSessionNotFound(`session "${sessionId}" not found`)
     }
-    return { meta: observation.header, events: [...observation.events] }
+    return {
+      meta: observation.header,
+      inheritedEventCount: observation.inheritedEventCount,
+      events: [...observation.events],
+    }
   } catch (error: unknown) {
     if (error instanceof SessionQueryError
       && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
diff --git a/packages/api/session-controller/src/client/contract/session.ts b/packages/api/session-controller/src/client/contract/session.ts
index 71cc72e0ab..43c0f2dfd6 100644
--- a/packages/api/session-controller/src/client/contract/session.ts
+++ b/packages/api/session-controller/src/client/contract/session.ts
@@ -9,7 +9,7 @@
  */
 import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { SessionId, SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { PromptContentPart, QueueAction, SessionRequestId } from '../../types.ts'
@@ -113,7 +113,7 @@ export interface ISession {
    * @param title - raw title text (the host normalizes acceptance).
    * @returns the normalized accepted title and its event seq, or the business error.
    */
-  rename(title: string): Promise<RemoteResult<{ title: string; seq: number }>>
+  rename(title: string): Promise<RemoteResult<{ title: string; seq: SessionSeq }>>
   /**
    * Extend the history window backwards (older messages pagination).
    * @returns completion; failures land in snapshot.openState/loadingOlder.
@@ -127,7 +127,7 @@ export interface ISession {
    * @param seq - durable event seq the window must reach (a turn's `turn/start` seq).
    * @returns completion once covered, exhausted, superseded, or failed soft.
    */
-  loadThrough(seq: number): Promise<void>
+  loadThrough(seq: SessionSeq): Promise<void>
   /**
    * Execute one slash-command line against this session's agent — pure
    * admission semantics (the host executor durably logs the lifecycle).
diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts
index 47392c86f3..fd39fefedf 100644
--- a/packages/api/session-controller/src/client/sessions/manager.ts
+++ b/packages/api/session-controller/src/client/sessions/manager.ts
@@ -3,7 +3,7 @@
 // List data never enters zustand; React connects via subscribe/getListSnapshot.
 
 import type { SubagentAddress, SubagentCatalog } from '@deepseek-ai/dsh-subagent/client'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { SessionSeq, type SessionId, type SessionSeqCursor } from '@deepseek-ai/dsh-session/types'
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
 import type {
   SessionControlBaseline,
@@ -26,6 +26,10 @@ import { ProjectionValueStore } from './projection-store.ts'
 import { Session } from './session.ts'
 import type { SessionRemotes } from './remotes.ts'
 
+function sessionSeqCursor(value: number): SessionSeqCursor {
+  return value === -1 ? -1 : SessionSeq(value)
+}
+
 /**
  * List arrival lifecycle, orthogonal to the pull-activity `state` axis:
  * `pending` (no successful pull yet — an empty items array means "nothing
@@ -498,7 +502,7 @@ export class SessionManager {
             if (block === undefined) continue
             const store = this.projectionStore(s.sessionId)
             const values = block.values as Record<string, unknown>
-            for (const key of Object.keys(values)) store.apply(key, values[key], block.asOfSeq)
+            for (const key of Object.keys(values)) store.apply(key, values[key], sessionSeqCursor(block.asOfSeq))
           }
         } else {
           this.listState = 'error'
@@ -590,7 +594,7 @@ export class SessionManager {
    * @returns the fork result (the child session id).
    */
   async fork(
-    opts: { sessionId: SessionId; atSeq?: number },
+    opts: { sessionId: SessionId; atSeq?: SessionSeq },
   ): Promise<RemoteResult<{ sessionId: SessionId }>> {
     const source = this.summaries.find(s => s.sessionId === opts.sessionId)
     const result = await this.remote.session.fork({
@@ -661,7 +665,7 @@ export class SessionManager {
       return
     }
     if (frame.type === 'projection') {
-      this.projectionStore(frame.sessionId).apply(frame.key, frame.value, frame.seq)
+      this.projectionStore(frame.sessionId).apply(frame.key, frame.value, SessionSeq(frame.seq))
       this.notifier.markDirty()
       return
     }
@@ -688,8 +692,9 @@ export class SessionManager {
 
     for (const [sessionId, block] of Object.entries(baseline.projections)) {
       const store = this.projectionStore(sessionId as SessionId)
-      store.truncate(block.asOfSeq)
-      store.seed(block)
+      const asOfSeq = sessionSeqCursor(block.asOfSeq)
+      store.truncate(asOfSeq)
+      store.seed({ ...block, asOfSeq })
     }
     for (const [sessionId, session] of this.sessions) {
       session.replaceControl(this.queues.get(sessionId) ?? [])
@@ -708,7 +713,7 @@ export class SessionManager {
     if (projections !== undefined) {
       const store = this.projectionStore(summary.sessionId)
       for (const [key, value] of Object.entries(projections.values)) {
-        store.apply(key, value, projections.asOfSeq)
+        store.apply(key, value, sessionSeqCursor(projections.asOfSeq))
       }
     }
     if (summary.origin === 'subagent' && summary.parentSessionId !== undefined) {
diff --git a/packages/api/session-controller/src/client/sessions/projection-store.ts b/packages/api/session-controller/src/client/sessions/projection-store.ts
index fd0ad1b5d2..79ad1b0e62 100644
--- a/packages/api/session-controller/src/client/sessions/projection-store.ts
+++ b/packages/api/session-controller/src/client/sessions/projection-store.ts
@@ -9,6 +9,7 @@
  * bare observable faces feed `useProjection` (ui-renderer binds them).
  */
 import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
+import type { SessionSeqCursor } from '@deepseek-ai/dsh-session/types'
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import { Notifier } from './notifier.ts'
 
@@ -46,7 +47,7 @@ export type UseProjection = {
  */
 export interface ProjectionsBaseline {
   /** The consistent-cut seq (equals the window tail seq by construction). */
-  asOfSeq: number
+  asOfSeq: SessionSeqCursor
   /** Whole current values by key; a registered key absent here means the capability is absent. */
   values: Readonly<Record<string, unknown>>
 }
@@ -54,7 +55,7 @@ export interface ProjectionsBaseline {
 /** One key's row: the latest finished value and the seq it is consistent with. */
 interface Row {
   value: unknown
-  seq: number
+  seq: SessionSeqCursor
 }
 
 /** Per-key notification channel: the bare face plus its batching notifier. */
@@ -130,7 +131,7 @@ export class ProjectionValueStore {
    * @param value - whole value computed by the host unit.
    * @param seq - the unit's watermark at emission.
    */
-  apply(key: string, value: unknown, seq: number): void {
+  apply(key: string, value: unknown, seq: SessionSeqCursor): void {
     const row = this.rows.get(key)
     if (row !== undefined && seq <= row.seq) return // higher seq wins; replays and stale frames drop
     this.rows.set(key, { value, seq })
@@ -165,7 +166,7 @@ export class ProjectionValueStore {
    * baseline immediately afterward.
    * @param lastSeq - highest durable sequence reflected by the baseline.
    */
-  truncate(lastSeq: number): void {
+  truncate(lastSeq: SessionSeqCursor): void {
     for (const [key, row] of this.rows) {
       if (row.seq <= lastSeq) continue
       this.rows.delete(key)
diff --git a/packages/api/session-controller/src/client/sessions/service.ts b/packages/api/session-controller/src/client/sessions/service.ts
index 3e6c8bf6e0..d1d840c513 100644
--- a/packages/api/session-controller/src/client/sessions/service.ts
+++ b/packages/api/session-controller/src/client/sessions/service.ts
@@ -16,7 +16,7 @@
  */
 import type { Context, Fiber } from '@deepseek-ai/cordis'
 import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
 import { workspaceTitleOf } from '@deepseek-ai/dsh-util-workspace-path'
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
 import { SESSION_SEARCH_RESULT_LIMIT } from '../../types.ts'
@@ -438,7 +438,7 @@ export class ClientSessions implements ISessions {
       // Flooring lands inside the anchor's own turn (every turn opens with a
       // turn/start), so the host's first-turn/end-at-or-after cut still ends
       // on that turn — never clipped back to the previous one.
-      ...(opts.atSeq === undefined ? {} : { atSeq: Math.floor(opts.atSeq) }),
+      ...(opts.atSeq === undefined ? {} : { atSeq: SessionSeq(Math.floor(opts.atSeq)) }),
     })
     if (!result.ok) throw new SessionForkError(result.error, opts.sessionId)
     this.projectList()
diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts
index 6e33412cf9..d9d58d41e2 100644
--- a/packages/api/session-controller/src/client/sessions/session.ts
+++ b/packages/api/session-controller/src/client/sessions/session.ts
@@ -5,7 +5,7 @@ import { randomUUID } from '@deepseek-ai/dsh-util-crypto'
 import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { SessionLogOffset, SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
 import { SessionEventStream } from '../transport.ts'
 import type { SessionJournalChange } from '../transport.ts'
 import type {
@@ -13,6 +13,7 @@ import type {
   QueueAction,
   SessionAddress,
   SessionControlFrame,
+  SessionProjectionBaseline,
   SessionQueuedItem,
   SessionRequestId,
 } from '../../types.ts'
@@ -35,6 +36,13 @@ import type { ProjectionsBaseline } from './projection-store.ts'
 import { resolvedClientTimeZone } from '../time-zone.ts'
 import { SessionQueueMirror } from './queue-mirror.ts'
 
+function projectionsBaseline(value: SessionProjectionBaseline): ProjectionsBaseline {
+  return {
+    ...value,
+    asOfSeq: value.asOfSeq === -1 ? -1 : SessionSeq(value.asOfSeq),
+  }
+}
+
 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50
 
@@ -72,7 +80,7 @@ export interface SessionOptions {
  */
 export class Session implements SessionFace {
   // ---- Window and derived state (all private; the snapshot is the only read API) ----
-  private baseSeq = 0
+  private baseSeq = SessionLogOffset(0)
   private hasMore = false
   private openState: OpenState = 'cold'
   private openError: RemoteFailure | null = null
@@ -82,7 +90,7 @@ export class Session implements SessionFace {
   private openGeneration = 0
   private loadingOlder = false
   /** Shared low-water target of the running jump loop; null when no jump is paging. */
-  private jumpTargetSeq: number | null = null
+  private jumpTargetSeq: SessionSeq | null = null
   /** The running jump loop's completion, shared by retargeting callers. */
   private jumpPromise: Promise<void> | null = null
   /** Authoritative stream-only inbox snapshot; pending work never hits history. */
@@ -326,10 +334,12 @@ export class Session implements SessionFace {
    * @param title - raw title text (the host normalizes acceptance).
    * @returns the rename result (normalized accepted title + title event seq).
    */
-  async rename(title: string): Promise<RemoteResult<{ title: string; seq: number }>> {
+  async rename(title: string): Promise<RemoteResult<{ title: string; seq: SessionSeq }>> {
     const result = await this.remote.session.rename({ sessionId: this.sessionId, title })
-    if (result.ok) this.projections.apply('title', result.value.title, result.value.seq)
-    return result
+    if (!result.ok) return result
+    const seq = SessionSeq(result.value.seq)
+    this.projections.apply('title', result.value.title, seq)
+    return { ok: true, value: { title: result.value.title, seq } }
   }
 
   /**
@@ -377,11 +387,11 @@ export class Session implements SessionFace {
   }
 
   /** Jump loader: page backwards until the window covers seq (see ISession.loadThrough). */
-  loadThrough(seq: number): Promise<void> {
+  loadThrough(seq: SessionSeq): Promise<void> {
     if (this.openState !== 'open' || !this.hasMore || this.baseSeq <= seq) return Promise.resolve()
     if (this.jumpPromise !== null) {
       // Retarget the running loop to the lowest requested seq.
-      this.jumpTargetSeq = Math.min(this.jumpTargetSeq ?? seq, seq)
+      this.jumpTargetSeq = SessionSeq(Math.min(this.jumpTargetSeq ?? seq, seq))
       return this.jumpPromise
     }
     // A plain single-page pull owns the busy flag; the jump does not queue
@@ -434,7 +444,7 @@ export class Session implements SessionFace {
     this.openPromise = null
     this.openState = 'cold'
     this.openError = null
-    this.baseSeq = 0
+    this.baseSeq = SessionLogOffset(0)
     this.notifier.markDirty()
     await this.open()
   }
@@ -606,7 +616,11 @@ export class Session implements SessionFace {
   private acceptEventChange(change: SessionJournalChange): void {
     switch (change.type) {
       case 'replace':
-        this.installWindow(change.entries, change.hasMore, change.page.projections)
+        this.installWindow(
+          change.entries,
+          change.hasMore,
+          change.page.projections === undefined ? undefined : projectionsBaseline(change.page.projections),
+        )
         return
       case 'prepend':
         this.prependWindow(change.entries, change.hasMore)
@@ -618,7 +632,7 @@ export class Session implements SessionFace {
 
   /** Replace the complete contiguous window and apply page-owned projection metadata. */
   private installWindow(entries: readonly SessionEventLikeEntry[], hasMore: boolean, projections?: ProjectionsBaseline): void {
-    this.baseSeq = entries[0]?.event.seq ?? 0
+    this.baseSeq = SessionLogOffset(entries[0]?.event.seq ?? 0)
     this.hasMore = hasMore
     if (entries.some(entry => entry.event.type === 'turn/start')) this.firstPromptPendingTurn = false
     if (projections !== undefined) this.projections.seed(projections)
@@ -629,7 +643,7 @@ export class Session implements SessionFace {
 
   /** Prepend one stream-validated history page. */
   private prependWindow(entries: readonly SessionEventLikeEntry[], hasMore: boolean): void {
-    this.baseSeq = entries[0]?.event.seq ?? this.baseSeq
+    this.baseSeq = entries[0] === undefined ? this.baseSeq : SessionLogOffset(entries[0].event.seq)
     this.hasMore = hasMore
     this.eventSource.prepend(entries, hasMore)
   }
diff --git a/packages/api/session-controller/src/commands.ts b/packages/api/session-controller/src/commands.ts
index 701aedcc36..0e8015f79c 100644
--- a/packages/api/session-controller/src/commands.ts
+++ b/packages/api/session-controller/src/commands.ts
@@ -10,6 +10,7 @@ import {
   ReasoningEffortId, createUserMessage, freezeMessage,
 } from '@deepseek-ai/dsh-llm'
 import type { MessageSource } from '@deepseek-ai/dsh-llm'
+import { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query'
 import { SessionTitleInvalidError } from '@deepseek-ai/dsh-session-title'
@@ -185,9 +186,11 @@ export class SessionCommandController {
    * @returns the new Session identity.
    */
   async fork(request: SessionForkRequest): Promise<SessionForkValue> {
-    if (request.atSeq !== undefined
-      && (!Number.isInteger(request.atSeq) || request.atSeq < 0)) {
-      throw new RemoteError('gateway/bad-request', 'atSeq must be a non-negative integer', {})
+    let atSeq: ReturnType<typeof SessionSeq> | undefined
+    try {
+      atSeq = request.atSeq === undefined ? undefined : SessionSeq(request.atSeq)
+    } catch {
+      throw new RemoteError('gateway/bad-request', 'atSeq must be a non-negative safe integer', {})
     }
     let observed: SessionObservation
     try {
@@ -207,7 +210,6 @@ export class SessionCommandController {
     }
     using source = observed
     const lastSeq = source.events.at(-1)?.seq ?? -1
-    const atSeq = request.atSeq
     const anchoredBoundary = atSeq === undefined
       ? undefined
       : source.events.find(event => event.type === 'turn/end' && event.seq >= atSeq)
@@ -224,8 +226,10 @@ export class SessionCommandController {
         { sessionId: request.sessionId },
       )
     }
-    let cut = boundary.seq + 1
-    while (cut < source.events.length && source.events[cut]?.type !== 'turn/start') cut++
+    let cut = SessionLogOffset(boundary.seq + 1)
+    while (cut < source.events.length && source.events[cut]?.type !== 'turn/start') {
+      cut = SessionLogOffset(cut + 1)
+    }
     let workspace: Workspace | undefined
     try {
       workspace = await this.forkWorkspace(source.header)
@@ -243,10 +247,11 @@ export class SessionCommandController {
       await this.ctx.agents.create({
         sessionId: childId,
         seed: source.events.slice(0, cut),
+        inheritedEventCount: cut,
         meta: {
           ...(source.header.cwd === undefined ? {} : { cwd: source.header.cwd }),
           parentSession: source.header.id,
-          seedLength: cut,
+          isSeeded: true,
           ...(composition.agentPreset === undefined
             ? {}
             : { agentPreset: composition.agentPreset }),
diff --git a/packages/api/session-controller/src/history.ts b/packages/api/session-controller/src/history.ts
index 7264e8cb82..9609da3fb5 100644
--- a/packages/api/session-controller/src/history.ts
+++ b/packages/api/session-controller/src/history.ts
@@ -2,9 +2,19 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { Deque } from '@deepseek-ai/dsh-deque'
-import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session'
+import {
+  isAppendSurfaceEvent,
+  SessionLogOffset,
+  SessionSeq,
+} from '@deepseek-ai/dsh-session'
 import { isChunkRow, packChunkRuns, type ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
-import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type {
+  SessionEvent,
+  SessionHeader,
+  SessionId,
+  SessionLogOffset as SessionLogOffsetType,
+  SessionSeqCursor,
+} from '@deepseek-ai/dsh-session'
 import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query'
 import type {} from '@deepseek-ai/dsh-subagent'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
@@ -19,6 +29,7 @@ import type {
   SessionPageRequest,
   SessionProjectionBaseline,
   SessionProjectionValues,
+  SessionWireHeader,
   SessionWireEvent,
 } from './types.ts'
 
@@ -51,26 +62,32 @@ export class SessionHistoryController {
    */
   async page(request: SessionPageRequest, signal: AbortSignal): Promise<SessionPage> {
     validatePageRequest(request)
+    const throughSeq: SessionSeqCursor = request.throughSeq === -1
+      ? -1
+      : SessionSeq(request.throughSeq)
+    const beforeSeq = request.beforeSeq === undefined
+      ? undefined
+      : SessionLogOffset(request.beforeSeq)
     using source = await this.sourceFor(request.address, signal, false)
     signal.throwIfAborted()
     const sourceLog = source.events
-    const sourceCursor = sourceLog.at(-1)?.seq ?? -1
-    if (request.throughSeq > sourceCursor) {
+    const sourceCursor: SessionSeqCursor = sourceLog.at(-1)?.seq ?? -1
+    if (throughSeq > sourceCursor) {
       throw new RemoteError(
         'gateway/bad-request',
-        `session page through seq ${String(request.throughSeq)} is past cursor ${String(sourceCursor)}`,
+        `session page through seq ${String(throughSeq)} is past cursor ${String(sourceCursor)}`,
         {},
       )
     }
     /* v8 ignore next -- Session and persistence validation guarantee a dense zero-based event prefix. */
-    if (request.throughSeq >= 0 && sourceLog[request.throughSeq]?.seq !== request.throughSeq) {
-      throw new RemoteError('gateway/internal', `session log does not contain through seq ${String(request.throughSeq)}`, {})
+    if (throughSeq >= 0 && sourceLog[throughSeq]?.seq !== throughSeq) {
+      throw new RemoteError('gateway/internal', `session log does not contain through seq ${String(throughSeq)}`, {})
     }
     const page = paginate(
       sourceLog,
-      request.beforeSeq,
+      beforeSeq,
       request.maxMessages ?? DEFAULT_MAX_MESSAGES,
-      request.throughSeq,
+      throughSeq,
     )
     const records = pageRecords(page.events)
     return {
@@ -90,7 +107,7 @@ export class SessionHistoryController {
     const { address } = request
     const target = addressId(address)
     const buffered = new Deque<SessionEvent>()
-    let snapshotCursor: number | undefined
+    let snapshotCursor: SessionSeqCursor | undefined
     let wake: (() => void) | undefined
     const notify = (): void => {
       const resume = wake
@@ -115,7 +132,7 @@ export class SessionHistoryController {
       // opening observation, replay everything beyond that snapshot cursor.
       const suffix = session.snapshotEvents(snapshotCursor === undefined
         ? session.firstLiveSeq
-        : snapshotCursor + 1)
+        : SessionLogOffset(snapshotCursor + 1))
       for (let index = suffix.length - 1; index >= 0; index -= 1) {
         buffered.pushFront(suffix[index] as SessionEvent)
       }
@@ -132,7 +149,7 @@ export class SessionHistoryController {
       const page = paginate(events, undefined, request.maxMessages ?? DEFAULT_MAX_MESSAGES)
       yield {
         type: 'snapshot',
-        header: source.header,
+        header: wireHeader(source.header, source.inheritedEventCount),
         cursor,
         records: pageRecords(page.events),
         hasMore: page.hasMore,
@@ -149,18 +166,19 @@ export class SessionHistoryController {
           throw error
         }
       }
-      let nextSeq = cursor + 1
+      let nextOffset = SessionLogOffset(cursor + 1)
       while (!follower.closed && !signal.aborted) {
         const item = buffered.popFront()
         if (item === undefined) {
           await new Promise<void>((resolve) => { wake = resolve })
           continue
         }
-        if (item.seq < nextSeq) continue
-        if (item.seq !== nextSeq) {
-          throw new RemoteError('gateway/internal', `session event stream skipped seq ${String(nextSeq)}`, {})
+        const expectedSeq = SessionSeq(nextOffset)
+        if (item.seq < expectedSeq) continue
+        if (item.seq !== expectedSeq) {
+          throw new RemoteError('gateway/internal', `session event stream skipped seq ${String(expectedSeq)}`, {})
         }
-        nextSeq++
+        nextOffset = SessionLogOffset(nextOffset + 1)
         yield entryFor(item)
       }
     } finally {
@@ -187,7 +205,12 @@ export class SessionHistoryController {
         rejectNotFound(address)
       }
       try {
-        validateAddress(address, observation.header, observation.projections)
+        validateAddress(
+          address,
+          observation.header,
+          observation.inheritedEventCount,
+          observation.projections,
+        )
       } catch (error: unknown) {
         observation[Symbol.dispose]()
         throw error
@@ -213,11 +236,15 @@ function projectionBlock(
 }
 
 function validatePageRequest(request: SessionPageRequest): void {
-  if (!Number.isSafeInteger(request.throughSeq) || request.throughSeq < -1) {
+  if (!Number.isSafeInteger(request.throughSeq)
+    || request.throughSeq < -1
+    || Object.is(request.throughSeq, -0)) {
     throw new RemoteError('gateway/bad-request', 'throughSeq must be an integer greater than or equal to -1', {})
   }
   if (request.beforeSeq !== undefined
-    && (!Number.isSafeInteger(request.beforeSeq) || request.beforeSeq < 0)) {
+    && (!Number.isSafeInteger(request.beforeSeq)
+      || request.beforeSeq < 0
+      || Object.is(request.beforeSeq, -0))) {
     throw new RemoteError('gateway/bad-request', 'beforeSeq must be a non-negative safe integer', {})
   }
   if (request.maxMessages !== undefined
@@ -240,6 +267,7 @@ function addressId(address: SessionAddress): SessionId {
 function validateAddress(
   address: SessionAddress,
   header: SessionHeader,
+  inheritedEventCount: SessionLogOffsetType,
   projections: SessionObservation['projections'],
 ): void {
   if (address.kind === 'session') {
@@ -263,7 +291,7 @@ function validateAddress(
       reason: 'corrupt',
     })
   }
-  if (identity === undefined || identity.seq < (header.seedLength ?? 0)) {
+  if (identity === undefined || identity.seq < inheritedEventCount) {
     throw new RemoteError('subagent/catalog-diagnostic', 'subagent descriptor is unavailable', {
       parentSessionId: address.parentSessionId,
       childSessionId: address.childSessionId,
@@ -289,30 +317,44 @@ function rejectNotFound(address: SessionAddress): never {
 
 function paginate(
   events: readonly SessionEvent[],
-  beforeSeq: number | undefined,
+  beforeSeq: SessionLogOffsetType | undefined,
   maxMessages: number,
-  throughSeq = events.at(-1)?.seq ?? -1,
+  throughSeq: SessionSeqCursor = events.at(-1)?.seq ?? -1,
 ): { readonly events: SessionEvent[]; readonly hasMore: boolean } {
-  const end = Math.min(throughSeq + 1, beforeSeq ?? throughSeq + 1)
+  const end = SessionLogOffset(Math.min(throughSeq + 1, beforeSeq ?? throughSeq + 1))
   let count = 0
-  let cut = 0
+  let cut = SessionLogOffset(0)
   for (let index = end - 1; index >= 0; index--) {
     const event = events[index] as SessionEvent
     if (!MESSAGE_TYPES.has(event.type) || !isAppendSurfaceEvent(event)) continue
     count++
-    const sources = (event as { readonly sourceEventSeqs?: readonly number[] }).sourceEventSeqs
+    const sources = event.sourceEventSeqs
     let groupStart = event.seq
     if (sources !== undefined) {
-      for (const source of sources) groupStart = Math.min(groupStart, source)
+      for (const source of sources) {
+        if (source < groupStart) groupStart = source
+      }
     }
     if (count >= maxMessages) {
-      cut = groupStart
+      cut = SessionLogOffset(groupStart)
       break
     }
   }
   return { events: events.slice(cut, end), hasMore: cut > 0 }
 }
 
+/** Translate logical Session metadata to the unchanged v0 browser wire. */
+function wireHeader(
+  header: SessionHeader,
+  inheritedEventCount: SessionLogOffsetType,
+): SessionWireHeader {
+  const { isSeeded, ...wire } = header
+  return {
+    ...wire,
+    ...isSeeded ? { seedLength: inheritedEventCount } : {},
+  }
+}
+
 function entryFor(event: SessionEvent): SessionEventEntry {
   return {
     type: 'event',
diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts
index 4a103dbd22..759c6b7f89 100644
--- a/packages/api/session-controller/src/index.ts
+++ b/packages/api/session-controller/src/index.ts
@@ -4,7 +4,8 @@ import { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import { canOpenNativePath, openNativePath } from '@deepseek-ai/dsh-native-command'
-import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence'
 import type { SessionObservation } from '@deepseek-ai/dsh-session-query'
 import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import {
@@ -191,10 +192,14 @@ export class SessionController extends TypertRemoteService {
   inspect(
     sessionId: SessionId,
     signal?: AbortSignal,
-  ): Promise<{ meta: SessionHeader; events: readonly SessionEvent[] }> {
+  ): Promise<SessionInspection> {
     const attached = this.ctx.sessions.get(sessionId)
     if (attached !== undefined) {
-      return Promise.resolve({ meta: attached.header, events: attached.snapshotEvents() })
+      return Promise.resolve({
+        meta: attached.header,
+        inheritedEventCount: attached.inheritedEventCount,
+        events: attached.snapshotEvents(),
+      })
     }
     return inspectApiSession(this.ctx, sessionId, signal)
   }
diff --git a/packages/api/session-controller/src/list.ts b/packages/api/session-controller/src/list.ts
index ab72da1c92..145c77c63a 100644
--- a/packages/api/session-controller/src/list.ts
+++ b/packages/api/session-controller/src/list.ts
@@ -4,6 +4,7 @@ import { stat } from 'node:fs/promises'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-agent-presets'
 import type { ImageAttachmentLimits } from '@deepseek-ai/dsh-attachment'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-session-projection'
 import type {} from '@deepseek-ai/dsh-session-projection-cache'
@@ -329,7 +330,9 @@ export class ApiSessionList {
   ): SessionProjectionHints | undefined {
     try {
       const block = session === undefined
-        ? this.ctx.get('sessionProjectionCache')?.cachedSnapshot(header)
+        ? header.isSeeded
+          ? undefined
+          : this.ctx.get('sessionProjectionCache')?.cachedSnapshot(header, SessionLogOffset(0))
         : this.ctx.sessionProjections.cachedSnapshot(session)
       return block !== undefined && Object.keys(block.values).length > 0
         ? {
diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts
index c0b25fcf2c..2e2a0d7c46 100644
--- a/packages/api/session-controller/src/types.ts
+++ b/packages/api/session-controller/src/types.ts
@@ -7,7 +7,7 @@ import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
-import type { SessionHeader, SessionId, SurfaceOp } from '@deepseek-ai/dsh-session/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
 import type { JobId } from '@deepseek-ai/dsh-jobs/brand'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
@@ -384,6 +384,25 @@ export interface SessionEventEntry {
   readonly event: SessionWireEvent
 }
 
+/** v0-compatible Session metadata carried on the browser wire. */
+export interface SessionWireHeader {
+  readonly version: number
+  readonly id: SessionId
+  readonly createdAt: number
+  readonly cwd?: string
+  readonly parentSession?: SessionId
+  /** Exact inherited prefix length; absent for an unseeded Session. */
+  readonly seedLength?: number
+  readonly origin?: 'subagent'
+  readonly delegationDepth?: number
+  readonly agentPreset?: string
+}
+
+/** Browser wire form of one Session surface operation. */
+export type SessionWireSurfaceOp =
+  | 'append'
+  | { readonly op: 'replace'; readonly start: number; readonly end: number }
+
 /** Event-shaped wire representation of one packed chunk row. */
 export type ChunkRowEvent = {
   [Kind in ChunkRow['type']]: {
@@ -411,7 +430,7 @@ export interface SessionWireEvent {
   readonly data: JsonValue
   readonly ignorable?: true
   readonly sourceEventSeqs?: number[]
-  readonly surfaceOp?: SurfaceOp
+  readonly surfaceOp?: SessionWireSurfaceOp
 }
 
 /** One message-aligned backwards-history request. */
@@ -439,7 +458,7 @@ export interface SessionPage {
 export type SessionFollowFrame =
   | {
     readonly type: 'snapshot'
-    readonly header: SessionHeader
+    readonly header: SessionWireHeader
     readonly cursor: number
     readonly records: readonly SessionHistoryRecord[]
     readonly hasMore: boolean
diff --git a/packages/api/session-controller/tests/agent.host.spec.ts b/packages/api/session-controller/tests/agent.host.spec.ts
index 922e0c8e2c..3d370bcf28 100644
--- a/packages/api/session-controller/tests/agent.host.spec.ts
+++ b/packages/api/session-controller/tests/agent.host.spec.ts
@@ -5,9 +5,10 @@ import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { agentPresetProjectionDefinition } from '@deepseek-ai/dsh-agent-presets'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import type { SessionObservation } from '@deepseek-ai/dsh-session-query'
+import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence'
 import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
@@ -47,10 +48,19 @@ function header(id: string, cwd: string | null = '/workspace'): SessionHeader {
     version: 0,
     id: SessionId(id),
     createdAt: 1,
+    isSeeded: false,
     ...(cwd === null ? {} : { cwd }),
   }
 }
 
+function unseededInspection(
+  meta: SessionHeader,
+  events: readonly SessionEvent[] = [],
+): SessionInspection {
+  if (meta.isSeeded) throw new Error('seeded inspection fixtures require an explicit inherited cut')
+  return { meta, inheritedEventCount: SessionLogOffset(0), events }
+}
+
 function providePersistence(ctx: Context, persistence: Record<string, unknown>): () => void {
   return ctx.provide('sessionPersistence', testSessionPersistence(ctx, persistence) as never)
 }
@@ -97,7 +107,7 @@ describe('ApiSession identity failures', () => {
     const listed = header('cwd-less-catalog', null)
     const disposeListed = providePersistence(ctx, {
       list: () => Promise.resolve([listed]),
-      inspect: () => Promise.resolve({ meta: listed, events: [] }),
+      inspect: () => Promise.resolve(unseededInspection(listed)),
     })
     await expect(inspectApiSession(ctx, listed.id)).rejects.toBeInstanceOf(ApiSessionNotFound)
     disposeListed()
@@ -106,7 +116,7 @@ describe('ApiSession identity failures', () => {
     const inspected = header('cwd-less-inspect', null)
     providePersistence(ctx, {
       list: () => Promise.resolve([catalog]),
-      inspect: () => Promise.resolve({ meta: inspected, events: [] }),
+      inspect: () => Promise.resolve(unseededInspection(inspected)),
     })
     await expect(inspectApiSession(ctx, catalog.id)).rejects.toBeInstanceOf(ApiSessionNotFound)
   })
@@ -117,11 +127,11 @@ describe('ApiSession identity failures', () => {
     await ctx.plugin(SessionStore)
     installSessionReadTestServices(ctx)
     const meta = header('signalled-inspection')
-    const inspect = vi.fn(() => Promise.resolve({ meta, events: [] }))
+    const inspect = vi.fn(() => Promise.resolve(unseededInspection(meta)))
     providePersistence(ctx, { inspect })
     const signal = new AbortController().signal
 
-    await expect(inspectApiSession(ctx, meta.id, signal)).resolves.toEqual({ meta, events: [] })
+    await expect(inspectApiSession(ctx, meta.id, signal)).resolves.toEqual(unseededInspection(meta))
     expect(inspect).toHaveBeenCalledWith(meta.id, signal)
   })
 })
@@ -138,6 +148,7 @@ describe('ApiSession Agent lookup and recovery', () => {
     const observed = {
       source: 'prepared',
       header: meta,
+      inheritedEventCount: SessionLogOffset(0),
       events: [],
       cursor: -1,
       projections: { asOfSeq: -1, values: {} },
@@ -177,7 +188,7 @@ describe('ApiSession Agent lookup and recovery', () => {
     const ordinaryMeta = header('ordinary-race')
     providePersistence(ordinary.ctx, {
       list: () => Promise.resolve([ordinaryMeta]),
-      inspect: () => Promise.resolve({ meta: ordinaryMeta, events: [] }),
+      inspect: () => Promise.resolve(unseededInspection(ordinaryMeta)),
     })
     const winner = agent(ordinary.ctx, ordinaryMeta)
     vi.spyOn(ordinary.ctx.agents, 'resume').mockImplementation(async () => {
@@ -190,7 +201,7 @@ describe('ApiSession Agent lookup and recovery', () => {
     const childMeta = header('child-race')
     providePersistence(child.ctx, {
       list: () => Promise.resolve([childMeta]),
-      inspect: () => Promise.resolve({ meta: childMeta, events: [] }),
+      inspect: () => Promise.resolve(unseededInspection(childMeta)),
     })
     vi.spyOn(child.ctx.agents, 'resume').mockImplementation(async () => {
       child.ctx.sessions.create(childMeta.id, {
@@ -217,7 +228,7 @@ describe('ApiSession Agent lookup and recovery', () => {
     const meta = header('failed')
     providePersistence(failed.ctx, {
       list: () => Promise.resolve([meta]),
-      inspect: () => Promise.resolve({ meta, events: [] }),
+      inspect: () => Promise.resolve(unseededInspection(meta)),
     })
     vi.spyOn(failed.ctx.agents, 'resume').mockRejectedValue(new Error('factory unavailable'))
     await expect(failed.agents.resolveAgent(meta.id)).resolves.toMatchObject({
@@ -231,6 +242,7 @@ describe('ApiSession Agent lookup and recovery', () => {
     const observed = {
       source: 'prepared',
       header: meta,
+      inheritedEventCount: SessionLogOffset(0),
       events: [],
       cursor: -1,
       retain: vi.fn(),
@@ -363,27 +375,27 @@ describe('ApiSession create or adoption', () => {
     const meta = { ...header('stored'), agentPreset: 'minimal' }
     const events = [{
       type: 'agent-preset/selected',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { agentPreset: 'minimal' },
     }] as SessionEvent[]
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
-      inspect: () => Promise.resolve({ meta, events }),
+      inspect: () => Promise.resolve(unseededInspection(meta, events)),
     })
     ctx.provide('agentPresets', {
       resolve: (id?: string) => Promise.resolve({ id: id ?? 'minimal' }),
       mount: () => Promise.resolve(),
     } as never)
+    const resumedSession = ctx.sessions.prepare(meta.id, {
+      seed: structuredClone(events),
+      meta: structuredClone(meta),
+      inheritedEventCount: SessionLogOffset(0),
+      seedSource: 'persistence',
+    })
     const resumed = {
       id: meta.id,
-      session: {
-        id: meta.id,
-        header: meta,
-        snapshotEvents: () => events,
-        eventAt: (seq: number) => events[seq],
-        seq: events.length,
-      },
+      session: resumedSession,
       status: 'idle',
       ctx,
     } as unknown as Agent
@@ -401,7 +413,7 @@ describe('ApiSession create or adoption', () => {
     const childMeta = header('resume-child-race')
     providePersistence(child.ctx, {
       list: () => Promise.resolve([childMeta]),
-      inspect: () => Promise.resolve({ meta: childMeta, events: [] }),
+      inspect: () => Promise.resolve(unseededInspection(childMeta)),
     })
     child.ctx.provide('agentPresets', {
       resolve: () => {
@@ -420,7 +432,7 @@ describe('ApiSession create or adoption', () => {
     const stored = header('stored-cwd-conflict', '/stored')
     providePersistence(conflict.ctx, {
       list: () => Promise.resolve([stored]),
-      inspect: () => Promise.resolve({ meta: stored, events: [] }),
+      inspect: () => Promise.resolve(unseededInspection(stored)),
     })
     await expect(conflict.agents.ensureSession(stored.id, '/requested', true))
       .rejects.toBeInstanceOf(ApiSessionCwdConflict)
diff --git a/packages/api/session-controller/tests/client-contract.client.spec.ts b/packages/api/session-controller/tests/client-contract.client.spec.ts
index bb9cd172ce..689d5a407b 100644
--- a/packages/api/session-controller/tests/client-contract.client.spec.ts
+++ b/packages/api/session-controller/tests/client-contract.client.spec.ts
@@ -1,11 +1,18 @@
 import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import type { PromptContentPart as AttachmentPromptContentPart } from '@deepseek-ai/dsh-attachment/types'
+import { SessionSeq, type SessionSeqCursor } from '@deepseek-ai/dsh-session/types'
 import {
   MutableSessionEventSource, type SessionLiveEventEntry,
 } from '../src/client/contract/events.ts'
-import type { PromptContentPart as SessionPromptContentPart } from '../src/types.ts'
+import type { ISession } from '../src/client/contract/session.ts'
+import type { ProjectionsBaseline } from '../src/client/sessions/projection-store.ts'
+import { ProjectionValueStore } from '../src/client/sessions/projection-store.ts'
+import type { PromptContentPart as SessionPromptContentPart, SessionPageRequest } from '../src/types.ts'
+import { ev, plainTurn } from './event-script.client.ts'
 
-function entry(seq: number): SessionLiveEventEntry {
+type RenameSuccess = Extract<Awaited<ReturnType<ISession['rename']>>, { readonly ok: true }>
+
+function entry(seq: SessionSeq): SessionLiveEventEntry {
   return {
     type: 'event',
     event: {
@@ -18,6 +25,23 @@ function entry(seq: number): SessionLiveEventEntry {
 }
 
 describe('Client Session contracts', () => {
+  it('requires branded Session positions at internal event fixture boundaries', () => {
+    expectTypeOf(entry).parameter(0).toEqualTypeOf<SessionSeq>()
+    expectTypeOf(ev.user).parameter(0).toEqualTypeOf<SessionSeq>()
+    expectTypeOf(ev.commandDone).parameter(4).toEqualTypeOf<SessionSeq | undefined>()
+    expectTypeOf(ev.compactSummary).parameter(2).toEqualTypeOf<SessionSeq>()
+    expectTypeOf(ev.compactCheckpoint).parameter(1).toEqualTypeOf<SessionSeq>()
+    expectTypeOf(plainTurn).parameter(0).toEqualTypeOf<SessionSeq>()
+  })
+
+  it('brands same-process Session event positions while keeping the API wire numeric', () => {
+    expectTypeOf<ISession['loadThrough']>().parameter(0).toEqualTypeOf<SessionSeq>()
+    expectTypeOf<RenameSuccess['value']['seq']>().toEqualTypeOf<SessionSeq>()
+    expectTypeOf<ProjectionValueStore['apply']>().parameter(2).toEqualTypeOf<SessionSeqCursor>()
+    expectTypeOf<ProjectionsBaseline['asOfSeq']>().toEqualTypeOf<SessionSeqCursor>()
+    expectTypeOf<SessionPageRequest['throughSeq']>().toEqualTypeOf<number>()
+  })
+
   it('keeps its catalog-visible prompt parts identical to attachment intake', () => {
     expectTypeOf<SessionPromptContentPart>().toEqualTypeOf<AttachmentPromptContentPart>()
   })
@@ -26,9 +50,9 @@ describe('Client Session contracts', () => {
     const feed = new MutableSessionEventSource()
     const listener = vi.fn()
     const dispose = feed.subscribe(listener)
-    const first = entry(1)
-    const older = entry(0)
-    const live = entry(2)
+    const first = entry(SessionSeq(1))
+    const older = entry(SessionSeq(0))
+    const live = entry(SessionSeq(2))
 
     feed.replace([first], true)
     expect(feed.getSnapshot()).toEqual({
@@ -56,13 +80,13 @@ describe('Client Session contracts', () => {
     expect(listener).toHaveBeenCalledTimes(3)
 
     dispose()
-    feed.append(entry(3))
+    feed.append(entry(SessionSeq(3)))
     expect(listener).toHaveBeenCalledTimes(3)
   })
 
   it('does not traverse the complete event window while appending', () => {
     const feed = new MutableSessionEventSource()
-    const first = entry(1)
+    const first = entry(SessionSeq(1))
     const base = [first]
     const iterate = vi.fn(Array.prototype[Symbol.iterator].bind(base))
     Object.defineProperty(base, Symbol.iterator, { value: iterate })
@@ -70,7 +94,7 @@ describe('Client Session contracts', () => {
     iterate.mockClear()
 
     const before = feed.getSnapshot()
-    const live = entry(2)
+    const live = entry(SessionSeq(2))
     feed.append(live)
     const after = feed.getSnapshot()
 
diff --git a/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts b/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts
index 97bd98e093..f437ed27a7 100644
--- a/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts
+++ b/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts
@@ -4,7 +4,7 @@ import type { Agent, ModelSelectionRef } from '@deepseek-ai/dsh-agent'
 import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import { createAssistantMessage, createUserMessage, MessageId } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import { describe, expect, it, vi } from 'vitest'
 import { ApiSessionAgentController } from '../src/agent.ts'
@@ -131,7 +131,7 @@ function imageRef(id: string): ImageAttachmentRef {
   }
 }
 
-function event(type: string, seq: number, data: unknown): SessionEvent {
+function event(type: string, seq: SessionSeq, data: unknown): SessionEvent {
   return { type, seq, time: seq + 1, data } as SessionEvent
 }
 
@@ -142,10 +142,20 @@ async function persistedController(
   const ctx = new Context()
   await ctx.plugin(SessionStore)
   const sessionId = SessionId('cold-attachment')
-  const meta: SessionHeader = { version: 0, id: sessionId, createdAt: 1, cwd: '/workspace' }
+  const meta: SessionHeader = {
+    version: 0,
+    id: sessionId,
+    createdAt: 1,
+    cwd: '/workspace',
+    isSeeded: false,
+  }
   ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
     list: () => Promise.resolve([meta]),
-    inspect: () => Promise.resolve({ meta, events }),
+    inspect: () => Promise.resolve({
+      meta,
+      inheritedEventCount: SessionLogOffset(0),
+      events,
+    }),
   }) as never)
   installSessionReadTestServices(ctx)
   ctx.provide('attachments', { readImage } as never)
@@ -160,12 +170,12 @@ describe('Session attachment authorization', () => {
     const inserted = imageRef('inserted')
     const streamed = imageRef('streamed')
     const events = [
-      { ...event('fixture/direct', 0, {
+      { ...event('fixture/direct', SessionSeq(0), {
         content: [null, [], { type: 'tool-result', content: [{ type: 'text', text: 'none' }] }, {
           type: 'tool-result', content: [{ type: 'image', attachment: nested }],
         }],
       }), ignorable: true as const },
-      { ...event('assistant/message', 1, {
+      { ...event('assistant/message', SessionSeq(1), {
         turn: 1,
         step: 1,
         message: createAssistantMessage({
@@ -173,7 +183,7 @@ describe('Session attachment authorization', () => {
           source: { provider: 'fixture', model: 'fixture' },
         }),
       }), surfaceOp: 'append' as const },
-      event('agent/inbox/spliced', 2, {
+      event('agent/inbox/spliced', SessionSeq(2), {
         target: 'next-turn',
         start: 0,
         inserted: [createUserMessage({
@@ -181,7 +191,7 @@ describe('Session attachment authorization', () => {
           source: { kind: 'user' },
         })],
       }),
-      event('assistant/chunk', 3, {
+      event('assistant/chunk', SessionSeq(3), {
         turn: 1,
         step: 1,
         chunk: { type: 'block-end', index: 0, block: { type: 'image', attachment: streamed } },
@@ -233,7 +243,7 @@ describe('Session attachment authorization', () => {
     ]) {
       const ref = imageRef(`failure-${thrown.name}`)
       const fixture = await persistedController(
-        [event('fixture/content', 0, { content: [{ type: 'image', attachment: ref }] })],
+        [event('fixture/content', SessionSeq(0), { content: [{ type: 'image', attachment: ref }] })],
         () => Promise.reject(thrown),
       )
       await expectFailure(fixture.controller.attachment({
diff --git a/packages/api/session-controller/tests/controller.host.spec.ts b/packages/api/session-controller/tests/controller.host.spec.ts
index f31c2cb3c7..ef5001cbe2 100644
--- a/packages/api/session-controller/tests/controller.host.spec.ts
+++ b/packages/api/session-controller/tests/controller.host.spec.ts
@@ -2,7 +2,7 @@ import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
 import { describe, expect, it, vi } from 'vitest'
@@ -30,9 +30,14 @@ describe('SessionController facade', () => {
       id: sessionId,
       createdAt: 1,
       cwd: '/workspace',
+      isSeeded: false,
     }
     const events: SessionEvent[] = []
-    const inspect = vi.fn(() => Promise.resolve({ meta: header, events }))
+    const inspect = vi.fn(() => Promise.resolve({
+      meta: header,
+      inheritedEventCount: SessionLogOffset(0),
+      events,
+    }))
     ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list: () => Promise.resolve([header]),
       inspect,
@@ -45,7 +50,11 @@ describe('SessionController facade', () => {
     ctx.on('api-session/error', failure)
     ctx.on('api-session/activity', activity)
 
-    await expect(controller.inspect(sessionId)).resolves.toEqual({ meta: header, events })
+    await expect(controller.inspect(sessionId)).resolves.toEqual({
+      meta: header,
+      inheritedEventCount: SessionLogOffset(0),
+      events,
+    })
     expect(inspect).toHaveBeenCalledOnce()
 
     const session = ctx.sessions.create(sessionId, { meta: header })
@@ -62,7 +71,11 @@ describe('SessionController facade', () => {
     )
 
     await expect(controller.resolveAgent(sessionId)).resolves.toEqual({ agent })
-    await expect(controller.inspect(sessionId)).resolves.toEqual({ meta: header, events })
+    await expect(controller.inspect(sessionId)).resolves.toEqual({
+      meta: header,
+      inheritedEventCount: SessionLogOffset(0),
+      events,
+    })
     expect(inspect).toHaveBeenCalledOnce()
     ctx.emit('agent/status', { agent, status: 'running' })
     ctx.emit('agent/error', { agent, turn: 1, step: 0, error: new Error('fixture failure') })
@@ -109,11 +122,15 @@ describe('SessionController facade', () => {
       await ctx.plugin(AgentRegistry)
       const sessionId = SessionId(`background-${outcome}`)
       const header: SessionHeader = {
-        version: 0, id: sessionId, createdAt: 1, cwd: '/workspace',
+        version: 0, id: sessionId, createdAt: 1, cwd: '/workspace', isSeeded: false,
       }
       ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
         list: () => Promise.resolve([header]),
-        inspect: () => Promise.resolve({ meta: header, events: [] }),
+        inspect: () => Promise.resolve({
+          meta: header,
+          inheritedEventCount: SessionLogOffset(0),
+          events: [],
+        }),
       }) as never)
       const controller = createSessionTestController(ctx, defaults)
       const agents = (controller as unknown as { agents: ApiSessionAgentController }).agents
@@ -161,11 +178,15 @@ describe('SessionController facade', () => {
     await ctx.plugin(AgentRegistry)
     const sessionId = SessionId('background-disposal')
     const header: SessionHeader = {
-      version: 0, id: sessionId, createdAt: 1, cwd: '/workspace',
+      version: 0, id: sessionId, createdAt: 1, cwd: '/workspace', isSeeded: false,
     }
     ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list: () => Promise.resolve([header]),
-      inspect: () => Promise.resolve({ meta: header, events: [] }),
+      inspect: () => Promise.resolve({
+        meta: header,
+        inheritedEventCount: SessionLogOffset(0),
+        events: [],
+      }),
     }) as never)
     const controller = createSessionTestController(ctx, defaults)
     const agents = (controller as unknown as { agents: ApiSessionAgentController }).agents
diff --git a/packages/api/session-controller/tests/event-script.client.ts b/packages/api/session-controller/tests/event-script.client.ts
index 0d8deb5e27..17cd7775fb 100644
--- a/packages/api/session-controller/tests/event-script.client.ts
+++ b/packages/api/session-controller/tests/event-script.client.ts
@@ -1,6 +1,7 @@
 import {
   ToolCallId, createMessage, createToolResultMessage, createUserMessage,
 } from '@deepseek-ai/dsh-llm'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 // Minimal SessionEvent builders for orchestration tests (shape mirrors what the
 // host emits; only the fields the object layer reads).
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
@@ -14,23 +15,23 @@ import type {
 /** One text content block (local helper). */
 const text = (t: string): ContentBlock[] => [{ type: 'text', text: t }]
 
-const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+const at = (seq: SessionSeq, e: Record<string, unknown>): SessionEvent =>
   ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
 
 export const ev = {
-  turnStart: (seq: number, turn: number): SessionEvent =>
+  turnStart: (seq: SessionSeq, turn: number): SessionEvent =>
     at(seq, { type: 'turn/start', data: { turn } }),
-  user: (seq: number, body: string): SessionEvent =>
+  user: (seq: SessionSeq, body: string): SessionEvent =>
     at(seq, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
       content: text(body), source: { kind: 'user' },
     }) }),
-  stepStart: (seq: number, turn: number, step = 0): SessionEvent =>
+  stepStart: (seq: SessionSeq, turn: number, step = 0): SessionEvent =>
     at(seq, { type: 'step/start', data: { turn, step } }),
-  chunkStart: (seq: number, turn: number, step = 0, index = 0): SessionEvent =>
+  chunkStart: (seq: SessionSeq, turn: number, step = 0, index = 0): SessionEvent =>
     at(seq, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'block-start', index, blockType: 'text' } } }),
-  chunkText: (seq: number, turn: number, piece: string, step = 0, index = 0): SessionEvent =>
+  chunkText: (seq: SessionSeq, turn: number, piece: string, step = 0, index = 0): SessionEvent =>
     at(seq, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'text-delta', index, text: piece } } }),
-  assistant: (seq: number, turn: number, body: string, step = 0): SessionEvent =>
+  assistant: (seq: SessionSeq, turn: number, body: string, step = 0): SessionEvent =>
     at(seq, { type: 'assistant/message', surfaceOp: 'append', data: {
       turn, step,
       message: createMessage({
@@ -42,9 +43,9 @@ export const ev = {
         },
       }),
     } }),
-  toolCall: (seq: number, turn: number, callId: string, name: string, args: string, step = 0): SessionEvent =>
+  toolCall: (seq: SessionSeq, turn: number, callId: string, name: string, args: string, step = 0): SessionEvent =>
     at(seq, { type: 'tool/call', data: { turn, step, callId, name, arguments: args } }),
-  toolResult: (seq: number, turn: number, callId: string, body: string, step = 0): SessionEvent =>
+  toolResult: (seq: SessionSeq, turn: number, callId: string, body: string, step = 0): SessionEvent =>
     at(seq, {
       type: 'tool/result',
       surfaceOp: 'append',
@@ -58,20 +59,28 @@ export const ev = {
         }),
       },
     }),
-  codeDispatchStart: (seq: number, parentCallId: string, n: number, name: string, args: unknown): SessionEvent =>
+  codeDispatchStart: (seq: SessionSeq, parentCallId: string, n: number, name: string, args: unknown): SessionEvent =>
     at(seq, {
       type: 'tool/code-dispatch-start',
       data: { rootCallId: parentCallId, parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args },
     }),
-  codeDispatch: (seq: number, parentCallId: string, n: number, name: string, args: unknown, body: string, isError = false): SessionEvent =>
+  codeDispatch: (
+    seq: SessionSeq,
+    parentCallId: string,
+    n: number,
+    name: string,
+    args: unknown,
+    body: string,
+    isError = false,
+  ): SessionEvent =>
     at(seq, {
       type: 'tool/code-dispatch',
       data: { rootCallId: parentCallId, parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args, isError, content: text(body) },
     }),
-  stepEnd: (seq: number, turn: number, step = 0): SessionEvent =>
+  stepEnd: (seq: SessionSeq, turn: number, step = 0): SessionEvent =>
     at(seq, { type: 'step/end', data: { turn, step } }),
   retry: (
-    seq: number,
+    seq: SessionSeq,
     turn: number,
     step = 0,
     retry = 1,
@@ -88,23 +97,23 @@ export const ev = {
         failure: { code: 'TRANSPORT', message },
       },
     }),
-  turnEnd: (seq: number, turn: number, reason: 'completed' | 'aborted' | 'disposed' = 'completed'): SessionEvent =>
+  turnEnd: (seq: SessionSeq, turn: number, reason: 'completed' | 'aborted' | 'disposed' = 'completed'): SessionEvent =>
     at(seq, { type: 'turn/end', data: {
       turn,
       reason: reason === 'completed'
         ? { kind: 'completed' }
         : { kind: 'aborted', reason: { kind: reason === 'disposed' ? 'disposed' : 'user' } },
     } }),
-  commandRun: (seq: number, commandId: string, name: string, args = ''): SessionEvent =>
+  commandRun: (seq: SessionSeq, commandId: string, name: string, args = ''): SessionEvent =>
     at(seq, { type: 'command/run', data: { commandId, name, args, source: { kind: 'user' } } }),
-  commandRunWithoutInput: (seq: number, commandId: string, name: string): SessionEvent =>
+  commandRunWithoutInput: (seq: SessionSeq, commandId: string, name: string): SessionEvent =>
     at(seq, { type: 'command/run', data: { commandId, name, source: { kind: 'user' } } }),
   commandDone: (
-    seq: number,
+    seq: SessionSeq,
     commandId: string,
     kind: 'success' | 'error' = 'success',
     text?: string,
-    sourceEventSeq?: number,
+    sourceEventSeq?: SessionSeq,
   ): SessionEvent =>
     at(seq, { type: 'command/done', data: {
       commandId,
@@ -113,7 +122,7 @@ export const ev = {
       ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
     } }),
   /** A compaction's log-only `compaction/summary` record. */
-  compactSummary: (seq: number, summary: string, start: number, end: number): SessionEvent =>
+  compactSummary: (seq: SessionSeq, summary: string, start: SessionSeq, end: SessionSeq): SessionEvent =>
     at(seq, { type: 'compaction/summary', data: {
       summary: text(summary),
       shadowedRange: { start, end },
@@ -123,7 +132,12 @@ export const ev = {
       model: 'compact-1',
     } }),
   /** The replacement user message a compaction backend lands (the checkpoint). */
-  compactCheckpoint: (seq: number, summarySeq: number, start: number, end: number): SessionEvent =>
+  compactCheckpoint: (
+    seq: SessionSeq,
+    summarySeq: SessionSeq,
+    start: SessionSeq,
+    end: SessionSeq,
+  ): SessionEvent =>
     at(seq, {
       type: 'user/message',
       surfaceOp: { op: 'replace', start, end },
@@ -136,14 +150,14 @@ export const ev = {
 }
 
 /** One complete plain turn (turn/start → user → step → assistant → turn/end), 6 events from startSeq. */
-export function plainTurn(startSeq: number, turn: number, ask: string, answer: string): SessionEvent[] {
+export function plainTurn(startSeq: SessionSeq, turn: number, ask: string, answer: string): SessionEvent[] {
   return [
     ev.turnStart(startSeq, turn),
-    ev.user(startSeq + 1, ask),
-    ev.stepStart(startSeq + 2, turn),
-    ev.assistant(startSeq + 3, turn, answer),
-    ev.stepEnd(startSeq + 4, turn),
-    ev.turnEnd(startSeq + 5, turn),
+    ev.user(SessionSeq(startSeq + 1), ask),
+    ev.stepStart(SessionSeq(startSeq + 2), turn),
+    ev.assistant(SessionSeq(startSeq + 3), turn, answer),
+    ev.stepEnd(SessionSeq(startSeq + 4), turn),
+    ev.turnEnd(SessionSeq(startSeq + 5), turn),
   ]
 }
 
diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts
index 541c104a58..14f7c25fca 100644
--- a/packages/api/session-controller/tests/manager.client.spec.ts
+++ b/packages/api/session-controller/tests/manager.client.spec.ts
@@ -5,6 +5,7 @@
 
 import { describe, expect, it, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
 import type { SessionControlFrame } from '@deepseek-ai/dsh-api-session-controller/types'
 import type {} from '@deepseek-ai/dsh-session-title/client'
@@ -751,7 +752,7 @@ describe('connected generation', () => {
   it('refreshes query baselines without rebuilding independently resumed Session sources', async () => {
     const api = new FakeApiClient()
     api.onHistory = () => Promise.resolve(ok({
-      records: entries(plainTurn(0, 0, 'a', 'b')) as never[],
+      records: entries(plainTurn(SessionSeq(0), 0, 'a', 'b')) as never[],
       hasMore: false,
       modelSelection: { provider: 'deepseek-official', model: 'deepseek-chat' },
     }))
diff --git a/packages/api/session-controller/tests/projection-store.client.spec.ts b/packages/api/session-controller/tests/projection-store.client.spec.ts
index 64ee9d66f8..74f37c57cd 100644
--- a/packages/api/session-controller/tests/projection-store.client.spec.ts
+++ b/packages/api/session-controller/tests/projection-store.client.spec.ts
@@ -9,6 +9,7 @@
  */
 import { describe, expect, it } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import { ProjectionValueStore } from '../src/client/sessions/projection-store.ts'
 import { Session } from '../src/client/sessions/session.ts'
 import { SessionManager } from '../src/client/sessions/manager.ts'
@@ -34,35 +35,35 @@ describe('Session projection value semantics', () => {
 
   it('applies frames last-wins by seq: replayed and stale frames drop', () => {
     const store = new ProjectionValueStore()
-    store.apply('test/marks', { marks: ['a'] }, 5)
-    store.apply('test/marks', { marks: ['a', 'b'] }, 9)
+    store.apply('test/marks', { marks: ['a'] }, SessionSeq(5))
+    store.apply('test/marks', { marks: ['a', 'b'] }, SessionSeq(9))
     expect(store.get('test/marks')).toEqual({ marks: ['a', 'b'] })
-    store.apply('test/marks', { marks: ['stale'] }, 5)
-    store.apply('test/marks', { marks: ['equal'] }, 9)
+    store.apply('test/marks', { marks: ['stale'] }, SessionSeq(5))
+    store.apply('test/marks', { marks: ['equal'] }, SessionSeq(9))
     expect(store.get('test/marks')).toEqual({ marks: ['a', 'b'] })
   })
 
   it('a stale baseline can neither overwrite nor clear a newer frame; a fresh one reseeds and clears', () => {
     const store = new ProjectionValueStore()
-    store.apply('test/marks', { marks: ['frame-20'] }, 20)
+    store.apply('test/marks', { marks: ['frame-20'] }, SessionSeq(20))
     // Stale cut: carried key loses to the newer frame; omitted key survives.
-    store.seed({ asOfSeq: 10, values: { 'test/marks': { marks: ['baseline-10'] } } })
+    store.seed({ asOfSeq: SessionSeq(10), values: { 'test/marks': { marks: ['baseline-10'] } } })
     expect(store.get('test/marks')).toEqual({ marks: ['frame-20'] })
-    store.seed({ asOfSeq: 15, values: {} })
+    store.seed({ asOfSeq: SessionSeq(15), values: {} })
     expect(store.get('test/marks')).toEqual({ marks: ['frame-20'] })
     // Fresh cut: carried key reseeds…
-    store.seed({ asOfSeq: 30, values: { 'test/marks': { marks: ['baseline-30'] } } })
+    store.seed({ asOfSeq: SessionSeq(30), values: { 'test/marks': { marks: ['baseline-30'] } } })
     expect(store.get('test/marks')).toEqual({ marks: ['baseline-30'] })
     // …and an omitting fresh cut clears (capability absent as of the cut).
-    store.seed({ asOfSeq: 40, values: {} })
+    store.seed({ asOfSeq: SessionSeq(40), values: {} })
     expect(store.get('test/marks')).toBeUndefined()
   })
 
   it('truncate drops rows past the durable baseline and keeps the rest', () => {
     const store = new ProjectionValueStore()
-    store.apply('test/marks', { marks: ['durable'] }, 5)
-    store.apply('other', 'phantom', 50)
-    store.truncate(10)
+    store.apply('test/marks', { marks: ['durable'] }, SessionSeq(5))
+    store.apply('other', 'phantom', SessionSeq(50))
+    store.truncate(SessionSeq(10))
     expect(store.get('test/marks')).toEqual({ marks: ['durable'] })
     expect(store.get('other')).toBeUndefined()
   })
@@ -73,11 +74,11 @@ describe('Session projection value semantics', () => {
     let anyTicks = 0
     store.faceOf('test/marks').subscribe(() => { keyTicks += 1 })
     store.subscribeAny(() => { anyTicks += 1 })
-    store.apply('test/marks', { marks: ['a'] }, 5)
+    store.apply('test/marks', { marks: ['a'] }, SessionSeq(5))
     await Promise.resolve()
     expect(keyTicks).toBe(1)
     expect(anyTicks).toBe(1)
-    store.apply('test/marks', { marks: ['replay'] }, 3)
+    store.apply('test/marks', { marks: ['replay'] }, SessionSeq(3))
     await Promise.resolve()
     expect(keyTicks).toBe(1)
     expect(anyTicks).toBe(1)
@@ -92,7 +93,7 @@ describe('Session projection value semantics', () => {
     const store = new ProjectionValueStore()
     const empty = store.values()
     expect(store.values()).toBe(empty)
-    store.apply('test/marks', { marks: ['a'] }, 1)
+    store.apply('test/marks', { marks: ['a'] }, SessionSeq(1))
     const populated = store.values()
     expect(populated).toEqual({ 'test/marks': { marks: ['a'] } })
     expect(populated).not.toBe(empty)
@@ -105,7 +106,7 @@ describe('Session tail-page seeding', () => {
     const api = new FakeApiClient()
     const session = new Session(SID, fakeRemote(api))
     api.onHistory = () => Promise.resolve(ok({
-      records: entries(plainTurn(0, 0, '问', '答')) as never[], hasMore: false,
+      records: entries(plainTurn(SessionSeq(0), 0, '问', '答')) as never[], hasMore: false,
       projections: { asOfSeq: 5, values: { 'test/marks': { marks: ['from-baseline'] } } },
     } as never))
     await session.open()
@@ -116,11 +117,11 @@ describe('Session tail-page seeding', () => {
     const api = new FakeApiClient()
     const session = new Session(SID, fakeRemote(api))
     api.onHistory = () => Promise.resolve(ok({
-      records: entries(plainTurn(0, 0, 'a', 'b')) as never[], hasMore: false,
+      records: entries(plainTurn(SessionSeq(0), 0, 'a', 'b')) as never[], hasMore: false,
       projections: { asOfSeq: 5, values: { 'test/marks': { marks: ['baseline'] } } },
     } as never))
     await session.open()
-    session.projections.apply('test/marks', { marks: ['pushed-9'] }, 9)
+    session.projections.apply('test/marks', { marks: ['pushed-9'] }, SessionSeq(9))
     await session.resync()
     expect(session.projections.get('test/marks')).toEqual({ marks: ['pushed-9'] })
   })
@@ -128,9 +129,9 @@ describe('Session tail-page seeding', () => {
   it('treats a blockless response as no reset: pushed values survive', async () => {
     const api = new FakeApiClient()
     const session = new Session(SID, fakeRemote(api))
-    api.onHistory = () => Promise.resolve(ok({ records: entries(plainTurn(0, 0, 'a', 'b')) as never[], hasMore: false }))
+    api.onHistory = () => Promise.resolve(ok({ records: entries(plainTurn(SessionSeq(0), 0, 'a', 'b')) as never[], hasMore: false }))
     await session.open()
-    session.projections.apply('test/marks', { marks: ['pushed'] }, 9)
+    session.projections.apply('test/marks', { marks: ['pushed'] }, SessionSeq(9))
     await session.resync()
     expect(session.projections.get('test/marks')).toEqual({ marks: ['pushed'] })
   })
diff --git a/packages/api/session-controller/tests/queue-store.client.spec.ts b/packages/api/session-controller/tests/queue-store.client.spec.ts
index 856a861d5a..722a06b090 100644
--- a/packages/api/session-controller/tests/queue-store.client.spec.ts
+++ b/packages/api/session-controller/tests/queue-store.client.spec.ts
@@ -6,7 +6,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, UserMessage } from '@deepseek-ai/dsh-llm/types'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { MessageId, RpcId, SessionId } from '@deepseek-ai/dsh-api-remotes/client'
 import type { SessionControlFrame } from '@deepseek-ai/dsh-api-session-controller/types'
 import { Session } from '../src/client/sessions/session.ts'
@@ -160,12 +160,12 @@ describe('Session queue snapshot intake', () => {
       { id: 's-second', body: '', placement: 'steering', message },
     ]))
     const durable = {
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1_700_000_000_000,
       type: 'user/message',
       surfaceOp: 'append',
       data: message,
-    } as SessionEvent
+    } satisfies SessionEvent
 
     await api.pushFollow(SID, { type: 'event', event: durable as never })
     await vi.waitFor(() => {
diff --git a/packages/api/session-controller/tests/session-cold.host.spec.ts b/packages/api/session-controller/tests/session-cold.host.spec.ts
index 20c374e8c3..a6cc76c8b5 100644
--- a/packages/api/session-controller/tests/session-cold.host.spec.ts
+++ b/packages/api/session-controller/tests/session-cold.host.spec.ts
@@ -9,7 +9,7 @@ import { mkdtempSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import { SessionHistoryController } from '@deepseek-ai/dsh-api-session-controller/src/history.ts'
 import { subagentIdentityProjectionDefinition } from '@deepseek-ai/dsh-subagent/src/projection.ts'
@@ -49,7 +49,7 @@ function promptRequest(
 }
 
 function header(id: string, createdAt: number, extra: Partial<SessionHeader> = {}): SessionHeader {
-  return { version: 0, id: sid(id), createdAt, cwd: '/proj', ...extra }
+  return { version: 0, id: sid(id), createdAt, cwd: '/proj', isSeeded: false, ...extra }
 }
 
 function providePersistence(ctx: Context, persistence: Record<string, unknown>): () => void {
@@ -70,29 +70,30 @@ describe('sessions.list cold merge', () => {
       header('small-conversation', 200),
       header('large-unknown', 300),
       header('cached-nonblank', 400),
+      header('seeded-cold', 450, { isSeeded: true }),
       header('locationless', 500, { parentSession: sid('session-parent'), origin: 'subagent' }),
       header('vanished', 600),
       header('read-failure', 700),
-      { version: 0, id: sid('missing-cwd'), createdAt: 800 },
+      { version: 0, id: sid('missing-cwd'), createdAt: 800, isSeeded: false },
     ]
     const inspect = vi.fn(async (id: SessionId) => {
       if (id === sid('small-blank')) {
         return {
           meta: metas[0]!,
-          events: [{ type: 'session/end-seed', seq: 0, time: 700, data: {} }] as SessionEvent[],
+          events: [{ type: 'session/end-seed', seq: SessionSeq(0), time: 700, data: {} }] satisfies SessionEvent[],
         }
       }
       if (id === sid('small-conversation')) {
         return {
           meta: metas[1]!,
           events: [
-            { type: 'turn/start', seq: 0, time: 800, data: { turn: 1 } },
+            { type: 'turn/start', seq: SessionSeq(0), time: 800, data: { turn: 1 } },
             {
-              type: 'user/message', seq: 1, time: 1200,
+              type: 'user/message', seq: SessionSeq(1), time: 1200,
               data: createUserMessage({ content: [{ type: 'text', text: 'worked' }], source: { kind: 'user' } }),
               surfaceOp: 'append',
             },
-          ] as SessionEvent[],
+          ] satisfies SessionEvent[],
         }
       }
       if (id === sid('read-failure')) throw new Error('simulated read failure')
@@ -101,7 +102,9 @@ describe('sessions.list cold merge', () => {
     providePersistence(ctx, {
       list: () => Promise.resolve(metas),
       locate: (meta: SessionHeader) => {
-        if (meta.id === sid('large-unknown')) return { kind: 'jsonl', path: largePath }
+        if (meta.id === sid('large-unknown') || meta.id === sid('seeded-cold')) {
+          return { kind: 'jsonl', path: largePath }
+        }
         if (meta.id === sid('locationless')) return undefined
         if (meta.id === sid('vanished')) return { kind: 'jsonl', path: join(root, 'vanished.log') }
         return { kind: 'jsonl', path: smallPath }
@@ -110,19 +113,20 @@ describe('sessions.list cold merge', () => {
     })
     ctx.provide('sessionProjectionCache', {
       cachedSnapshot: (meta: SessionHeader) => {
+        if (meta.id === sid('seeded-cold')) throw new Error('seeded cold listing must not guess a body cut')
         if (meta.id === sid('small-blank')) {
-          return { asOfSeq: 0, values: { sessionListMetadata: { blank: true, lastPromptAt: null } } }
+          return { asOfSeq: SessionSeq(0), values: { sessionListMetadata: { blank: true, lastPromptAt: null } } }
         }
         if (meta.id === sid('small-conversation')) {
-          return { asOfSeq: 0, values: { sessionListMetadata: { blank: true, lastPromptAt: 900 } } }
+          return { asOfSeq: SessionSeq(0), values: { sessionListMetadata: { blank: true, lastPromptAt: 900 } } }
         }
         if (meta.id === sid('cached-nonblank')) {
-          return { asOfSeq: 1, values: { sessionListMetadata: { blank: false, lastPromptAt: 1000 } } }
+          return { asOfSeq: SessionSeq(1), values: { sessionListMetadata: { blank: false, lastPromptAt: 1000 } } }
         }
         return undefined
       },
-      hydratePrepared: (session: Session, _meta: SessionHeader, events: readonly SessionEvent[]) =>
-        ctx.sessionProjections.hydrate(session, {}, events, 0),
+      hydratePrepared: (session: Session, events: readonly SessionEvent[]) =>
+        ctx.sessionProjections.hydrate(session, {}, events, SessionLogOffset(0)),
     } as never)
     const remote = createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
@@ -134,6 +138,7 @@ describe('sessions.list cold merge', () => {
     expect(byId['small-conversation']).toMatchObject({ blank: false, updatedAt: 1200 })
     expect(byId['large-unknown']).toMatchObject({ blank: false, updatedAt: 300 })
     expect(byId['cached-nonblank']).toMatchObject({ blank: false, updatedAt: 1000 })
+    expect(byId['seeded-cold']).toMatchObject({ blank: false, updatedAt: 450 })
     expect(byId['locationless']).toMatchObject({
       blank: false,
       updatedAt: 500,
@@ -195,9 +200,9 @@ describe('sessions.list cold merge', () => {
     await started.promise
     const session = ctx.sessions.create(meta.id, {
       seed: [
-        { type: 'turn/start', seq: 0, time: 200, data: { turn: 1 } },
+        { type: 'turn/start', seq: SessionSeq(0), time: 200, data: { turn: 1 } },
         {
-          type: 'user/message', seq: 1, time: 300,
+          type: 'user/message', seq: SessionSeq(1), time: 300,
           data: createUserMessage({ content: [{ type: 'text', text: 'live' }], source: { kind: 'user' } }),
           surfaceOp: 'append',
         },
@@ -236,10 +241,14 @@ describe('sessions.list cold merge', () => {
       inspect: () => {
         const session = ctx.sessions.create(meta.id, {
           meta,
-          seed: [{ type: 'turn/start', seq: 0, time: 200, data: { turn: 1 } }],
+          seed: [{ type: 'turn/start', seq: SessionSeq(0), time: 200, data: { turn: 1 } }],
         })
         ctx.agents.register({ id: session.id, session, status: 'running', ctx } as Agent)
-        return Promise.resolve({ meta, events: [] })
+        return Promise.resolve({
+          meta,
+          inheritedEventCount: SessionLogOffset(0),
+          events: [],
+        })
       },
     })
     const remote = createSessionTestRemote(ctx, {
@@ -290,7 +299,11 @@ describe('sessions.list cold merge', () => {
       header: meta, live: false, persisted: true,
     }])
     vi.spyOn(ctx.sessionQuery, 'observeSession').mockResolvedValue({
-      source: 'prepared', header: meta, events: [], cursor: -1,
+      source: 'prepared',
+      header: meta,
+      inheritedEventCount: SessionLogOffset(0),
+      events: [],
+      cursor: -1,
       retain: vi.fn(), [Symbol.dispose]: vi.fn(),
     })
     const list = new ApiSessionList(ctx, 1024)
@@ -314,13 +327,13 @@ describe('attached updatedAt tracks human prompts', () => {
     const worked = 1_000_000
     const resumed = ctx.sessions.create(sid('resumed-untouched'), {
       seed: [
-        { type: 'turn/start', seq: 0, time: worked, data: { turn: 1 } },
+        { type: 'turn/start', seq: SessionSeq(0), time: worked, data: { turn: 1 } },
         {
-          type: 'user/message', seq: 1, time: worked,
+          type: 'user/message', seq: SessionSeq(1), time: worked,
           data: createUserMessage({ content: [{ type: 'text', text: 'worked' }], source: { kind: 'user' } }),
           surfaceOp: 'append',
         },
-        { type: 'turn/end', seq: 2, time: worked + 1, data: { turn: 1, reason: { kind: 'completed' } } },
+        { type: 'turn/end', seq: SessionSeq(2), time: worked + 1, data: { turn: 1, reason: { kind: 'completed' } } },
       ],
       meta: { cwd: '/proj', createdAt: 500 },
     })
@@ -360,7 +373,8 @@ describe('cold history recovery view', () => {
     const meta = header(sessionId, 1000)
     const stored: StoredPrefix<never> = {
       meta,
-      events: [{ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }],
+      inheritedEventCount: SessionLogOffset(0),
+      events: [{ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }],
       revision: SessionPersistenceRevision('history-recovery-test:1'),
     }
     const backend: PersistenceBackend<never> = {
@@ -425,7 +439,11 @@ describe('Remote Agent and Session lookup policy', () => {
     await ctx.plugin(AgentRegistry)
     const sessionId = sid('session-remote-cold')
     const meta = header(sessionId, 1000)
-    const inspect = vi.fn(() => Promise.resolve({ meta, events: [] as SessionEvent[] }))
+    const inspect = vi.fn(() => Promise.resolve({
+      meta,
+      inheritedEventCount: SessionLogOffset(0),
+      events: [] as SessionEvent[],
+    }))
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
       inspect,
@@ -469,7 +487,11 @@ describe('Remote Agent and Session lookup policy', () => {
       parentSession: sid('session-parent'),
       origin: 'subagent',
     })
-    const inspect = vi.fn(() => Promise.resolve({ meta: coldMeta, events: [] as SessionEvent[] }))
+    const inspect = vi.fn(() => Promise.resolve({
+      meta: coldMeta,
+      inheritedEventCount: SessionLogOffset(0),
+      events: [] as SessionEvent[],
+    }))
     providePersistence(ctx, {
       list: () => Promise.resolve([coldMeta]),
       inspect,
@@ -513,21 +535,29 @@ describe('subagent ownership fence', () => {
     const sessionId = sid('session-child')
     const meta = header('session-child', 1000, {
       parentSession: sid('session-parent'),
-      seedLength: 0,
+      isSeeded: true,
       origin: 'subagent',
     })
     const events = [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      {
+        type: 'turn/start',
+        seq: SessionSeq(0),
+        time: 1,
+        data: {
+          turn: 1,
+          trigger: { kind: 'message', source: { kind: 'user' } },
+        } as SessionEvent<'turn/start'>['data'],
+      },
       {
         type: 'user/message',
-        seq: 1,
+        seq: SessionSeq(1),
         time: 2,
         data: createUserMessage({ content: [{ type: 'text', text: 'work' }], source: { kind: 'user' } }),
         surfaceOp: 'append',
       },
       {
         type: 'subagent/descriptor',
-        seq: 2,
+        seq: SessionSeq(2),
         time: 3,
         data: snapshotSubagentDescriptor({
           mode: 'continuable',
@@ -535,9 +565,13 @@ describe('subagent ownership fence', () => {
           label: 'child',
         }),
       },
-      { type: 'turn/end', seq: 3, time: 4, data: { turn: 1, reason: { kind: 'completed' } } },
-    ] as SessionEvent[]
-    const inspect = vi.fn(() => Promise.resolve({ meta, events }))
+      { type: 'turn/end', seq: SessionSeq(3), time: 4, data: { turn: 1, reason: { kind: 'completed' } } },
+    ] satisfies SessionEvent[]
+    const inspect = vi.fn(() => Promise.resolve({
+      meta,
+      inheritedEventCount: SessionLogOffset(0),
+      events,
+    }))
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
       inspect,
@@ -591,19 +625,23 @@ describe('subagent ownership fence', () => {
     const sessionId = sid('session-legacy-child')
     const meta = header('session-legacy-child', 1000, {
       parentSession: sid('session-parent'),
-      seedLength: 0,
+      isSeeded: true,
     })
     const events = [
       {
         type: 'subagent/descriptor',
-        seq: 0,
+        seq: SessionSeq(0),
         time: 1,
         data: { version: 2, mode: 'continuable', provider: 'spawn', label: 'child' },
       },
-    ] as SessionEvent[]
+    ] satisfies SessionEvent[]
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
-      inspect: () => Promise.resolve({ meta, events }),
+      inspect: () => Promise.resolve({
+        meta,
+        inheritedEventCount: SessionLogOffset(0),
+        events,
+      }),
       locate: () => undefined,
     })
     // Stores whose headers predate `origin` classify a child only through the
@@ -690,11 +728,12 @@ describe('subagent ownership fence', () => {
     const session = ctx.sessions.create(sid('session-ordinary-fork'), {
       seed: [{
         type: 'subagent/descriptor',
-        seq: 0,
+        seq: SessionSeq(0),
         time: 1,
         data: { version: 2, mode: 'continuable', provider: 'spawn', label: 'ancestor' },
       }],
-      meta: { cwd: '/proj', parentSession: sid('session-source'), seedLength: 1 },
+      inheritedEventCount: SessionLogOffset(1),
+      meta: { cwd: '/proj', parentSession: sid('session-source'), isSeeded: true },
     })
     const followup = vi.fn()
     const agent = { id: session.id, session, status: 'idle', ctx, followup } as unknown as Agent
@@ -862,7 +901,11 @@ describe('sessions.prompt synchronous rejection', () => {
     const meta: SessionHeader = header('race-resume', 1000)
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
-      inspect: () => Promise.resolve({ meta, events: [] as SessionEvent[] }),
+      inspect: () => Promise.resolve({
+        meta,
+        inheritedEventCount: SessionLogOffset(0),
+        events: [] as SessionEvent[],
+      }),
       locate: () => undefined,
     })
     // The raced winner: a live parent-owned subagent publishes the identity
diff --git a/packages/api/session-controller/tests/session-fork.host.spec.ts b/packages/api/session-controller/tests/session-fork.host.spec.ts
index 958e53f5ba..7942bb92f6 100644
--- a/packages/api/session-controller/tests/session-fork.host.spec.ts
+++ b/packages/api/session-controller/tests/session-fork.host.spec.ts
@@ -6,7 +6,7 @@ import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
 import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import type { Workspace } from '@deepseek-ai/dsh-workspace'
@@ -32,6 +32,9 @@ async function composed(workspaces: readonly Workspace[] = []): Promise<Context>
       const session = ctx.sessions.create(options.sessionId, {
         ...options.seed === undefined ? {} : { seed: [...options.seed] },
         ...options.meta === undefined ? {} : { meta: options.meta },
+        ...options.inheritedEventCount === undefined
+          ? {}
+          : { inheritedEventCount: options.inheritedEventCount },
       })
       const agent = {} as Agent
       const agentCtx = ownerCtx.extend({ agent })
@@ -89,7 +92,7 @@ describe('sessions.fork', () => {
     const ctx = await composed()
     const source = liveAgent(ctx, 'session-source', 2)
     const response = await remote(ctx).fork(request({ sessionId: source.id, atSeq: 1 }))
-    expect(response.ok).toBe(true)
+    expect(response.ok ? null : response.error).toBeNull()
     if (!response.ok) return
     const child = ctx.sessions.get(response.value.sessionId)
     expect(child?.snapshotEvents().map(event => event.type)).toEqual([
@@ -153,22 +156,35 @@ describe('sessions.fork', () => {
       createdAt: 1,
       cwd: '/proj',
       parentSession: parentId,
+      isSeeded: false,
       origin: 'subagent',
     }
     const events = [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      {
+        type: 'turn/start',
+        seq: SessionSeq(0),
+        time: 1,
+        data: {
+          turn: 1,
+          trigger: { kind: 'message', source: { kind: 'user' } },
+        } as SessionEvent<'turn/start'>['data'],
+      },
       {
         type: 'user/message',
-        seq: 1,
+        seq: SessionSeq(1),
         time: 2,
         data: createUserMessage({ content: [{ type: 'text', text: 'work' }], source: { kind: 'user' } }),
         surfaceOp: 'append',
       },
-      { type: 'turn/end', seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' } } },
-    ] as SessionEvent[]
+      { type: 'turn/end', seq: SessionSeq(2), time: 3, data: { turn: 1, reason: { kind: 'completed' } } },
+    ] satisfies SessionEvent[]
     ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list: () => Promise.resolve([header]),
-      inspect: () => Promise.resolve({ meta: header, events }),
+      inspect: () => Promise.resolve({
+        meta: header,
+        inheritedEventCount: SessionLogOffset(0),
+        events,
+      }),
     }) as never)
     const resume = vi.spyOn(ctx.agents, 'resume')
 
diff --git a/packages/api/session-controller/tests/session-history-journal.host.spec.ts b/packages/api/session-controller/tests/session-history-journal.host.spec.ts
index 90b5851e08..4dcd66d8da 100644
--- a/packages/api/session-controller/tests/session-history-journal.host.spec.ts
+++ b/packages/api/session-controller/tests/session-history-journal.host.spec.ts
@@ -3,7 +3,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionSeq } from '@deepseek-ai/dsh-session'
 import { decodeStorageRecord, type ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
 import { ToolCallId, createMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
@@ -93,11 +93,11 @@ function pageEvents(page: SessionPage): SessionWireEvent[] {
 function chunkRow(event: ChunkRowEvent): ChunkRow {
   switch (event.type) {
     case 'chunkrow/text-chunks':
-      return { type: 'text-chunks', seq0: event.seq, time0: event.time, data: event.data }
+      return { type: 'text-chunks', seq0: SessionSeq(event.seq), time0: event.time, data: event.data }
     case 'chunkrow/reasoning-chunks':
-      return { type: 'reasoning-chunks', seq0: event.seq, time0: event.time, data: event.data }
+      return { type: 'reasoning-chunks', seq0: SessionSeq(event.seq), time0: event.time, data: event.data }
     case 'chunkrow/tool-call-chunks':
-      return { type: 'tool-call-chunks', seq0: event.seq, time0: event.time, data: event.data }
+      return { type: 'tool-call-chunks', seq0: SessionSeq(event.seq), time0: event.time, data: event.data }
   }
 }
 
@@ -210,6 +210,11 @@ describe('Session history raw journal', () => {
     const third = appendUserText(session, 'second prompt')
     appendAssistantText(session, 'second reply', 2)
     const shadowed = [...session.surface.nodes]
+    const shadowedStart = shadowed[0]
+    const shadowedEnd = shadowed.at(-1)
+    if (shadowedStart === undefined || shadowedEnd === undefined) {
+      throw new Error('expected a non-empty surface')
+    }
     // A compaction transaction: a log-only summary record immediately followed by the
     // replacement that shadows the range.
     const summary = appendExtension(session, 'compaction/summary', {
@@ -224,7 +229,7 @@ describe('Session history raw journal', () => {
       content: [{ type: 'text', text: '<context_checkpoint>summary</context_checkpoint>' }],
       source: { kind: 'plugin', plugin: 'compact' },
     }), {
-      surfaceOp: { op: 'replace', start: shadowed[0] as number, end: shadowed.at(-1) as number },
+      surfaceOp: { op: 'replace', start: shadowedStart, end: shadowedEnd },
       sourceEventSeqs: [...shadowed, summary.seq],
     })
 
diff --git a/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts b/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts
index e5aad4564b..c0bad5dabd 100644
--- a/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts
+++ b/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts
@@ -3,7 +3,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import { SessionSeq, type SessionEvent, type SessionId } from '@deepseek-ai/dsh-session/types'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
 import { Session } from '../src/client/sessions/session.ts'
 import type { PendingSubmissionRetirement } from '../src/client/contract/session.ts'
@@ -32,7 +32,7 @@ function imageRef(id: string): ImageAttachmentRef {
 }
 
 /** A durable browser-prompt user/message whose source echoes `rpcId`. */
-function promptEvent(seq: number, rpcId: SessionRequestId, refs: readonly ImageAttachmentRef[] = []): SessionEvent {
+function promptEvent(seq: SessionSeq, rpcId: SessionRequestId, refs: readonly ImageAttachmentRef[] = []): SessionEvent {
   return {
     seq,
     time: 1_700_000_000_000 + seq,
@@ -160,7 +160,7 @@ describe('observed retirement', () => {
       onRetire: retirement => retirements.push(retirement),
     })
     const refs = [imageRef('att-1')]
-    await api.pushFollow(SID, { type: 'event', event: promptEvent(0, handle.requestId, refs) as never })
+    await api.pushFollow(SID, { type: 'event', event: promptEvent(SessionSeq(0), handle.requestId, refs) as never })
     // Synchronously after the append the echo is still in the snapshot; the
     // render-time dedupe owns the overlap frame.
     expect(session.getSnapshot().pendingSubmissions).toHaveLength(1)
@@ -191,7 +191,7 @@ describe('observed retirement', () => {
   it('a full-window install (reconnect resync) retires echoes observed in the window', async () => {
     const { api, session } = makeSession()
     const handle = session.beginSubmission({ mode: 'queue', text: '重连', images: [] })
-    api.onHistory = () => Promise.resolve(ok(historyValue([promptEvent(12, handle.requestId)])))
+    api.onHistory = () => Promise.resolve(ok(historyValue([promptEvent(SessionSeq(12), handle.requestId)])))
     await session.open()
     await settleFrames()
     expect(session.getSnapshot().pendingSubmissions).toEqual([])
@@ -208,7 +208,7 @@ describe('observed retirement', () => {
       images: [],
       onRetire: retirement => retirements.push(retirement),
     })
-    await api.pushFollow(SID, { type: 'event', event: promptEvent(0, handle.requestId) as never })
+    await api.pushFollow(SID, { type: 'event', event: promptEvent(SessionSeq(0), handle.requestId) as never })
     handle.abandon()
     await settleFrames()
     expect(retirements).toEqual([{ reason: 'observed', attachments: [] }])
@@ -229,7 +229,7 @@ describe('observed retirement', () => {
       type: 'queue', sessionId: SID, items: [queuedItem(handle.requestId, [])],
     })
     await api.pushFollow(SID, {
-      type: 'event', event: promptEvent(0, handle.requestId) as never,
+      type: 'event', event: promptEvent(SessionSeq(0), handle.requestId) as never,
     })
     await settleFrames()
     expect(retirements).toEqual([{ reason: 'observed', attachments: [] }])
@@ -246,7 +246,7 @@ describe('observed retirement', () => {
     api.onHistory = () => Promise.resolve(ok(historyValue([])))
     await session.open()
     const handle = session.beginSubmission({ mode: 'queue', text: '帧', images: [] })
-    await api.pushFollow(SID, { type: 'event', event: promptEvent(0, handle.requestId) as never })
+    await api.pushFollow(SID, { type: 'event', event: promptEvent(SessionSeq(0), handle.requestId) as never })
     expect(session.getSnapshot().pendingSubmissions).toHaveLength(1)
     expect(frames).toHaveLength(1)
     frames[0]?.(0)
@@ -272,7 +272,7 @@ describe('disposal', () => {
       images: [],
       onRetire: retirement => retirements.push({ text: '未settle', retirement }),
     })
-    await api.pushFollow(SID, { type: 'event', event: promptEvent(0, observed.requestId) as never })
+    await api.pushFollow(SID, { type: 'event', event: promptEvent(SessionSeq(0), observed.requestId) as never })
     await session.dispose()
     await settleFrames()
     expect(retirements).toEqual([
diff --git a/packages/api/session-controller/tests/session-projections.host.spec.ts b/packages/api/session-controller/tests/session-projections.host.spec.ts
index c2ac3216a5..3f57e1afe2 100644
--- a/packages/api/session-controller/tests/session-projections.host.spec.ts
+++ b/packages/api/session-controller/tests/session-projections.host.spec.ts
@@ -18,7 +18,7 @@ import { AttachmentStore } from '@deepseek-ai/dsh-attachment'
 import { agentPresetProjectionDefinition } from '@deepseek-ai/dsh-agent-presets'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
@@ -132,6 +132,38 @@ function seedMessages(session: Session, count: number): void {
 const remote = (ctx: Context) => createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
 describe('session.history projections block', () => {
+  it('keeps the v0 numeric seed cut on the wire while logical headers expose only lineage', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(SessionProjectionRegistry)
+    const parent = ctx.sessions.create(SessionId('wire-seed-parent'), { meta: { cwd: '/workspace' } })
+    parent.append('turn/start', { turn: 1 })
+    parent.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    const inheritedEventCount = parent.seq
+    const child = ctx.sessions.create(SessionId('wire-seed-child'), {
+      seed: parent.snapshotEvents(),
+      inheritedEventCount,
+      meta: {
+        cwd: '/workspace',
+        parentSession: parent.id,
+        isSeeded: true,
+      },
+    })
+
+    const snapshot = await opening(remote(ctx), child.id)
+
+    expect(snapshot.header).toEqual({
+      version: 0,
+      id: child.id,
+      createdAt: child.header.createdAt,
+      cwd: '/workspace',
+      parentSession: parent.id,
+      seedLength: inheritedEventCount,
+    })
+    expect(snapshot.header).not.toHaveProperty('isSeeded')
+  })
+
   it('tracks pending and used model selections across repeated request headers', async () => {
     const { ctx, session } = await harness(true)
     remote(ctx)
@@ -318,7 +350,7 @@ describe('session.history projections block', () => {
     expect('test/last-user' in after.projections.values).toBe(false)
     expect(after.projections.values.sessionListMetadata).toEqual({
       blank: true,
-      lastPromptAt: session.eventAt(session.seq - 1)?.time,
+      lastPromptAt: session.eventAt(SessionSeq(session.seq - 1))?.time,
     })
   })
 
@@ -352,7 +384,7 @@ describe('session.list projections column', () => {
     expect(row?.projections?.values['test/last-user']).toEqual({ text: 'm0' })
     expect(row?.projections?.values.sessionListMetadata).toEqual({
       blank: false,
-      lastPromptAt: session.eventAt(session.seq - 1)?.time,
+      lastPromptAt: session.eventAt(SessionSeq(session.seq - 1))?.time,
     })
     expect(row?.projections?.asOfSeq).toBe(session.seq - 1)
   })
@@ -414,7 +446,7 @@ describe('session.list projections column', () => {
       cachedSnapshot: (meta: { id: unknown; createdAt: number }) =>
         (meta.id === coldId && meta.createdAt === 5
           ? {
-            asOfSeq: 7,
+            asOfSeq: SessionSeq(7),
             values: {
               'test/last-user': { text: 'cached' },
               sessionListMetadata: { blank: false, lastPromptAt: 6 },
diff --git a/packages/api/session-controller/tests/session-search.host.spec.ts b/packages/api/session-controller/tests/session-search.host.spec.ts
index 0c4591556c..89d1a2f424 100644
--- a/packages/api/session-controller/tests/session-search.host.spec.ts
+++ b/packages/api/session-controller/tests/session-search.host.spec.ts
@@ -8,7 +8,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import {
@@ -32,6 +32,7 @@ function header(id: string, cwd: string | null = '/project'): SessionHeader {
     version: 0,
     id: sid(id),
     createdAt: 100,
+    isSeeded: false,
     ...(cwd === null ? {} : { cwd }),
   }
 }
@@ -44,7 +45,7 @@ function hit(id: string, index = 0): SessionSearchHit {
     persisted: false,
     bestMatch: {
       sessionId: session.id,
-      seq: index,
+      seq: SessionSeq(index),
       type: 'user/message',
       time: 200 + index,
       surface: 'current',
diff --git a/packages/api/session-controller/tests/session-skills.host.spec.ts b/packages/api/session-controller/tests/session-skills.host.spec.ts
index 6fe4169b72..386d37e55c 100644
--- a/packages/api/session-controller/tests/session-skills.host.spec.ts
+++ b/packages/api/session-controller/tests/session-skills.host.spec.ts
@@ -1,7 +1,7 @@
 import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
 import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query'
 import type {} from '@deepseek-ai/dsh-skill'
 import { describe, expect, it, vi } from 'vitest'
@@ -18,9 +18,11 @@ function observation(
       version: 0,
       id: sessionId,
       createdAt: 1,
+      isSeeded: false,
       ...options.cwd === undefined ? {} : { cwd: options.cwd },
     },
     events,
+    inheritedEventCount: SessionLogOffset(0),
     cursor: -1,
     projections: {
       asOfSeq: -1,
diff --git a/packages/api/session-controller/tests/session.client.spec.ts b/packages/api/session-controller/tests/session.client.spec.ts
index 899a3f7745..f91e574c77 100644
--- a/packages/api/session-controller/tests/session.client.spec.ts
+++ b/packages/api/session-controller/tests/session.client.spec.ts
@@ -1,7 +1,7 @@
 /** Session object lifecycle, event-window transport, commands, and resync behavior. */
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client'
 import { RemoteStreamCarrierError } from '@deepseek-ai/dsh-api-gateway/client'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
@@ -56,7 +56,7 @@ describe('Session open', () => {
 
   it('installs the tail page: cold → loading → open with window and nodes in place', async () => {
     const { api, session } = makeSession()
-    const page = plainTurn(10, 3, '问', '答')
+    const page = plainTurn(SessionSeq(10), 3, '问', '答')
     api.onHistory = () => histResponse(page, true)
     expect(session.getSnapshot().openState).toBe('cold')
     const opening = session.open()
@@ -101,7 +101,7 @@ describe('Session open', () => {
 
   it('lands a packed live record in openState=error instead of crashing the stream loop', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     await session.open()
     expect(session.getSnapshot().openState).toBe('open')
 
@@ -136,10 +136,10 @@ describe('Session open', () => {
     api.onHistory = () => gate.promise
     const opening = session.open()
     // Three live frames land while the opening snapshot is pending; seq 15 overlaps its tail.
-    const page = plainTurn(10, 0, '早', '安')
+    const page = plainTurn(SessionSeq(10), 0, '早', '安')
     const deliveries = [
-      follow(api, ev.turnStart(15, 1)),
-      follow(api, ev.user(16, '插进来的')),
+      follow(api, ev.turnStart(SessionSeq(15), 1)),
+      follow(api, ev.user(SessionSeq(16), '插进来的')),
     ]
     gate.resolve(ok({
       records: entries(page) as never[],
@@ -155,7 +155,7 @@ describe('Session open', () => {
 
 
 describe('live event path', () => {
-  async function opened(events: SessionEvent[] = plainTurn(0, 0, 'a', 'b')) {
+  async function opened(events: SessionEvent[] = plainTurn(SessionSeq(0), 0, 'a', 'b')) {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(events)
     await session.open()
@@ -165,7 +165,7 @@ describe('live event path', () => {
   it('drops replayed frames at or below the window tail', async () => {
     const { api, session } = await opened()
     const before = session.eventSource.getSnapshot()
-    await follow(api, ev.user(3, '重放'))
+    await follow(api, ev.user(SessionSeq(3), '重放'))
     expect(session.eventSource.getSnapshot()).toBe(before)
   })
 
@@ -173,8 +173,8 @@ describe('live event path', () => {
     const { api, session } = await opened([])
     session.handleBlank(true)
     await Promise.all([
-      follow(api, ev.commandRun(0, 'cmd-perm', 'permission', ' danger-full-access')),
-      follow(api, ev.commandDone(1, 'cmd-perm', 'success', 'preset danger-full-access')),
+      follow(api, ev.commandRun(SessionSeq(0), 'cmd-perm', 'permission', ' danger-full-access')),
+      follow(api, ev.commandDone(SessionSeq(1), 'cmd-perm', 'success', 'preset danger-full-access')),
     ])
     const snapshot = session.getSnapshot()
     expect(eventSeqs(session)).toEqual([0, 1])
@@ -182,11 +182,11 @@ describe('live event path', () => {
   })
 
   it('repairs a seq gap by repulling the tail page instead of appending a hole', async () => {
-    const { api, session } = await opened(plainTurn(0, 0, 'a', 'b')) // tail seq = 5
-    const repaired = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]
+    const { api, session } = await opened(plainTurn(SessionSeq(0), 0, 'a', 'b')) // tail seq = 5
+    const repaired = [...plainTurn(SessionSeq(0), 0, 'a', 'b'), ...plainTurn(SessionSeq(6), 1, 'c', 'd')]
     api.onHistory = () => histResponse(repaired)
     // seq 9 with tail 5 → gap; the event detours to the buffer and one history refetch fires.
-    await follow(api, ev.assistant(9, 1, 'd'))
+    await follow(api, ev.assistant(SessionSeq(9), 1, 'd'))
     await vi.waitFor(() => {
       expect(api.callsOf('session.history')).toHaveLength(1)
     })
@@ -200,8 +200,8 @@ describe('live event path', () => {
 
 describe('paging', () => {
   it('prepends an older page and keeps seq continuity', async () => {
-    const older = plainTurn(0, 0, '旧问', '旧答')
-    const newer = plainTurn(6, 1, '新问', '新答')
+    const older = plainTurn(SessionSeq(0), 0, '旧问', '旧答')
+    const newer = plainTurn(SessionSeq(6), 1, '新问', '新答')
     const { api, session } = makeSession()
     api.onHistory = payload => payload.beforeSeq === undefined
       ? histResponse(newer, true)
@@ -220,9 +220,9 @@ describe('paging', () => {
   it('installs a page without interpreting business replacement metadata', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse([
-      ev.compactSummary(80, '窗外范围的摘要', 3, 40),
-      ev.compactCheckpoint(81, 80, 3, 40),
-      ev.user(82, '压缩后的新问题'),
+      ev.compactSummary(SessionSeq(80), '窗外范围的摘要', SessionSeq(3), SessionSeq(40)),
+      ev.compactCheckpoint(SessionSeq(81), SessionSeq(80), SessionSeq(3), SessionSeq(40)),
+      ev.user(SessionSeq(82), '压缩后的新问题'),
     ], true)
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
     try {
@@ -239,8 +239,8 @@ describe('paging', () => {
   it('drops a discontinuous older page fail-soft (window unchanged, hasMore cleared)', async () => {
     const { api, session } = makeSession()
     api.onHistory = payload => payload.beforeSeq === undefined
-      ? histResponse(plainTurn(10, 1, '新', '页'), true)
-      : histResponse(plainTurn(0, 0, '断', '层'), true) // tail seq 5, but baseSeq is 10 → hole
+      ? histResponse(plainTurn(SessionSeq(10), 1, '新', '页'), true)
+      : histResponse(plainTurn(SessionSeq(0), 0, '断', '层'), true) // tail seq 5, but baseSeq is 10 → hole
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
     try {
       await session.open()
@@ -255,9 +255,9 @@ describe('paging', () => {
   })
 
   it('loadThrough pages repeatedly until the window covers the target seq', async () => {
-    const oldest = plainTurn(0, 0, '最旧问', '最旧答')
-    const middle = plainTurn(6, 1, '中问', '中答')
-    const newest = plainTurn(12, 2, '新问', '新答')
+    const oldest = plainTurn(SessionSeq(0), 0, '最旧问', '最旧答')
+    const middle = plainTurn(SessionSeq(6), 1, '中问', '中答')
+    const newest = plainTurn(SessionSeq(12), 2, '新问', '新答')
     const { api, session } = makeSession()
     api.onHistory = (payload) => {
       if (payload.beforeSeq === undefined) return histResponse(newest, true)
@@ -271,7 +271,7 @@ describe('paging', () => {
       void payload
       return gate.promise
     }
-    const jump = session.loadThrough(0)
+    const jump = session.loadThrough(SessionSeq(0))
     expect(session.getSnapshot().loadingOlder).toBe(true)
     gate.resolve(ok(historyValue(middle, true)))
     await jump
@@ -286,21 +286,21 @@ describe('paging', () => {
 
   it('loadThrough is a no-op when the window already covers the target or the session is not open', async () => {
     const { api, session } = makeSession()
-    await session.loadThrough(0) // cold: no-op
+    await session.loadThrough(SessionSeq(0)) // cold: no-op
     expect(api.calls).toEqual([])
-    api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(6), 1, 'x', 'y'), true)
     await session.open()
     const calls = api.calls.length
-    await session.loadThrough(6) // baseSeq is already 6
-    await session.loadThrough(9) // inside the window
+    await session.loadThrough(SessionSeq(6)) // baseSeq is already 6
+    await session.loadThrough(SessionSeq(9)) // inside the window
     expect(api.calls.length).toBe(calls)
   })
 
   it('loadThrough retargets a running jump to the lowest requested seq and shares its completion', async () => {
-    const oldest = plainTurn(0, 0, 'a', 'b')
-    const middle = plainTurn(6, 1, 'c', 'd')
+    const oldest = plainTurn(SessionSeq(0), 0, 'a', 'b')
+    const middle = plainTurn(SessionSeq(6), 1, 'c', 'd')
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(12, 2, 'e', 'f'), true)
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(12), 2, 'e', 'f'), true)
     await session.open()
 
     const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
@@ -308,25 +308,28 @@ describe('paging', () => {
       api.onHistory = () => histResponse(oldest, false)
       return gate.promise
     }
-    const first = session.loadThrough(6)
-    const second = session.loadThrough(0)
+    const first = session.loadThrough(SessionSeq(6))
+    const second = session.loadThrough(SessionSeq(0))
     gate.resolve(ok(historyValue(middle, true)))
     await Promise.all([first, second])
-    expect(eventSeqs(session)).toEqual([...oldest, ...middle].map(event => event.seq).concat([12, 13, 14, 15, 16, 17]))
+    expect(eventSeqs(session)).toEqual([
+      ...[...oldest, ...middle].map(event => event.seq),
+      12, 13, 14, 15, 16, 17,
+    ])
     expect(api.callsOf('session.history')).toHaveLength(2)
   })
 
   it('loadThrough refused by a busy pager leaves no target behind for later jumps', async () => {
-    const middle = plainTurn(6, 1, 'c', 'd')
+    const middle = plainTurn(SessionSeq(6), 1, 'c', 'd')
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(12, 2, 'e', 'f'), true)
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(12), 2, 'e', 'f'), true)
     await session.open()
 
     // A plain single-page pull holds the busy flag while the jump is refused.
     const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
     api.onHistory = () => gate.promise
     const older = session.loadOlder()
-    await session.loadThrough(0) // refused: must not park seq 0 anywhere
+    await session.loadThrough(SessionSeq(0)) // refused: must not park seq 0 anywhere
     gate.resolve(ok(historyValue(middle, true)))
     await older
 
@@ -335,11 +338,11 @@ describe('paging', () => {
     api.onHistory = (payload) => {
       const start = ((payload as { beforeSeq?: number }).beforeSeq ?? 0) - 3
       return histResponse(
-        [ev.user(start, `u${String(start)}`), ev.user(start + 1, `u${String(start + 1)}`), ev.user(start + 2, `u${String(start + 2)}`)],
+        [ev.user(SessionSeq(start), `u${String(start)}`), ev.user(SessionSeq(start + 1), `u${String(start + 1)}`), ev.user(SessionSeq(start + 2), `u${String(start + 2)}`)],
         start > 0,
       )
     }
-    await session.loadThrough(4)
+    await session.loadThrough(SessionSeq(4))
     // Covered at seq 3 (≤ 4) after one page; a leaked 0 target would add a
     // third call at beforeSeq 3 and pull the head to 0.
     expect(api.callsOf('session.history').map(call => (call as { beforeSeq?: number }).beforeSeq))
@@ -349,16 +352,16 @@ describe('paging', () => {
 
   it('loadThrough stops paging when the event stream generation moves mid-loop', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(12, 2, 'x', 'y'), true)
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(12), 2, 'x', 'y'), true)
     await session.open()
 
     const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
     api.onHistory = () => gate.promise
-    const jump = session.loadThrough(0)
+    const jump = session.loadThrough(SessionSeq(0))
     // The address is rebuilt while the first page is in flight.
-    api.onHistory = () => histResponse(plainTurn(12, 2, 'x', 'y'), true)
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(12), 2, 'x', 'y'), true)
     const rebuilt = session.resync()
-    gate.resolve(ok(historyValue(plainTurn(6, 1, 'c', 'd'), true)))
+    gate.resolve(ok(historyValue(plainTurn(SessionSeq(6), 1, 'c', 'd'), true)))
     await jump
     await rebuilt
     // The stale loop must not page the new generation toward its old target:
@@ -370,22 +373,22 @@ describe('paging', () => {
   it('loadThrough stops on a page that makes no progress instead of looping', async () => {
     const { api, session } = makeSession()
     api.onHistory = payload => payload.beforeSeq === undefined
-      ? histResponse(plainTurn(12, 2, 'x', 'y'), true)
+      ? histResponse(plainTurn(SessionSeq(12), 2, 'x', 'y'), true)
       : histResponse([], true) // empty page still claiming more history
     await session.open()
-    await session.loadThrough(0)
+    await session.loadThrough(SessionSeq(0))
     expect(session.getSnapshot().loadingOlder).toBe(false)
     expect(api.callsOf('session.history')).toHaveLength(1)
   })
 
   it('loadThrough fails soft on a thrown page and clears its busy state', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(12, 2, 'x', 'y'), true)
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(12), 2, 'x', 'y'), true)
     await session.open()
     api.onHistory = () => Promise.reject(new Error('page wire down'))
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
     try {
-      await session.loadThrough(0)
+      await session.loadThrough(SessionSeq(0))
       expect(errorSpy).toHaveBeenCalled()
       expect(session.getSnapshot().loadingOlder).toBe(false)
     } finally {
@@ -395,14 +398,14 @@ describe('paging', () => {
 
   it('ignores loadOlder while one is in flight (single request)', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(6), 1, 'x', 'y'), true)
     await session.open()
     const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
     api.onHistory = () => gate.promise
     const first = session.loadOlder()
     const second = session.loadOlder()
     gate.resolve(ok({
-      records: entries(plainTurn(0, 0, 'a', 'b')) as never[],
+      records: entries(plainTurn(SessionSeq(0), 0, 'a', 'b')) as never[],
       hasMore: false,
       modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
@@ -618,7 +621,7 @@ describe('rename', () => {
     expect(session.projections.faceOf('title').getSnapshot()).toBe('正名')
     // A stale lower-seq apply (the push-frame path routes into this same
     // store) must not roll the settled value back.
-    session.projections.apply('title', '旧名', 3)
+    session.projections.apply('title', '旧名', SessionSeq(3))
     expect(session.projections.faceOf('title').getSnapshot()).toBe('正名')
   })
 
@@ -652,7 +655,7 @@ describe('remaining branches', () => {
     const { api, session } = makeSession()
     await session.loadOlder() // cold: no-op, zero calls
     expect(api.calls).toEqual([])
-    api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(6), 1, 'x', 'y'), true)
     await session.open()
     // err result: window unchanged
     api.onHistory = () => Promise.resolve(err(new RemoteError('gateway/internal', 'x', {})))
@@ -671,7 +674,7 @@ describe('remaining branches', () => {
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
     try {
       await session.resync()
-      api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+      api.onHistory = () => histResponse(plainTurn(SessionSeq(6), 1, 'x', 'y'), true)
       await session.resync()
       api.onHistory = () => Promise.reject(new Error('page wire down'))
       await session.loadOlder()
@@ -684,7 +687,7 @@ describe('remaining branches', () => {
 
   it('subscribe delivers snapshot-change notifications and unsubscribes', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     let notified = 0
     const unsubscribe = session.subscribe(() => { notified++ })
     await session.open()
@@ -702,7 +705,7 @@ describe('remaining branches', () => {
     let call = 0
     api.onHistory = () => {
       call++
-      return histResponse(plainTurn(0, 0, 'a', 'b'))
+      return histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     }
     api.followCursor = 11
     await session.open()
@@ -726,17 +729,17 @@ describe('remaining branches', () => {
 
   it('drops live events while cold/error (no window upkeep)', async () => {
     const { api, session } = makeSession()
-    await follow(api, ev.user(0, '冷态帧'))
+    await follow(api, ev.user(SessionSeq(0), '冷态帧'))
     expect(eventSeqs(session)).toEqual([])
     api.onHistory = () => Promise.resolve(err(new RemoteError('gateway/internal', 'x', {})))
     await session.open()
-    await follow(api, ev.user(0, '错态帧'))
+    await follow(api, ev.user(SessionSeq(0), '错态帧'))
     expect(eventSeqs(session)).toEqual([])
   })
 
   it('preserves a Host-reported failure that terminates the live source', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     await session.open()
     const failure = new RemoteError('session/not-found', 'session disappeared', { sessionId: SID })
 
@@ -750,7 +753,7 @@ describe('remaining branches', () => {
 
   it('coalesces queued gap frames behind one repair and exposes a failed repair', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     await session.open()
     const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
     let repairs = 0
@@ -759,8 +762,8 @@ describe('remaining branches', () => {
       return gate.promise
     }
     const deliveries = Promise.all([
-      follow(api, ev.user(9, '洞一')),
-      follow(api, ev.user(10, '洞二')),
+      follow(api, ev.user(SessionSeq(9), '洞一')),
+      follow(api, ev.user(SessionSeq(10), '洞二')),
     ])
     await vi.waitFor(() => { expect(repairs).toBe(1) })
     gate.reject(new RemoteError('gateway/internal', 'repair wire down', {}))
@@ -775,7 +778,7 @@ describe('remaining branches', () => {
     const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
     api.onHistory = () => stale.promise
     const opening = session.open()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     const resynced = session.resync()
     stale.reject(new Error('stale wire'))
     await Promise.all([opening, resynced])
@@ -787,39 +790,39 @@ describe('remaining branches', () => {
     const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
     api.onHistory = () => stale.promise
     const opening = session.open()
-    api.onHistory = () => histResponse(plainTurn(6, 1, '新', '代'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(6), 1, '新', '代'))
     const resynced = session.resync()
     stale.resolve(ok({
-      records: entries(plainTurn(0, 0, '旧', '代')) as never[],
+      records: entries(plainTurn(SessionSeq(0), 0, '旧', '代')) as never[],
       hasMore: false,
       modelSelection: { provider: 'deepseek-official', model: 'stale' },
     })) // success, but its generation is gone
     await Promise.all([opening, resynced])
-    expect(eventSeqs(session)).toEqual(plainTurn(6, 1, '新', '代').map(event => event.seq))
+    expect(eventSeqs(session)).toEqual(plainTurn(SessionSeq(6), 1, '新', '代').map(event => event.seq))
   })
 
   it('drops a gap repair superseded by a full resync while its pull was in flight', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     await session.open()
     const repairPull = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
     api.onHistory = () => repairPull.promise
-    const delivery = follow(api, ev.user(9, '洞'))
+    const delivery = follow(api, ev.user(SessionSeq(9), '洞'))
     await vi.waitFor(() => { expect(api.callsOf('session.history')).toHaveLength(1) })
-    api.onHistory = () => histResponse(plainTurn(6, 1, 'c', 'd'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(6), 1, 'c', 'd'))
     const resynced = session.resync() // bumps the generation
     repairPull.resolve(ok({
-      records: entries(plainTurn(0, 0, '旧', '页')) as never[],
+      records: entries(plainTurn(SessionSeq(0), 0, '旧', '页')) as never[],
       hasMore: false,
       modelSelection: { provider: 'deepseek-official', model: 'stale' },
     })) // repair result: stale, dropped
     await Promise.all([delivery, resynced])
-    expect(eventSeqs(session)).toEqual(plainTurn(6, 1, 'c', 'd').map(event => event.seq))
+    expect(eventSeqs(session)).toEqual(plainTurn(SessionSeq(6), 1, 'c', 'd').map(event => event.seq))
   })
 
   it('successful cancel leaves no promptError', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     await session.open()
     const result = await session.cancel()
     expect(result.ok).toBe(true)
@@ -833,11 +836,11 @@ describe('remaining branches', () => {
 
   it('carries raw history and follow events through the event feed', async () => {
     const { api, session } = makeSession()
-    const historyCall = ev.toolCall(6, 1, 'h1', 'bash', '{"cmd":"pwd"}')
-    const historyResult = ev.toolResult(7, 1, 'h1', 'done')
+    const historyCall = ev.toolCall(SessionSeq(6), 1, 'h1', 'bash', '{"cmd":"pwd"}')
+    const historyResult = ev.toolResult(SessionSeq(7), 1, 'h1', 'done')
     api.onHistory = () => Promise.resolve(ok({
       records: [
-        ...entries(plainTurn(0, 0, 'a', 'b')),
+        ...entries(plainTurn(SessionSeq(0), 0, 'a', 'b')),
         { type: 'event', event: historyCall },
         { type: 'event', event: historyResult },
       ] as never[],
@@ -849,10 +852,10 @@ describe('remaining branches', () => {
       { type: 'event', event: historyCall },
       { type: 'event', event: historyResult },
     ])
-    const liveCall = ev.toolCall(8, 2, 'l1', 'write', '{"file_path":"a.ts"}')
+    const liveCall = ev.toolCall(SessionSeq(8), 2, 'l1', 'write', '{"file_path":"a.ts"}')
     await follow(api, liveCall)
     expect(windowEntries(session).at(-1)).toEqual({ type: 'event', event: liveCall })
-    const liveResult = ev.toolResult(9, 2, 'l1', 'ok')
+    const liveResult = ev.toolResult(SessionSeq(9), 2, 'l1', 'ok')
     await follow(api, liveResult)
     expect(windowEntries(session).at(-1)).toEqual({ type: 'event', event: liveResult })
   })
@@ -861,7 +864,7 @@ describe('remaining branches', () => {
 describe('resync', () => {
   it('keeps the old feed until the reconnect snapshot, then repairs queued live gaps', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '旧', '窗'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, '旧', '窗'))
     await session.open()
     const oldWindow = session.eventSource.getSnapshot()
     const replacement = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
@@ -878,17 +881,17 @@ describe('resync', () => {
     expect(publications).toEqual([])
 
     api.onHistory = () => histResponse([
-      ...plainTurn(10, 2, '终', '页'),
-      ev.user(16, '后到低位'),
-      ev.user(17, '后到高位'),
+      ...plainTurn(SessionSeq(10), 2, '终', '页'),
+      ev.user(SessionSeq(16), '后到低位'),
+      ev.user(SessionSeq(17), '后到高位'),
     ])
     const liveDeliveries = Promise.all([
-      follow(api, ev.user(17, '后到高位')),
-      follow(api, ev.user(16, '后到低位')),
+      follow(api, ev.user(SessionSeq(17), '后到高位')),
+      follow(api, ev.user(SessionSeq(16), '后到低位')),
     ])
     expect(session.eventSource.getSnapshot()).toBe(oldWindow)
     replacement.resolve(ok({
-      records: entries(plainTurn(10, 2, '终', '页')) as never[],
+      records: entries(plainTurn(SessionSeq(10), 2, '终', '页')) as never[],
       hasMore: false,
       modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
@@ -906,11 +909,11 @@ describe('resync', () => {
 
   it('rebuilds the window without clearing control state; cold instances no-op', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, 'a', 'b'))
     await session.open()
     session.handleRunning(true)
     session.handleAgentError('still visible')
-    api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')])
+    api.onHistory = () => histResponse([...plainTurn(SessionSeq(0), 0, 'a', 'b'), ...plainTurn(SessionSeq(6), 1, 'c', 'd')])
     await session.resync()
     const snapshot = session.getSnapshot()
     expect(snapshot.openState).toBe('open')
@@ -928,14 +931,14 @@ describe('resync', () => {
     const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
     api.onHistory = () => stale.promise
     const firstOpen = session.open()
-    api.onHistory = () => histResponse(plainTurn(6, 1, '新', '代'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(6), 1, '新', '代'))
     const resynced = session.resync()
     stale.reject(new Error('dead connection')) // the doomed pre-disconnect request fails late
     await firstOpen
     await resynced
     const snapshot = session.getSnapshot()
     expect(snapshot.openState).toBe('open') // stale failure did not settle the fresh generation into error
-    expect(eventSeqs(session)).toEqual(plainTurn(6, 1, '新', '代').map(event => event.seq))
+    expect(eventSeqs(session)).toEqual(plainTurn(SessionSeq(6), 1, '新', '代').map(event => event.seq))
   })
 
 })
@@ -943,12 +946,12 @@ describe('resync', () => {
 describe('snapshot ownership', () => {
   it('publishes event-window appends without changing an unrelated Session snapshot', async () => {
     const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
+    api.onHistory = () => histResponse(plainTurn(SessionSeq(0), 0, '稳', '定'))
     await session.open()
     const sessionBefore = session.getSnapshot()
     const windowBefore = session.eventSource.getSnapshot()
     const firstEntry = windowBefore.entries[0]
-    await follow(api, ev.user(6, '追加'))
+    await follow(api, ev.user(SessionSeq(6), '追加'))
     const windowAfter = session.eventSource.getSnapshot()
     expect(session.getSnapshot()).toBe(sessionBefore)
     expect(windowAfter).not.toBe(windowBefore)
diff --git a/packages/api/session-controller/tests/test-remote.ts b/packages/api/session-controller/tests/test-remote.ts
index 3d7d549a26..2794e52ffe 100644
--- a/packages/api/session-controller/tests/test-remote.ts
+++ b/packages/api/session-controller/tests/test-remote.ts
@@ -2,6 +2,7 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import type { ModelSelection as AgentModelSelection } from '@deepseek-ai/dsh-agent'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import {
   SessionPersistenceCorruptionError,
@@ -111,15 +112,22 @@ export function testSessionPersistence(
       signal?.throwIfAborted()
       if (inspection === undefined) throw new SessionPersistenceNotFoundError(sessionId)
       try {
+        const inheritedEventCount = (inspection as Partial<SessionInspection>).inheritedEventCount
+        if (inspection.meta.isSeeded && inheritedEventCount === undefined) {
+          throw new Error('seeded test persistence must provide inheritedEventCount')
+        }
+        const cut = SessionLogOffset(inheritedEventCount ?? 0)
         const preparedSession = ctx.sessions.prepare(inspection.meta.id, {
           seed: [...inspection.events],
           meta: inspection.meta,
+          inheritedEventCount: cut,
           seedSource: 'persistence',
         })
         return {
           source: 'prepared',
           inspection: {
             meta: preparedSession.header,
+            inheritedEventCount: preparedSession.inheritedEventCount,
             events: Object.freeze([...inspection.events]),
           },
           revision: SessionPersistenceRevision(`test:${sessionId}:${String(preparedSession.seq)}`),
diff --git a/packages/api/session-controller/tests/transport.host.spec.ts b/packages/api/session-controller/tests/transport.host.spec.ts
index 91bdcb67ee..b6eeda6b41 100644
--- a/packages/api/session-controller/tests/transport.host.spec.ts
+++ b/packages/api/session-controller/tests/transport.host.spec.ts
@@ -1,7 +1,7 @@
 import { Context } from '@deepseek-ai/cordis'
 import { createScope } from '@deepseek-ai/dsh-scope'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionHeader, SurfaceIntent } from '@deepseek-ai/dsh-session'
 import type { SessionObservation } from '@deepseek-ai/dsh-session-query'
 import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent'
 import { subagentIdentityProjectionDefinition } from '@deepseek-ai/dsh-subagent/src/projection.ts'
@@ -15,7 +15,7 @@ function append(
   session: Session,
   type: string,
   data: unknown,
-  options?: { readonly surfaceOp?: unknown; readonly sourceEventSeqs?: readonly number[] },
+  options?: Partial<SurfaceIntent>,
 ): SessionEvent {
   return (session.append as unknown as (
     eventType: string,
@@ -24,7 +24,7 @@ function append(
   ) => SessionEvent)(type, data, options)
 }
 
-function event(type: string, seq: number, data: unknown = {}): SessionEvent {
+function event(type: string, seq: SessionSeq, data: unknown = {}): SessionEvent {
   return {
     type,
     seq,
@@ -38,6 +38,7 @@ function eventSession(header: SessionHeader, events: readonly SessionEvent[]): S
   return {
     id: header.id,
     header,
+    inheritedEventCount: SessionLogOffset(0),
     seq: events.length,
     eventAt: (seq: number) => events[seq],
     snapshotEvents: (fromSeq = 0, toSeqExclusive = events.length) => events.slice(fromSeq, toSeqExclusive),
@@ -49,9 +50,14 @@ function cold(
   header: SessionHeader,
   events: readonly SessionEvent[],
 ): void {
+  if (header.isSeeded) throw new Error('seeded cold fixtures require an explicit inherited cut')
   ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
     list: () => Promise.resolve([header]),
-    inspect: () => Promise.resolve({ meta: header, events }),
+    inspect: () => Promise.resolve({
+      meta: header,
+      inheritedEventCount: SessionLogOffset(0),
+      events,
+    }),
   }) as never)
 }
 
@@ -164,8 +170,18 @@ describe('SessionHistoryController', () => {
   it('subscribes before a cold read and ignores unrelated and replayed buffered events', async () => {
     const { ctx, transport } = await setup()
     const sessionId = SessionId('cold-race')
-    const header = { version: 0, id: sessionId, createdAt: 1, cwd: '/workspace' }
-    const inspected = deferred<{ meta: SessionHeader; events: readonly SessionEvent[] }>()
+    const header = {
+      version: 0,
+      id: sessionId,
+      createdAt: 1,
+      cwd: '/workspace',
+      isSeeded: false,
+    }
+    const inspected = deferred<{
+      meta: SessionHeader
+      inheritedEventCount: SessionLogOffset
+      events: readonly SessionEvent[]
+    }>()
     ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       inspect: () => inspected.promise,
     }) as never)
@@ -174,11 +190,15 @@ describe('SessionHistoryController', () => {
       [Symbol.asyncIterator]()
     const opening = iterator.next()
 
-    const unrelated = event('fixture/other', 0)
-    const start = event('fixture/start', 0)
+    const unrelated = event('fixture/other', SessionSeq(0))
+    const start = event('fixture/start', SessionSeq(0))
     ctx.emit('session/event', eventSession({ ...header, id: SessionId('unrelated') }, [unrelated]), unrelated)
     ctx.emit('session/event', eventSession(header, [start]), start)
-    inspected.resolve({ meta: header, events: [event('fixture/start', 0)] })
+    inspected.resolve({
+      meta: header,
+      inheritedEventCount: SessionLogOffset(0),
+      events: [event('fixture/start', SessionSeq(0))],
+    })
     await expect(opening).resolves.toMatchObject({ done: false, value: { type: 'snapshot', cursor: 0 } })
 
     const waiting = iterator.next()
@@ -190,7 +210,13 @@ describe('SessionHistoryController', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const sessionId = SessionId('created-during-observation')
-    const header = { version: 0, id: sessionId, createdAt: 1, cwd: '/workspace' }
+    const header = {
+      version: 0,
+      id: sessionId,
+      createdAt: 1,
+      cwd: '/workspace',
+      isSeeded: false,
+    }
     const observed = deferred<SessionObservation>()
     ctx.provide('sessionQuery', { observeSession: () => observed.promise } as never)
     const transport = new SessionHistoryController(ctx, vi.fn())
@@ -199,7 +225,7 @@ describe('SessionHistoryController', () => {
       [Symbol.asyncIterator]()
     const opening = iterator.next()
 
-    const attached = ctx.sessions.create(sessionId, { meta: header, seed: [event('fixture/seed', 0)] })
+    const attached = ctx.sessions.create(sessionId, { meta: header, seed: [event('fixture/seed', SessionSeq(0))] })
     observed.resolve({
       source: 'live',
       header: attached.header,
@@ -242,8 +268,14 @@ describe('SessionHistoryController', () => {
       { inject: ['sessions'] },
     ))
     const sessionId = SessionId('cold-attach')
-    const header = { version: 0, id: sessionId, createdAt: 1, cwd: '/workspace' }
-    const seed = [event('fixture/start', 0)]
+    const header = {
+      version: 0,
+      id: sessionId,
+      createdAt: 1,
+      cwd: '/workspace',
+      isSeeded: false,
+    }
+    const seed = [event('fixture/start', SessionSeq(0))]
     cold(ctx, header, seed)
     agentCtx.on('session/created', (session) => {
       if (session.id !== sessionId) return
@@ -284,8 +316,14 @@ describe('SessionHistoryController', () => {
   it('rejects gaps in replayed and live event sequences', async () => {
     const replay = await setup()
     const replayId = SessionId('replay-gap')
-    const replayHeader = { version: 0, id: replayId, createdAt: 1, cwd: '/workspace' }
-    cold(replay.ctx, replayHeader, [event('fixture/start', 0), event('fixture/gap', 2)])
+    const replayHeader = {
+      version: 0,
+      id: replayId,
+      createdAt: 1,
+      cwd: '/workspace',
+      isSeeded: false,
+    }
+    cold(replay.ctx, replayHeader, [event('fixture/start', SessionSeq(0)), event('fixture/gap', SessionSeq(2))])
     const replayed = replay.transport.follow({
       address: { kind: 'session', sessionId: replayId },
     }, signal())[Symbol.asyncIterator]()
@@ -299,9 +337,12 @@ describe('SessionHistoryController', () => {
       address: { kind: 'session', sessionId: session.id },
     }, signal())[Symbol.asyncIterator]()
     await expect(followed.next()).resolves.toMatchObject({ done: false, value: { type: 'snapshot', cursor: 0 } })
-    const skipped = event('fixture/skipped', 1)
-    const gap = event('fixture/gap', 2)
-    live.ctx.emit('session/event', eventSession(session.header, [event('fixture/start', 0), skipped, gap]), gap)
+    const skipped = event('fixture/skipped', SessionSeq(1))
+    const gap = event('fixture/gap', SessionSeq(2))
+    live.ctx.emit('session/event', eventSession(
+      session.header,
+      [event('fixture/start', SessionSeq(0)), skipped, gap],
+    ), gap)
     await expect(followed.next()).rejects.toMatchObject({ code: 'gateway/internal' })
   })
 
@@ -324,10 +365,20 @@ describe('SessionHistoryController', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const sessionId = SessionId('projectionless-follow')
-    const meta = { version: 0, id: sessionId, createdAt: 1, cwd: '/workspace' }
+    const meta = {
+      version: 0,
+      id: sessionId,
+      createdAt: 1,
+      cwd: '/workspace',
+      isSeeded: false,
+    }
     ctx.provide('sessionQuery', {
       observeSession: () => Promise.resolve({
-        source: 'live', header: meta, events: [], cursor: -1,
+        source: 'live',
+        header: meta,
+        inheritedEventCount: SessionLogOffset(0),
+        events: [],
+        cursor: -1,
         retain: vi.fn(), [Symbol.dispose]: vi.fn(),
       } satisfies SessionObservation),
     } as never)
@@ -438,8 +489,10 @@ describe('SessionHistoryController', () => {
     const address = { kind: 'session' as const, sessionId: session.id }
     for (const request of [
       { address, throughSeq: -2 },
+      { address, throughSeq: -0 },
       { address, throughSeq: 0.5 },
       { address, throughSeq: -1, beforeSeq: -1 },
+      { address, throughSeq: -1, beforeSeq: -0 },
       { address, throughSeq: -1, beforeSeq: 1.5 },
       { address, throughSeq: -1, maxMessages: 0 },
       { address, throughSeq: -1, maxMessages: 1.5 },
@@ -453,8 +506,8 @@ describe('SessionHistoryController', () => {
     const corruptId = SessionId('missing-through-seq')
     cold(
       corrupt.ctx,
-      { version: 0, id: corruptId, createdAt: 1, cwd: '/workspace' },
-      [event('fixture/start', 0), event('fixture/gap', 2)],
+      { version: 0, id: corruptId, createdAt: 1, cwd: '/workspace', isSeeded: false },
+      [event('fixture/start', SessionSeq(0)), event('fixture/gap', SessionSeq(2))],
     )
     await expect(corrupt.transport.page({
       address: { kind: 'session', sessionId: corruptId }, throughSeq: 1,
@@ -494,20 +547,28 @@ describe('SessionHistoryController', () => {
     const first = await setup()
     const sessionId = SessionId('incomplete')
     const address = { kind: 'session' as const, sessionId }
-    const firstHeader = { version: 0, id: sessionId, createdAt: 1 }
+    const firstHeader = { version: 0, id: sessionId, createdAt: 1, isSeeded: false }
     first.ctx.provide('sessionPersistence', testSessionPersistence(first.ctx, {
       list: () => Promise.resolve([firstHeader]),
-      inspect: () => Promise.resolve({ meta: firstHeader, events: [] }),
+      inspect: () => Promise.resolve({
+        meta: firstHeader,
+        inheritedEventCount: SessionLogOffset(0),
+        events: [],
+      }),
     }) as never)
     await expect(first.transport.page({ address, throughSeq: -1 }, signal()))
       .rejects.toMatchObject({ code: 'session/not-found' })
 
     const second = await setup()
-    const listed = { version: 0, id: sessionId, createdAt: 1, cwd: '/workspace' }
-    const inspected = { version: 0, id: sessionId, createdAt: 1 }
+    const listed = { version: 0, id: sessionId, createdAt: 1, cwd: '/workspace', isSeeded: false }
+    const inspected = { version: 0, id: sessionId, createdAt: 1, isSeeded: false }
     second.ctx.provide('sessionPersistence', testSessionPersistence(second.ctx, {
       list: () => Promise.resolve([listed]),
-      inspect: () => Promise.resolve({ meta: inspected, events: [] }),
+      inspect: () => Promise.resolve({
+        meta: inspected,
+        inheritedEventCount: SessionLogOffset(0),
+        events: [],
+      }),
     }) as never)
     await expect(second.transport.page({ address, throughSeq: -1 }, signal()))
       .rejects.toMatchObject({ code: 'session/not-found' })
@@ -516,8 +577,14 @@ describe('SessionHistoryController', () => {
   it('serves cold ordinary history and validates every durable subagent descriptor state', async () => {
     const ordinaryBench = await setup()
     const ordinaryId = SessionId('cold-ordinary')
-    const ordinaryHeader = { version: 0, id: ordinaryId, createdAt: 1, cwd: '/workspace' }
-    cold(ordinaryBench.ctx, ordinaryHeader, [event('turn/start', 0, { turn: 1 })])
+    const ordinaryHeader = {
+      version: 0,
+      id: ordinaryId,
+      createdAt: 1,
+      cwd: '/workspace',
+      isSeeded: false,
+    }
+    cold(ordinaryBench.ctx, ordinaryHeader, [event('turn/start', SessionSeq(0), { turn: 1 })])
     await expect(ordinaryBench.transport.page({
       address: { kind: 'session', sessionId: ordinaryId },
       throughSeq: 0,
@@ -532,6 +599,7 @@ describe('SessionHistoryController', () => {
       id: childSessionId,
       createdAt: 1,
       cwd: '/workspace',
+      isSeeded: false,
       origin: 'subagent' as const,
       parentSession: parentSessionId,
     }
@@ -547,7 +615,7 @@ describe('SessionHistoryController', () => {
       .rejects.toMatchObject({ code: 'subagent/catalog-diagnostic', details: { reason: 'corrupt' } })
 
     const corrupt = await setup()
-    cold(corrupt.ctx, childHeader, [event('subagent/descriptor', 0, { version: 'bad' })])
+    cold(corrupt.ctx, childHeader, [event('subagent/descriptor', SessionSeq(0), { version: 'bad' })])
     await expect(corrupt.transport.page({ address: childAddress, throughSeq: 0 }, signal()))
       .rejects.toMatchObject({ code: 'subagent/catalog-diagnostic', details: { reason: 'corrupt' } })
 
@@ -568,12 +636,17 @@ describe('SessionHistoryController', () => {
       id: childSessionId,
       createdAt: 1,
       cwd: '/workspace',
+      isSeeded: false,
       origin: 'subagent',
       parentSession: parentSessionId,
     }
     ctx.provide('sessionQuery', {
       observeSession: () => Promise.resolve({
-        source: 'live', header: meta, events: [], cursor: -1,
+        source: 'live',
+        header: meta,
+        inheritedEventCount: SessionLogOffset(0),
+        events: [],
+        cursor: -1,
         projections: { asOfSeq: -1, values: {} },
         retain: vi.fn(), [Symbol.dispose]: vi.fn(),
       } as unknown as SessionObservation),
@@ -629,8 +702,8 @@ describe('SessionHistoryController', () => {
     append(session, 'assistant/message', { turn: 1, step: 2, message: {} }, { surfaceOp: 'append' })
     const summary = append(session, 'fixture/summary', {})
     const replacement = append(session, 'user/message', { content: [], source: { kind: 'plugin' } }, {
-      surfaceOp: { op: 'replace', start: 1, end: 4 },
-      sourceEventSeqs: [1, firstReply.seq, 3, 4, summary.seq],
+      surfaceOp: { op: 'replace', start: SessionSeq(1), end: SessionSeq(4) },
+      sourceEventSeqs: [SessionSeq(1), firstReply.seq, SessionSeq(3), SessionSeq(4), summary.seq],
     })
 
     const page = await transport.page({
diff --git a/packages/bundle/headless/src/index.ts b/packages/bundle/headless/src/index.ts
index 5f2ad0e4b7..152576c67d 100644
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -17,7 +17,8 @@ import type { Agent, ModelSelectionRef } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-agent-default-model'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { assertNever } from '@deepseek-ai/dsh-util-values'
-import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
 // Empty type imports carry the loader Context merge for the settlement await
 // and the cmdline Context merge for the appExit host value.
 import type {} from '@deepseek-ai/cordis-plugin-loader'
@@ -60,13 +61,13 @@ export const internals: { stdout: HeadlessIo['stdout']; stderr: HeadlessIo['stde
 }
 
 /** Aggregate the last assistant text and turn outcome in one owned interval. */
-function summarize(session: Session, firstSeq: number): RunOutcome {
+function summarize(session: Session, firstSeq: SessionLogOffset): RunOutcome {
   let started = false
   let text = ''
   let reason: SessionEvent<'turn/end'>['data']['reason'] | undefined
   const length = session.seq
   for (let seq = firstSeq; seq < length; seq++) {
-    const event = session.eventAt(seq)
+    const event = session.eventAt(SessionSeq(seq))
     if (event === undefined) {
       throw new Error(`headless summary cannot read seq ${String(seq)} below captured length ${String(length)}`)
     }
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index c79b8caf20..dd5452015c 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -19,9 +19,9 @@ import type {
 import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type {
   SessionEvent,
-  SessionHeader,
   SessionId,
 } from '@deepseek-ai/dsh-session/types'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { isChunkRow, packChunkRuns } from '@deepseek-ai/dsh-session/chunk-rows'
 import type { ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
@@ -135,10 +135,22 @@ interface FixturePageRequest {
   readonly maxMessages?: number
 }
 
+interface FixtureSessionWireHeader {
+  readonly version: number
+  readonly id: SessionId
+  readonly createdAt: number
+  readonly cwd?: string
+  readonly parentSession?: SessionId
+  readonly seedLength?: number
+  readonly origin?: 'subagent'
+  readonly delegationDepth?: number
+  readonly agentPreset?: string
+}
+
 type FixtureFollowFrame =
   | {
     readonly type: 'snapshot'
-    readonly header: SessionHeader
+    readonly header: FixtureSessionWireHeader
     readonly cursor: number
     readonly records: readonly FixtureHistoryRecord[]
     readonly hasMore: boolean
@@ -2048,7 +2060,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
   }
   const append = (id: SessionId, e: Record<string, unknown>): void => {
     const log = logOf(id)
-    const event = { seq: log.length, time: Date.now(), ...e } as unknown as SessionEvent
+    const event = { seq: SessionSeq(log.length), time: Date.now(), ...e } as unknown as SessionEvent
     log.push(event)
     emitFollow(id, { type: 'event', event })
     // Host eager-drive parallel: a unit-advancing event pushes its finished value.
@@ -2672,7 +2684,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     /** Log append without follow delivery: a frame lost in transit that page repair must recover. */
     appendSilent(id: string, msg: string): void {
       const log = logOf(sid(id))
-      log.push({ type: 'user/message', surfaceOp: 'append', seq: log.length, time: Date.now(), data: userMessage(text(msg)) } as unknown as SessionEvent)
+      log.push({ type: 'user/message', surfaceOp: 'append', seq: SessionSeq(log.length), time: Date.now(), data: userMessage(text(msg)) } as unknown as SessionEvent)
     },
     /** End every open stream generator (client sees both streams close -> reconnect + resync path). */
     breakStreams(): void {
diff --git a/packages/client/connection/tests/fixture.client.spec.ts b/packages/client/connection/tests/fixture.client.spec.ts
index 7b5cbf0eca..ca80aaaa6c 100644
--- a/packages/client/connection/tests/fixture.client.spec.ts
+++ b/packages/client/connection/tests/fixture.client.spec.ts
@@ -9,6 +9,7 @@ import type {
 import { RpcId } from '../src/client/api.ts'
 import { decodeStorageRecord } from '@deepseek-ai/dsh-session/chunk-rows'
 import type { ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import {
   createFixtureConnectionRpc,
   createFixtureFaces,
@@ -72,11 +73,11 @@ function historyEvents(records: readonly FixtureHistoryRecord[]): SessionEvent[]
 function chunkRow(event: FixtureChunkRowEvent): ChunkRow {
   switch (event.type) {
     case 'chunkrow/text-chunks':
-      return { type: 'text-chunks', seq0: event.seq, time0: event.time, data: event.data }
+      return { type: 'text-chunks', seq0: SessionSeq(event.seq), time0: event.time, data: event.data }
     case 'chunkrow/reasoning-chunks':
-      return { type: 'reasoning-chunks', seq0: event.seq, time0: event.time, data: event.data }
+      return { type: 'reasoning-chunks', seq0: SessionSeq(event.seq), time0: event.time, data: event.data }
     case 'chunkrow/tool-call-chunks':
-      return { type: 'tool-call-chunks', seq0: event.seq, time0: event.time, data: event.data }
+      return { type: 'tool-call-chunks', seq0: SessionSeq(event.seq), time0: event.time, data: event.data }
   }
 }
 
diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index 42aada1017..75ff66b500 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -5,6 +5,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
 import type {
   ConversationTimelineSnapshot, RenderMessageImages,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import { Button, IconChevronDownOutline14, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
 import type { ChatSnapshot } from '../contract/snapshot.ts'
@@ -304,7 +305,7 @@ export function ChatView({
    * while the request is pending and restored after the prepend lands. */
   const anchorRef = useRef<PagingAnchor | null>(null)
   /** Unloaded-turn jump in flight: target turn plus its load-through seq. */
-  const pendingJumpRef = useRef<{ turn: number; seq: number } | null>(null)
+  const pendingJumpRef = useRef<{ turn: number; seq: SessionSeq } | null>(null)
   /** Whether the in-flight jump already landed mid-paging (settle then only corrects an untouched landing). */
   const jumpLandedRef = useRef(false)
   const [busyJumpTurn, setBusyJumpTurn] = useState<number | null>(null)
diff --git a/packages/client/ui-chat/src/client/chat/turn-rail-items.ts b/packages/client/ui-chat/src/client/chat/turn-rail-items.ts
index 98089e83c3..b1ab1e390a 100644
--- a/packages/client/ui-chat/src/client/chat/turn-rail-items.ts
+++ b/packages/client/ui-chat/src/client/chat/turn-rail-items.ts
@@ -7,6 +7,7 @@
  */
 
 import type {} from '@deepseek-ai/dsh-session-turn-outline/client'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { TurnNavigationItem } from '../contract/snapshot.ts'
 
 /** One rail mark: a loaded Turn scrolls to its row; an unloaded one pages history through its seq first. */
@@ -19,7 +20,7 @@ export interface TurnRailItem {
   /** How the rail reaches the Turn. */
   readonly anchor:
     | { readonly kind: 'loaded'; readonly key: string }
-    | { readonly kind: 'unloaded'; readonly seq: number }
+    | { readonly kind: 'unloaded'; readonly seq: SessionSeq }
 }
 
 const EMPTY_ITEMS: readonly TurnRailItem[] = []
@@ -31,14 +32,14 @@ const EMPTY_ITEMS: readonly TurnRailItem[] = []
  * decorative, so a malformed one degrades to `''` and the turn stays
  * navigable by number.
  */
-function outlineEntry(value: unknown): { turn: number; seq: number; prompt: string; response: string } | undefined {
+function outlineEntry(value: unknown): { turn: number; seq: SessionSeq; prompt: string; response: string } | undefined {
   if (typeof value !== 'object' || value === null) return undefined
   const entry = value as { turn?: unknown; seq?: unknown; prompt?: unknown; response?: unknown }
   if (typeof entry.turn !== 'number' || !Number.isSafeInteger(entry.turn) || entry.turn < 0) return undefined
-  if (typeof entry.seq !== 'number' || !Number.isSafeInteger(entry.seq) || entry.seq < 0) return undefined
+  if (typeof entry.seq !== 'number' || !Number.isSafeInteger(entry.seq) || entry.seq < 0 || Object.is(entry.seq, -0)) return undefined
   return {
     turn: entry.turn,
-    seq: entry.seq,
+    seq: SessionSeq(entry.seq),
     prompt: typeof entry.prompt === 'string' ? entry.prompt : '',
     response: typeof entry.response === 'string' ? entry.response : '',
   }
diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts
index 14fe308321..2ff7122ea2 100644
--- a/packages/client/ui-chat/src/client/contract/slots.ts
+++ b/packages/client/ui-chat/src/client/contract/slots.ts
@@ -1,5 +1,6 @@
 /** Chat-owned Slot declarations and composed component props. */
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type {
   ConversationTurnDataMap, MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, TurnLocation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -119,7 +120,7 @@ export interface ChatViewInjected {
   openFile: (path: string) => Promise<void>
   loadOlder: () => void
   /** Jump loader: page history back through seq; resolves when the window covers it. */
-  loadThrough: (seq: number) => Promise<void>
+  loadThrough: (seq: SessionSeq) => Promise<void>
   loadImage: MessageImageLoader
   chatScroll: {
     save: (position: ChatScrollPosition | null) => void
diff --git a/packages/client/ui-chat/tests/apply-inject.client.spec.tsx b/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
index 98b477c57f..fa7cb20093 100644
--- a/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
+++ b/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
@@ -15,7 +15,7 @@ import {
 import {
   apply as applyChat, inject as injectChat, type ChatViewInjected, type DetailsInjected,
 } from '@deepseek-ai/dsh-client-ui-chat/client'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
 import { createChatStore } from '../src/client/stores.ts'
 
 usePinnedBrowserLanguages('zh-CN')
@@ -93,7 +93,7 @@ describe('Chat inject API', () => {
     injected.loadOlder()
     expect(b.session.loadOlder).toHaveBeenCalledOnce()
 
-    void injected.loadThrough(42)
+    void injected.loadThrough(SessionSeq(42))
     expect(b.session.loadThrough).toHaveBeenCalledWith(42)
 
     injected.forkAt(17)
diff --git a/packages/client/ui-chat/tests/turn-rail-items.client.spec.ts b/packages/client/ui-chat/tests/turn-rail-items.client.spec.ts
index 8f9dee2b68..289ff3c0fd 100644
--- a/packages/client/ui-chat/tests/turn-rail-items.client.spec.ts
+++ b/packages/client/ui-chat/tests/turn-rail-items.client.spec.ts
@@ -62,6 +62,8 @@ describe('mergeTurnRailItems', () => {
     const items = mergeTurnRailItems([], [
       { turn: -1, seq: 0, prompt: 'negative turn', response: '' },
       { turn: 2, seq: 0.5, prompt: 'fractional seq', response: '' },
+      { turn: 4, seq: -0, prompt: 'negative zero seq', response: '' },
+      { turn: 5, seq: Number.MAX_SAFE_INTEGER + 1, prompt: 'unsafe seq', response: '' },
       { turn: 3, seq: 4, prompt: 5, response: 6 },
       { turn: 6, seq: 7, prompt: 'kept', response: 8 },
       null,
diff --git a/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts b/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
index 2c5fa7c17c..0e95e83465 100644
--- a/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
@@ -4,6 +4,7 @@ import type {
 } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { ChunkRowEvent } from '@deepseek-ai/dsh-api-session-controller/types'
 import type { ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { ConversationNodeAssembler as RuntimeConversationNodeAssembler } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
@@ -114,7 +115,7 @@ function trackedView(target: string) {
   return { definition, create, replace, apply }
 }
 
-function at(seq: number, type: string, data: unknown): SessionEvent {
+function at(seq: SessionSeq, type: string, data: unknown): SessionEvent {
   return { seq, time: 1_700_000_000_000 + seq, type, data } as SessionEvent
 }
 
@@ -210,7 +211,7 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([chat.definition, trajectory.definition]),
     )
 
-    assembler.replaceWindow([input(at(1, 'active/start', {}))], false)
+    assembler.replaceWindow([input(at(SessionSeq(1), 'active/start', {}))], false)
     expect(assembler.flush()).toBe(false)
     expect(chat.create).not.toHaveBeenCalled()
     expect(trajectory.create).not.toHaveBeenCalled()
@@ -223,7 +224,7 @@ describe('ConversationNodeAssembler', () => {
     expect(buildChat).toHaveBeenCalledOnce()
     expect(buildTrajectory).not.toHaveBeenCalled()
 
-    assembler.append(input(at(2, 'active/update', {})))
+    assembler.append(input(at(SessionSeq(2), 'active/update', {})))
     expect(assembler.flush()).toBe(true)
     expect(chat.apply).toHaveBeenCalledOnce()
     expect(trajectory.apply).not.toHaveBeenCalled()
@@ -234,7 +235,7 @@ describe('ConversationNodeAssembler', () => {
     expect((assembler.snapshot('trajectory') as readonly ConversationViewNode[])
       .map(node => node.data)).toEqual([{ updates: 1 }])
 
-    assembler.append(input(at(3, 'active/update', {})))
+    assembler.append(input(at(SessionSeq(3), 'active/update', {})))
     expect(assembler.flush()).toBe(true)
     expect(chat.apply).toHaveBeenCalledTimes(2)
     expect(trajectory.apply).toHaveBeenCalledOnce()
@@ -270,13 +271,13 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(1, 'tool/call', { turn: 1, step: 1, callId: 'a', name: 'x', arguments: '{}' })),
-      input(at(2, 'tool/call', { turn: 1, step: 1, callId: 'b', name: 'x', arguments: '{}' })),
+      input(at(SessionSeq(1), 'tool/call', { turn: 1, step: 1, callId: 'a', name: 'x', arguments: '{}' })),
+      input(at(SessionSeq(2), 'tool/call', { turn: 1, step: 1, callId: 'b', name: 'x', arguments: '{}' })),
     ], false)
     assembler.flush()
     starts.mockClear()
 
-    assembler.append(input(at(3, 'tool/result', {
+    assembler.append(input(at(SessionSeq(3), 'tool/result', {
       turn: 1,
       step: 1,
       message: { source: { type: 'tool-result', callId: 'a' }, content: [], isError: false },
@@ -321,11 +322,11 @@ describe('ConversationNodeAssembler', () => {
       new TestEventDefinitions([definition]),
       new TestViewDefinitions([testView()]),
     )
-    assembler.replaceWindow([input(at(1, 'linear/start', {}))], false)
+    assembler.replaceWindow([input(at(SessionSeq(1), 'linear/start', {}))], false)
     starts.mockClear()
 
     for (let seq = 2; seq <= 1_001; seq++) {
-      assembler.append(input(at(seq, 'linear/update', {})))
+      assembler.append(input(at(SessionSeq(seq), 'linear/update', {})))
     }
     assembler.flush()
 
@@ -395,15 +396,15 @@ describe('ConversationNodeAssembler', () => {
     }
     const run = chunkInput({
       type: 'text-chunks',
-      seq0: 12,
+      seq0: SessionSeq(12),
       time0: 1_700_000_000_012,
       data: { turn: 2, step: 3, index: 0, dt: [1, 1], texts: ['a', 'b', 'c'] },
     })
     const inputs: SessionEventLikeEntry[] = [
-      input(at(10, 'step/start', { turn: 2, step: 3 })),
-      input(at(11, 'probe/update', { turn: 2, step: 3 })),
+      input(at(SessionSeq(10), 'step/start', { turn: 2, step: 3 })),
+      input(at(SessionSeq(11), 'probe/update', { turn: 2, step: 3 })),
       run,
-      input(at(15, 'probe/update', { turn: 2, step: 3 })),
+      input(at(SessionSeq(15), 'probe/update', { turn: 2, step: 3 })),
     ]
     const assembler = new ConversationNodeAssembler(
       new TestEventDefinitions([definition, passive]),
@@ -430,7 +431,7 @@ describe('ConversationNodeAssembler', () => {
       ],
     })
 
-    assembler.append(input(at(16, 'step/end', { turn: 2, step: 3 })))
+    assembler.append(input(at(SessionSeq(16), 'step/end', { turn: 2, step: 3 })))
     assembler.flush()
 
     expect(updates.mock.calls.filter(([, match]) => (
@@ -493,7 +494,7 @@ describe('ConversationNodeAssembler', () => {
     )
     const run = chunkInput({
       type: 'reasoning-chunks',
-      seq0: 21,
+      seq0: SessionSeq(21),
       time0: 1_700_000_000_021,
       data: { turn: 4, step: 5, index: 0, dt: [0, -1], texts: ['', ' ', 'x'] },
     })
@@ -506,7 +507,7 @@ describe('ConversationNodeAssembler', () => {
     expect(testSnapshot(assembler)?.order).toEqual([])
 
     assembler.prepend([
-      input(at(20, 'step/start', { turn: 4, step: 5 })),
+      input(at(SessionSeq(20), 'step/start', { turn: 4, step: 5 })),
     ], false)
     assembler.flush()
 
@@ -534,7 +535,7 @@ describe('ConversationNodeAssembler', () => {
     )
     const run = chunkInput({
       type: 'text-chunks',
-      seq0: 1,
+      seq0: SessionSeq(1),
       time0: 1_700_000_000_001,
       data: { turn: 1, step: 1, index: 0, dt: [1, 1], texts: ['a', 'b', 'c'] },
     })
@@ -567,7 +568,7 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     const current = Array.from({ length: 100 }, (_, index) => (
-      input(at(index + 102, 'linear/update', {}))
+      input(at(SessionSeq(index + 102), 'linear/update', {}))
     ))
     assembler.replaceWindow(current, true)
     assembler.flush()
@@ -575,9 +576,9 @@ describe('ConversationNodeAssembler', () => {
     expect(updates).not.toHaveBeenCalled()
 
     const older = [
-      input(at(1, 'linear/start', {})),
+      input(at(SessionSeq(1), 'linear/start', {})),
       ...Array.from({ length: 100 }, (_, index) => (
-        input(at(index + 2, 'linear/update', {}))
+        input(at(SessionSeq(index + 2), 'linear/update', {}))
       )),
     ]
     assembler.prepend(older, false)
@@ -606,7 +607,7 @@ describe('ConversationNodeAssembler', () => {
       new TestEventDefinitions([definition]),
       new TestViewDefinitions([testView()]),
     )
-    assembler.replaceWindow([input(at(10, 'tool/result', {
+    assembler.replaceWindow([input(at(SessionSeq(10), 'tool/result', {
       turn: 1,
       step: 1,
       message: { source: { type: 'tool-result', callId: 'a' }, content: [], isError: false },
@@ -615,7 +616,7 @@ describe('ConversationNodeAssembler', () => {
     expect([...testSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
       .toEqual({ pendingStart: true })
 
-    assembler.prepend([input(at(5, 'tool/call', {
+    assembler.prepend([input(at(SessionSeq(5), 'tool/call', {
       turn: 1, step: 1, callId: 'a', name: 'x', arguments: '{}',
     }))], false)
     assembler.flush()
@@ -642,8 +643,8 @@ describe('ConversationNodeAssembler', () => {
     )
 
     expect(() => assembler.replaceWindow([
-      input(at(1, 'turn/start', { turn: 1 })),
-      input(at(2, 'turn/end', { turn: 1, reason: { kind: 'completed' } })),
+      input(at(SessionSeq(1), 'turn/start', { turn: 1 })),
+      input(at(SessionSeq(2), 'turn/end', { turn: 1, reason: { kind: 'completed' } })),
     ], false)).toThrow('received an update before its start Match')
   })
 
@@ -677,13 +678,13 @@ describe('ConversationNodeAssembler', () => {
       new TestEventDefinitions([source, consumer]),
       new TestViewDefinitions([testView()]),
     )
-    assembler.replaceWindow([input(at(10, 'assistant/message', {
+    assembler.replaceWindow([input(at(SessionSeq(10), 'assistant/message', {
       turn: 2, step: 1, message: { role: 'assistant', content: [] },
     }))], true)
     assembler.flush()
     expect([...testSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(-1)
 
-    assembler.prepend([input(at(5, 'user/message', {
+    assembler.prepend([input(at(SessionSeq(5), 'user/message', {
       id: 'm1', value: 7, content: [], source: { kind: 'user' },
     }))], false)
     assembler.flush()
@@ -718,22 +719,22 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(40, 'user/message', { id: 'm40', content: [], source: { kind: 'user' } })),
-      input(at(50, 'assistant/message', {
+      input(at(SessionSeq(40), 'user/message', { id: 'm40', content: [], source: { kind: 'user' } })),
+      input(at(SessionSeq(50), 'assistant/message', {
         turn: 1, step: 1, message: { role: 'assistant', content: [] },
       })),
     ], true)
     assembler.flush()
 
     assembler.prepend([
-      input(at(10, 'user/message', { id: 'm10', content: [], source: { kind: 'user' } })),
-      input(at(30, 'user/message', { id: 'm30', content: [], source: { kind: 'user' } })),
+      input(at(SessionSeq(10), 'user/message', { id: 'm10', content: [], source: { kind: 'user' } })),
+      input(at(SessionSeq(30), 'user/message', { id: 'm30', content: [], source: { kind: 'user' } })),
     ], false)
     assembler.flush()
-    assembler.append(input(at(60, 'user/message', {
+    assembler.append(input(at(SessionSeq(60), 'user/message', {
       id: 'm60', content: [], source: { kind: 'user' },
     })))
-    assembler.append(input(at(70, 'assistant/message', {
+    assembler.append(input(at(SessionSeq(70), 'assistant/message', {
       turn: 2, step: 1, message: { role: 'assistant', content: [] },
     })))
     assembler.flush()
@@ -762,7 +763,7 @@ describe('ConversationNodeAssembler', () => {
       new TestEventDefinitions([consumer]),
       new TestViewDefinitions([testView()]),
     )
-    assembler.replaceWindow([input(at(10, 'assistant/message', {
+    assembler.replaceWindow([input(at(SessionSeq(10), 'assistant/message', {
       turn: 2, step: 1, message: { role: 'assistant', content: [] },
     }))], true)
     assembler.flush()
@@ -807,12 +808,12 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(1, 'user/message', { id: 'source', content: [], source: { kind: 'user' } })),
-      input(at(2, 'assistant/message', { turn: 1, step: 1, message: { role: 'assistant', content: [] } })),
+      input(at(SessionSeq(1), 'user/message', { id: 'source', content: [], source: { kind: 'user' } })),
+      input(at(SessionSeq(2), 'assistant/message', { turn: 1, step: 1, message: { role: 'assistant', content: [] } })),
     ], false)
     assembler.flush()
 
-    expect(assembler.append(input(at(3, 'source/update', { value: 2 })))).toBe('immediate')
+    expect(assembler.append(input(at(SessionSeq(3), 'source/update', { value: 2 })))).toBe('immediate')
     assembler.flush()
 
     expect(consumerStart).toHaveBeenCalledTimes(2)
@@ -875,14 +876,14 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(1, 'user/message', { id: 'source', content: [], source: { kind: 'user' } })),
-      input(at(2, 'turn/start', { turn: 1 })),
-      input(at(3, 'assistant/message', { turn: 1, step: 1, message: { role: 'assistant', content: [] } })),
-      input(at(4, 'tool/call', { turn: 1, step: 1, callId: 'call', name: 'x', arguments: '{}' })),
+      input(at(SessionSeq(1), 'user/message', { id: 'source', content: [], source: { kind: 'user' } })),
+      input(at(SessionSeq(2), 'turn/start', { turn: 1 })),
+      input(at(SessionSeq(3), 'assistant/message', { turn: 1, step: 1, message: { role: 'assistant', content: [] } })),
+      input(at(SessionSeq(4), 'tool/call', { turn: 1, step: 1, callId: 'call', name: 'x', arguments: '{}' })),
     ], false)
 
-    assembler.append(input(at(5, 'diamond/x', { value: 20 })))
-    assembler.append(input(at(6, 'diamond/a', { value: 2 })))
+    assembler.append(input(at(SessionSeq(5), 'diamond/x', { value: 20 })))
+    assembler.append(input(at(SessionSeq(6), 'diamond/a', { value: 2 })))
     assembler.flush()
 
     const value = [...testSnapshot(assembler)?.nodes.values() ?? []]
@@ -911,13 +912,13 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView(apply)]),
     )
     assembler.replaceWindow([
-      input(at(1, 'turn/start', { turn: 1 })),
-      input(at(2, 'step/start', { turn: 1, step: 1 })),
+      input(at(SessionSeq(1), 'turn/start', { turn: 1 })),
+      input(at(SessionSeq(2), 'step/start', { turn: 1, step: 1 })),
     ], false)
     assembler.flush()
     expect([...testSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe('open')
 
-    assembler.append(input(at(3, 'step/end', { turn: 1, step: 1 })))
+    assembler.append(input(at(SessionSeq(3), 'step/end', { turn: 1, step: 1 })))
     assembler.flush()
 
     expect(starts).toHaveBeenCalledTimes(2)
@@ -990,14 +991,14 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(1, 'turn/start', { turn: 1 })),
-      input(at(2, 'step/start', { turn: 1, step: 1 })),
+      input(at(SessionSeq(1), 'turn/start', { turn: 1 })),
+      input(at(SessionSeq(2), 'step/start', { turn: 1, step: 1 })),
     ], false)
     assembler.flush()
     expect([...testSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
       .toEqual({ step: 1, turn: 1 })
 
-    assembler.append(input(at(3, 'scope-probe/update', { turn: 1, step: 1, value: 2 })))
+    assembler.append(input(at(SessionSeq(3), 'scope-probe/update', { turn: 1, step: 1, value: 2 })))
     assembler.flush()
 
     expect([...testSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
@@ -1022,11 +1023,11 @@ describe('ConversationNodeAssembler', () => {
       new TestEventDefinitions([definition]),
       new TestViewDefinitions([testView(apply)]),
     )
-    assembler.replaceWindow([input(at(1, 'turn/start', { turn: 1 }))], false)
+    assembler.replaceWindow([input(at(SessionSeq(1), 'turn/start', { turn: 1 }))], false)
     assembler.flush()
     expect([...testSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(0)
 
-    assembler.append(input(at(2, 'step/start', { turn: 1, step: 1 })))
+    assembler.append(input(at(SessionSeq(2), 'step/start', { turn: 1, step: 1 })))
     assembler.flush()
 
     expect(apply).toHaveBeenCalledOnce()
@@ -1042,7 +1043,7 @@ describe('ConversationNodeAssembler', () => {
     assembler.replaceWindow([], false)
     assembler.flush()
 
-    assembler.append(input(at(1, 'turn/start', { turn: 1 })))
+    assembler.append(input(at(SessionSeq(1), 'turn/start', { turn: 1 })))
     assembler.flush()
 
     expect(apply).toHaveBeenCalledOnce()
@@ -1083,11 +1084,11 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(1, 'turn/start', { turn: 1 })),
-      input(at(2, 'step/start', { turn: 1, step: 1 })),
-      input(at(3, 'turn/start', { turn: 2 })),
-      input(at(4, 'command/run', { commandId: 'command', name: 'x' })),
-      input(at(5, 'compaction/start', { compactionId: 'compact', turn: null })),
+      input(at(SessionSeq(1), 'turn/start', { turn: 1 })),
+      input(at(SessionSeq(2), 'step/start', { turn: 1, step: 1 })),
+      input(at(SessionSeq(3), 'turn/start', { turn: 2 })),
+      input(at(SessionSeq(4), 'command/run', { commandId: 'command', name: 'x' })),
+      input(at(SessionSeq(5), 'compaction/start', { compactionId: 'compact', turn: null })),
     ], false)
     assembler.flush()
 
@@ -1111,12 +1112,12 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(1, 'turn/start', { turn: 1 })),
-      input(at(2, 'step/start', { turn: 1, step: 1 })),
+      input(at(SessionSeq(1), 'turn/start', { turn: 1 })),
+      input(at(SessionSeq(2), 'step/start', { turn: 1, step: 1 })),
     ], false)
     assembler.flush()
 
-    assembler.append(input(at(3, 'turn/end', { turn: 1, reason: { kind: 'aborted' } })))
+    assembler.append(input(at(SessionSeq(3), 'turn/end', { turn: 1, reason: { kind: 'aborted' } })))
     assembler.flush()
 
     expect([...testSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe('turn')
@@ -1143,12 +1144,12 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(10, 'tool/call', { turn: 2, step: 3, callId: 'root', name: 'x', arguments: '{}' })),
-      input(at(11, 'tool/code-dispatch-start', { rootCallId: 'root', subCallId: 'a' })),
+      input(at(SessionSeq(10), 'tool/call', { turn: 2, step: 3, callId: 'root', name: 'x', arguments: '{}' })),
+      input(at(SessionSeq(11), 'tool/code-dispatch-start', { rootCallId: 'root', subCallId: 'a' })),
     ], true)
     assembler.flush()
 
-    assembler.append(input(at(12, 'tool/code-dispatch-start', { rootCallId: 'root', subCallId: 'b' })))
+    assembler.append(input(at(SessionSeq(12), 'tool/code-dispatch-start', { rootCallId: 'root', subCallId: 'b' })))
     assembler.flush()
 
     expect([...testSnapshot(assembler)?.nodes.values() ?? []].map(value => value.data))
@@ -1176,9 +1177,9 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(10, 'tool/call', { turn: 2, step: 3, callId: 'root', name: 'x', arguments: '{}' })),
-      input(at(11, 'step/end', { turn: 2, step: 3 })),
-      input(at(12, 'turn/end', { turn: 2, reason: { kind: 'completed' } })),
+      input(at(SessionSeq(10), 'tool/call', { turn: 2, step: 3, callId: 'root', name: 'x', arguments: '{}' })),
+      input(at(SessionSeq(11), 'step/end', { turn: 2, step: 3 })),
+      input(at(SessionSeq(12), 'turn/end', { turn: 2, reason: { kind: 'completed' } })),
     ], true)
     assembler.flush()
 
@@ -1205,10 +1206,10 @@ describe('ConversationNodeAssembler', () => {
       new TestEventDefinitions([definition]),
       new TestViewDefinitions([testView()]),
     )
-    assembler.replaceWindow([input(at(1, 'step/start', { turn: 1, step: 1 }))], false)
+    assembler.replaceWindow([input(at(SessionSeq(1), 'step/start', { turn: 1, step: 1 }))], false)
     assembler.flush()
 
-    assembler.append(input(at(2, 'step/end', { turn: 1, step: 1 })))
+    assembler.append(input(at(SessionSeq(2), 'step/end', { turn: 1, step: 1 })))
     assembler.flush()
 
     expect(seen).toHaveBeenCalledTimes(2)
@@ -1229,7 +1230,7 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
 
-    assembler.replaceWindow([input(at(1, 'command/run', { commandId: 'one', name: 'x' }))], false)
+    assembler.replaceWindow([input(at(SessionSeq(1), 'command/run', { commandId: 'one', name: 'x' }))], false)
     assembler.flush()
 
     expect(fallbackStart).toHaveBeenCalledOnce()
@@ -1253,7 +1254,7 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
 
-    assembler.replaceWindow([input(at(1, 'command/run', { commandId: 'one', name: 'x' }))], false)
+    assembler.replaceWindow([input(at(SessionSeq(1), 'command/run', { commandId: 'one', name: 'x' }))], false)
     assembler.flush()
 
     expect(fallbackStart).toHaveBeenCalledOnce()
@@ -1274,7 +1275,7 @@ describe('ConversationNodeAssembler', () => {
       new TestEventDefinitions([claimed], fallbackDefinition(fallbackStart)),
       new TestViewDefinitions([testView()]),
     )
-    assembler.replaceWindow([input(at(1, 'command/run', { commandId: 'one', name: 'x' }))], false)
+    assembler.replaceWindow([input(at(SessionSeq(1), 'command/run', { commandId: 'one', name: 'x' }))], false)
     assembler.flush()
 
     expect(fallbackStart).not.toHaveBeenCalled()
@@ -1298,11 +1299,11 @@ describe('ConversationNodeAssembler', () => {
       new TestEventDefinitions([definition]),
       new TestViewDefinitions([testView()]),
     )
-    assembler.replaceWindow([input(at(1, 'command/run', { commandId: 'one', name: 'x' }))], false)
+    assembler.replaceWindow([input(at(SessionSeq(1), 'command/run', { commandId: 'one', name: 'x' }))], false)
     assembler.flush()
     expect(testSnapshot(assembler)?.order).toHaveLength(1)
 
-    assembler.append(input(at(2, 'toggle/hide', {})))
+    assembler.append(input(at(SessionSeq(2), 'toggle/hide', {})))
     expect(() => assembler.flush()).toThrow(/withdrew materialized target "test"/)
 
     expect(testSnapshot(assembler)?.order).toHaveLength(1)
@@ -1322,7 +1323,7 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     expect(() => startAssembler.replaceWindow([
-      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+      input(at(SessionSeq(1), 'command/run', { commandId: 'one', name: 'x' })),
     ], false)).toThrow(/Definition "undefined-start" returned undefined from start/)
 
     const updateUndefined: ConversationNodeDefinition<boolean> = {
@@ -1342,10 +1343,10 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     updateAssembler.replaceWindow([
-      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+      input(at(SessionSeq(1), 'command/run', { commandId: 'one', name: 'x' })),
     ], false)
     expect(() => updateAssembler.append(
-      input(at(2, 'command/done', { commandId: 'one', kind: 'success' })),
+      input(at(SessionSeq(2), 'command/done', { commandId: 'one', kind: 'success' })),
     )).toThrow(/Definition "undefined-update" returned undefined from update/)
   })
 
@@ -1363,12 +1364,12 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView()]),
     )
     assembler.replaceWindow([
-      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+      input(at(SessionSeq(1), 'command/run', { commandId: 'one', name: 'x' })),
     ], false)
     assembler.flush()
 
     expect(() => assembler.append(
-      input(at(2, 'command/run', { commandId: 'two', name: 'x' })),
+      input(at(SessionSeq(2), 'command/run', { commandId: 'two', name: 'x' })),
     )).toThrow(/received more than one start Match/)
     assembler.flush()
     expect([...testSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(1)
diff --git a/packages/client/ui-conversation/tests/history-transport.perf.client.ts b/packages/client/ui-conversation/tests/history-transport.perf.client.ts
index 65f2b42893..c04457e08d 100644
--- a/packages/client/ui-conversation/tests/history-transport.perf.client.ts
+++ b/packages/client/ui-conversation/tests/history-transport.perf.client.ts
@@ -9,6 +9,7 @@ import { z } from 'zod'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { isChunkRow, packChunkRuns } from '@deepseek-ai/dsh-session/chunk-rows'
 import type { ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { SessionEvent, SessionEventMap } from '@deepseek-ai/dsh-session/types'
 import type {
   ChunkRowEvent,
@@ -672,7 +673,7 @@ it('reports compact folding cost for long whitespace-prefix runs', () => {
     }
     const start = wireEntry({
       type: 'step/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: TIME_ZERO,
       data: { turn: 1, step: 1 },
     })
diff --git a/packages/client/ui-conversation/tests/request-inspection.client.spec.ts b/packages/client/ui-conversation/tests/request-inspection.client.spec.ts
index 1f0471ce8f..5fbf5cd271 100644
--- a/packages/client/ui-conversation/tests/request-inspection.client.spec.ts
+++ b/packages/client/ui-conversation/tests/request-inspection.client.spec.ts
@@ -1,11 +1,12 @@
 import { describe, expect, it } from 'vitest'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { inspectRequestPrompt } from '../src/client/contract/request-inspection.ts'
 
 const CONFIG = { provider: 'test', model: 'test' }
 
 function header(
-  seq: number,
+  seq: SessionSeq,
   reason: SessionEvent<'request/header'>['data']['reason'],
   value: SessionEvent<'request/header'>['data']['header'],
 ): SessionEvent<'request/header'> {
@@ -19,7 +20,7 @@ function header(
 
 describe('inspectRequestPrompt', () => {
   it('classifies the first complete header as the initial prompt', () => {
-    expect(inspectRequestPrompt(undefined, header(1, 'initial', {
+    expect(inspectRequestPrompt(undefined, header(SessionSeq(1), 'initial', {
       config: CONFIG,
       system: '# System\n\nFollow instructions.',
       tools: [{ name: 'read', description: 'Read a file', parameters: { type: 'object' } }],
@@ -34,7 +35,7 @@ describe('inspectRequestPrompt', () => {
   })
 
   it('suppresses a resume header when the earlier prompt is outside the loaded window', () => {
-    expect(inspectRequestPrompt(undefined, header(2, 'resume', {
+    expect(inspectRequestPrompt(undefined, header(SessionSeq(2), 'resume', {
       config: CONFIG,
       system: 'same prompt',
     }))).toEqual({
@@ -43,22 +44,22 @@ describe('inspectRequestPrompt', () => {
   })
 
   it('classifies system, tool, and combined changes against the previous prompt', () => {
-    const initial = inspectRequestPrompt(undefined, header(1, 'initial', {
+    const initial = inspectRequestPrompt(undefined, header(SessionSeq(1), 'initial', {
       config: CONFIG,
       system: 'first',
       tools: [{ name: 'read', description: 'Read', parameters: { type: 'object' } }],
     })).prompt
-    const system = inspectRequestPrompt(initial, header(2, 'change', {
+    const system = inspectRequestPrompt(initial, header(SessionSeq(2), 'change', {
       config: CONFIG,
       system: 'second',
       tools: [...initial.tools],
     }))
-    const tools = inspectRequestPrompt(system.prompt, header(3, 'change', {
+    const tools = inspectRequestPrompt(system.prompt, header(SessionSeq(3), 'change', {
       config: CONFIG,
       system: 'second',
       tools: [{ name: 'write', description: 'Write', parameters: { type: 'object' } }],
     }))
-    const combined = inspectRequestPrompt(tools.prompt, header(4, 'change', {
+    const combined = inspectRequestPrompt(tools.prompt, header(SessionSeq(4), 'change', {
       config: CONFIG,
       system: 'third',
       tools: [],
@@ -71,12 +72,12 @@ describe('inspectRequestPrompt', () => {
   })
 
   it('omits a change when the prompt and tools are unchanged', () => {
-    const previous = inspectRequestPrompt(undefined, header(1, 'initial', {
+    const previous = inspectRequestPrompt(undefined, header(SessionSeq(1), 'initial', {
       config: CONFIG,
       system: 'same',
     })).prompt
 
-    expect(inspectRequestPrompt(previous, header(2, 'resume', {
+    expect(inspectRequestPrompt(previous, header(SessionSeq(2), 'resume', {
       config: { ...CONFIG, maxTokens: 1_024 },
       system: 'same',
     }))).toEqual({
diff --git a/packages/client/ui-tool/tests/tool-details-render.client.tsx b/packages/client/ui-tool/tests/tool-details-render.client.tsx
index 6338be9931..fb2d60c6bf 100644
--- a/packages/client/ui-tool/tests/tool-details-render.client.tsx
+++ b/packages/client/ui-tool/tests/tool-details-render.client.tsx
@@ -1,5 +1,6 @@
 /** Test adapter for the production conversation.details.tool registration. */
 import type { SessionLiveEventEntry } from '@deepseek-ai/dsh-api-session-controller/client'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import { isJsonValue, type JsonValue } from '@deepseek-ai/dsh-util-values'
 import type {
   ChatConversationViewNode, ChatSnapshot, ConversationNode, DetailsSlotProps,
@@ -74,7 +75,7 @@ export function toolSessionEvents(nodes: readonly ToolResultNode[]): readonly Se
     {
       type: 'event',
       event: {
-        seq: 1,
+        seq: SessionSeq(1),
         time: firstTime - 2,
         type: 'turn/start',
         data: { turn: 1 },
@@ -83,7 +84,7 @@ export function toolSessionEvents(nodes: readonly ToolResultNode[]): readonly Se
     {
       type: 'event',
       event: {
-        seq: 2,
+        seq: SessionSeq(2),
         time: firstTime - 1,
         type: 'step/start',
         data: { turn: 1, step: 1 },
@@ -96,7 +97,7 @@ export function toolSessionEvents(nodes: readonly ToolResultNode[]): readonly Se
     const callEntry: SessionLiveEventEntry = {
       type: 'event',
       event: {
-        seq: callSeq,
+        seq: SessionSeq(callSeq),
         time: node.callTime ?? node.time - 1,
         type: 'tool/call',
         data: {
@@ -112,7 +113,7 @@ export function toolSessionEvents(nodes: readonly ToolResultNode[]): readonly Se
     const resultEntry: SessionLiveEventEntry = {
       type: 'event',
       event: {
-        seq: callSeq + 1,
+        seq: SessionSeq(callSeq + 1),
         time: node.time,
         type: 'tool/result',
         data: jsonFixture({
diff --git a/packages/client/ui-workspace/tests/rename-assembly.client.spec.tsx b/packages/client/ui-workspace/tests/rename-assembly.client.spec.tsx
index 15b0afc345..d57a89ba8b 100644
--- a/packages/client/ui-workspace/tests/rename-assembly.client.spec.tsx
+++ b/packages/client/ui-workspace/tests/rename-assembly.client.spec.tsx
@@ -15,7 +15,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, waitFor, within } from '@testing-library/react'
 import type { ISession } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { WorkspaceId } from '@deepseek-ai/dsh-api-workspace-controller/client'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { RemoteError, SlotTestRuntime, TestRemote, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
@@ -55,7 +55,7 @@ describe('session rename through the assembled browser', () => {
   it('renames via the row menu: binding.session.rename fires, the dialog closes, the row re-labels from the list', async () => {
     const runtime = await createRuntime()
     const rename = vi.fn<ISession['rename']>(async title => ({
-      ok: true, value: { title: title.trim().replace(/\s+/g, ' '), seq: 7 },
+      ok: true, value: { title: title.trim().replace(/\s+/g, ' '), seq: SessionSeq(7) },
     }))
     await runtime.sessions.add({
       id: SID,
diff --git a/packages/compaction/command-compact/tests/command-compact.spec.ts b/packages/compaction/command-compact/tests/command-compact.spec.ts
index 7cc9d3331e..f2ab167d69 100644
--- a/packages/compaction/command-compact/tests/command-compact.spec.ts
+++ b/packages/compaction/command-compact/tests/command-compact.spec.ts
@@ -12,19 +12,19 @@ import {
   type CompactionTrigger,
   type ManualCompactAgentContext,
 } from '@deepseek-ai/dsh-compaction'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import * as commandCompact from '@deepseek-ai/dsh-command-compact'
 
 const COMPACTION_ID = CompactionId('command-compact-test')
 
 const RESULT: CompactionResult = {
   compactionId: COMPACTION_ID,
-  startSeq: 1,
-  summarySeq: 2,
-  endSeq: 3,
+  startSeq: SessionSeq(1),
+  summarySeq: SessionSeq(2),
+  endSeq: SessionSeq(3),
   summary: [{ type: 'text', text: 'summary' }],
-  shadowedRange: { start: 1, end: 7 },
-  shadowedSeqs: [1, 3, 7],
+  shadowedRange: { start: SessionSeq(1), end: SessionSeq(7) },
+  shadowedSeqs: [SessionSeq(1), SessionSeq(3), SessionSeq(7)],
   shadowedTokenCount: 42,
 }
 
diff --git a/packages/compaction/command-compact/tests/loader-composition.spec.ts b/packages/compaction/command-compact/tests/loader-composition.spec.ts
index e4cbedd42a..442d8196dc 100644
--- a/packages/compaction/command-compact/tests/loader-composition.spec.ts
+++ b/packages/compaction/command-compact/tests/loader-composition.spec.ts
@@ -17,18 +17,18 @@ import {
   type ManualCompactAgentContext,
 } from '@deepseek-ai/dsh-compaction'
 import * as commandCompact from '@deepseek-ai/dsh-command-compact'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 
 const COMPACTION_ID = CompactionId('loader-command-compact-test')
 
 const RESULT: CompactionResult = {
   compactionId: COMPACTION_ID,
-  startSeq: 1,
-  summarySeq: 2,
-  endSeq: 3,
+  startSeq: SessionSeq(1),
+  summarySeq: SessionSeq(2),
+  endSeq: SessionSeq(3),
   summary: [{ type: 'text', text: 'loader summary' }],
-  shadowedRange: { start: 3, end: 8 },
-  shadowedSeqs: [3, 5, 8],
+  shadowedRange: { start: SessionSeq(3), end: SessionSeq(8) },
+  shadowedSeqs: [SessionSeq(3), SessionSeq(5), SessionSeq(8)],
   shadowedTokenCount: 99,
 }
 
diff --git a/packages/compaction/compaction-basic/src/index.ts b/packages/compaction/compaction-basic/src/index.ts
index dc7d7371bc..7a6ce3daba 100644
--- a/packages/compaction/compaction-basic/src/index.ts
+++ b/packages/compaction/compaction-basic/src/index.ts
@@ -9,7 +9,7 @@ import z from '@deepseek-ai/schemastery'
 import { CompactionEngine, ManualCompactionError } from '@deepseek-ai/dsh-compaction'
 import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compaction'
 import type { TokenMeter } from '@deepseek-ai/dsh-token-meter'
-import type { Session } from '@deepseek-ai/dsh-session'
+import type { Session, SessionSeq } from '@deepseek-ai/dsh-session'
 import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm'
 import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
 import { assertNever } from '@deepseek-ai/dsh-util-values'
@@ -342,8 +342,8 @@ export class BasicCompactionEngine extends CompactionEngine {
    * @returns the successful durable compaction result.
    */
   override async compactRegion(
-    start: number,
-    end: number,
+    start: SessionSeq,
+    end: SessionSeq,
     agent: Agent,
     signal?: AbortSignal,
   ): Promise<CompactionResult> {
diff --git a/packages/compaction/compaction-basic/src/region.ts b/packages/compaction/compaction-basic/src/region.ts
index b609f949c8..c639814ce7 100644
--- a/packages/compaction/compaction-basic/src/region.ts
+++ b/packages/compaction/compaction-basic/src/region.ts
@@ -19,7 +19,7 @@ import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import { createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
 import type { Message, UserMessage } from '@deepseek-ai/dsh-llm'
 import type { TokenMeasurement, TokenMeter } from '@deepseek-ai/dsh-token-meter'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { frameSummary } from './summarizer.ts'
 import type { SummarizationInput, SummaryResult } from './summarizer.ts'
@@ -31,11 +31,11 @@ interface RegionDependencies {
 
 /** One validated inclusive span of current surface positions. */
 interface SurfaceSelection {
-  readonly start: number
-  readonly end: number
+  readonly start: SessionSeq
+  readonly end: SessionSeq
   readonly startIdx: number
   readonly endIdx: number
-  readonly shadowedSeqs: readonly number[]
+  readonly shadowedSeqs: readonly SessionSeq[]
 }
 
 /** A selection with its priced snapshot and the replay input built from it. */
@@ -66,7 +66,7 @@ interface CompactionTransactionOptions {
 interface CompactionEntryState {
   readonly openTurn: number | null
   readonly unmatchedCompactionStart: SessionEvent<'compaction/start'> | undefined
-  readonly latestEndSeedSeq: number | undefined
+  readonly latestEndSeedSeq: SessionSeq | undefined
 }
 
 /**
@@ -101,7 +101,7 @@ export function selectCompactableRange(
   session: Session,
   measurement: TokenMeasurement,
   retainTokens: number,
-): { start: number; end: number } | null {
+): { start: SessionSeq; end: SessionSeq } | null {
   const pricedNodes = measurement.nodes
   if (pricedNodes.length === 0) return null
 
@@ -154,8 +154,8 @@ export function selectCompactableRange(
 export async function compactSurfaceRegion(
   dependencies: RegionDependencies,
   session: Session,
-  start: number,
-  end: number,
+  start: SessionSeq,
+  end: SessionSeq,
   agent: Agent,
   options: CompactionTransactionOptions,
   signal?: AbortSignal,
@@ -287,7 +287,7 @@ function throwManualFailure(failure: TransactionFailure): never {
  */
 function assertCompactionInactive(
   unmatchedCompactionStart: SessionEvent<'compaction/start'> | undefined,
-  latestEndSeedSeq: number | undefined,
+  latestEndSeedSeq: SessionSeq | undefined,
   stage: string,
 ): void {
   if (unmatchedCompactionStart === undefined
@@ -314,7 +314,7 @@ export function assertNoActiveCompaction(session: Session, stage: string): void
 }
 
 /** Validate one requested surface-position span before asynchronous work begins. */
-function validateSurfaceRegion(session: Session, start: number, end: number): SurfaceSelection {
+function validateSurfaceRegion(session: Session, start: SessionSeq, end: SessionSeq): SurfaceSelection {
   const nodes = session.surface.nodes
   const startIdx = nodes.indexOf(start)
   const endIdx = nodes.indexOf(end)
@@ -507,7 +507,7 @@ function completeCompaction(
  */
 function buildSummarizationInput(
   session: Session,
-  shadowedSeqs: readonly number[],
+  shadowedSeqs: readonly SessionSeq[],
 ): SummarizationInput {
   const header = session.requestHeader()
   const regionMessages = shadowedSeqs
@@ -528,10 +528,10 @@ function inspectCompactionEntryState(session: Session): CompactionEntryState {
   let openTurnStateKnown = false
   let unmatchedCompactionStart: SessionEvent<'compaction/start'> | undefined
   let compactionEntryStateKnown = false
-  let latestEndSeedSeq: number | undefined
+  let latestEndSeedSeq: SessionSeq | undefined
   for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
     // oxlint-disable-next-line typescript/no-non-null-assertion
-    const event = session.eventAt(seq)!
+    const event = session.eventAt(SessionSeq(seq))!
     if (latestEndSeedSeq === undefined && event.type === 'session/end-seed') {
       latestEndSeedSeq = event.seq
     }
diff --git a/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts b/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts
index 20125c18c6..e6ed88274b 100644
--- a/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts
+++ b/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts
@@ -23,7 +23,7 @@ import type {
   StreamChunk,
   TokenUsage,
 } from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeter from '@deepseek-ai/dsh-token-meter'
 import { agentEvents, type Agent, type RequestErrorAction } from '@deepseek-ai/dsh-agent'
@@ -911,8 +911,8 @@ describe('compaction region transaction', () => {
     const session = conversation(2)
     const nodes = session.surface.nodes
     await expect(compact.compactRegion(
-      startOverride ?? nodes[0]!,
-      endOverride ?? nodes[1]!,
+      startOverride === undefined ? nodes[0]! : SessionSeq(startOverride),
+      endOverride === undefined ? nodes[1]! : SessionSeq(endOverride),
       agent(session, MODEL),
     )).rejects.toThrow(pattern)
   })
@@ -1686,12 +1686,12 @@ describe('automatic listener and loader composition', () => {
     const session = conversation(2)
     const fakeResult: CompactionResult = {
       compactionId: CompactionId('fake-compaction'),
-      startSeq: 1,
-      summarySeq: 2,
-      endSeq: 3,
+      startSeq: SessionSeq(1),
+      summarySeq: SessionSeq(2),
+      endSeq: SessionSeq(3),
       summary: [{ type: 'text', text: 'fake' }],
-      shadowedRange: { start: 1, end: 2 },
-      shadowedSeqs: [1, 2],
+      shadowedRange: { start: SessionSeq(1), end: SessionSeq(2) },
+      shadowedSeqs: [SessionSeq(1), SessionSeq(2)],
       shadowedTokenCount: 10,
     }
     vi.spyOn(compact, 'compactIfNeeded').mockResolvedValue(fakeResult)
diff --git a/packages/compaction/compaction-tool-result-pruner/src/index.ts b/packages/compaction/compaction-tool-result-pruner/src/index.ts
index d3f3212c1e..d13303e0c9 100644
--- a/packages/compaction/compaction-tool-result-pruner/src/index.ts
+++ b/packages/compaction/compaction-tool-result-pruner/src/index.ts
@@ -8,7 +8,7 @@ import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { freezeMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { Session, SessionEvent, ToolResultMessage } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionSeq, ToolResultMessage } from '@deepseek-ai/dsh-session'
 // Type-only: the `compaction/*` SessionEventMap merges (the shadow-price event).
 import type {} from '@deepseek-ai/dsh-compaction'
 // Type-only: the `ctx.tokenMeter` Context merge for the declared injection.
@@ -36,7 +36,7 @@ declare module '@deepseek-ai/cordis' {
 }
 
 interface SnapshotCandidate {
-  readonly seq: number
+  readonly seq: SessionSeq
   readonly event: SessionEvent<'tool/result'>
 }
 
diff --git a/packages/compaction/compaction-tool-result-pruner/src/types.ts b/packages/compaction/compaction-tool-result-pruner/src/types.ts
index d8228765a3..8cc6934b10 100644
--- a/packages/compaction/compaction-tool-result-pruner/src/types.ts
+++ b/packages/compaction/compaction-tool-result-pruner/src/types.ts
@@ -1,4 +1,5 @@
 import type { ToolCallId } from '@deepseek-ai/dsh-llm'
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 
 /** Character-budget policy for deterministic tool-result pruning. */
 export interface ToolResultPruneConfig {
@@ -20,9 +21,9 @@ export interface ResolvedConfig {
 /** Cited source event and size accounting for one landed surface replacement. */
 export interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
-  readonly originalSeq: number
+  readonly originalSeq: SessionSeq
   /** Newly appended pruned tool-result event. */
-  readonly replacementSeq: number
+  readonly replacementSeq: SessionSeq
   /** Tool call shared by the original and replacement. */
   readonly callId: ToolCallId
   /** Original text size in Unicode code points. */
diff --git a/packages/compaction/compaction/src/index.ts b/packages/compaction/compaction/src/index.ts
index 13d8fb06b5..cfbdd42209 100644
--- a/packages/compaction/compaction/src/index.ts
+++ b/packages/compaction/compaction/src/index.ts
@@ -8,7 +8,7 @@
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import type { Session } from '@deepseek-ai/dsh-session'
+import type { Session, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { CompactionResult } from './types.ts'
 
@@ -162,8 +162,8 @@ export abstract class CompactionEngine extends Service {
    * @returns the appended event seqs, summary, replaced range, and token accounting.
    */
   abstract compactRegion(
-    start: number,
-    end: number,
+    start: SessionSeq,
+    end: SessionSeq,
     agent: CompactionAgentContext,
     signal?: AbortSignal,
   ): Promise<CompactionResult>
diff --git a/packages/compaction/compaction/src/invariant.ts b/packages/compaction/compaction/src/invariant.ts
index df82f348ee..ce19a6670f 100644
--- a/packages/compaction/compaction/src/invariant.ts
+++ b/packages/compaction/compaction/src/invariant.ts
@@ -1,8 +1,9 @@
 /** Package-owned compaction log-stream invariants. @module @deepseek-ai/dsh-compaction/invariant */
 
 import type { Context } from '@deepseek-ai/cordis'
-import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session'
+import { isReplacementSurfaceEvent, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { SurfaceManager } from '@deepseek-ai/dsh-session/surface'
 import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 import type { CompactionId } from './brand.ts'
 import { isCompactCheckpointSource } from './checkpoint.ts'
@@ -19,7 +20,7 @@ export const inject = ['invariants']
 interface CompactionTrace {
   compactionId: CompactionId
   sourceCommandId: string | undefined
-  startSeq: number
+  startSeq: SessionSeq
   turn: number | null
   summarized: boolean
 }
@@ -27,11 +28,13 @@ interface CompactionTrace {
 interface SessionTrace {
   openTurn: number | null
   compaction: CompactionTrace | undefined
+  surfaceEvents: SessionEvent[]
+  surface: SurfaceManager
 }
 
 type CompactionTransition =
-  | { kind: 'start'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: number; turn: number | null }
-  | { kind: 'summary'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: number; turn: number | null }
+  | { kind: 'start'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: SessionSeq; turn: number | null }
+  | { kind: 'summary'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: SessionSeq; turn: number | null }
   | { kind: 'end' }
   | { kind: 'end-seed' }
 
@@ -40,6 +43,44 @@ function validateId(value: unknown, label: string, fail: InvariantFailure): asse
   if (typeof value !== 'string' || value.length === 0) fail(`${label} must be a non-empty string`)
 }
 
+/** Validate a durable event-sequence identity at this package's event boundary. */
+function validateSeq(value: unknown, label: string, fail: InvariantFailure): SessionSeq {
+  if (typeof value !== 'number') return fail(`${label} must be a non-negative safe integer event seq`)
+  try {
+    return SessionSeq(value)
+  } catch {
+    return fail(`${label} must be a non-negative safe integer event seq`)
+  }
+}
+
+/** Validate one shadowed surface span and its complete ordered identity list. */
+function validateShadowedSeqs(
+  trace: SessionTrace,
+  event: SessionEvent<'compaction/summary' | 'compaction/prune'>,
+  fail: InvariantFailure,
+): void {
+  const eventType = event.type
+  const { data } = event
+  const start = validateSeq(data.shadowedRange.start, `${eventType} shadowedRange.start`, fail)
+  const end = validateSeq(data.shadowedRange.end, `${eventType} shadowedRange.end`, fail)
+  const seqs = data.shadowedSeqs.map((seq, index) => validateSeq(seq, `${eventType} shadowedSeqs[${index}]`, fail))
+  if (seqs.length === 0) fail(`${eventType} shadowedSeqs must be non-empty`)
+  if (seqs[0] !== start || seqs.at(-1) !== end) {
+    fail(`${eventType} shadowedRange must match the first and last shadowedSeqs`)
+  }
+  const surface = trace.surface.nodes
+  const startIndex = surface.indexOf(start)
+  const endIndex = surface.indexOf(end)
+  if (startIndex < 0 || endIndex < startIndex) {
+    fail(`${eventType} shadowed seqs must name an earlier current surface span`)
+  }
+  const expected = surface.slice(startIndex, endIndex + 1)
+  if (expected.length !== seqs.length
+    || expected.some((seq, index) => seq !== seqs[index])) {
+    fail(`${eventType} shadowedSeqs must list every node in the current surface span`)
+  }
+}
+
 /** Keep the optional initiating command identity stable across one transaction. */
 function validateSourceCommandId(
   eventType: string,
@@ -75,9 +116,9 @@ function validateCheckpoint(
 /** Compaction starts still unmatched when a later seed boundary made them stale. */
 function inheritedOrphanStartSeqs(
   events: readonly SessionEvent[],
-): ReadonlySet<number> {
-  const stale = new Set<number>()
-  let openStartSeq: number | undefined
+): ReadonlySet<SessionSeq> {
+  const stale = new Set<SessionSeq>()
+  let openStartSeq: SessionSeq | undefined
   for (const event of events) {
     if (event.type === 'compaction/start') {
       openStartSeq = event.seq
@@ -142,6 +183,10 @@ function validateCompactionEvent(
   fail: InvariantFailure,
 ): CompactionTransition | undefined {
   if (event.type === 'session/end-seed') return { kind: 'end-seed' }
+  if (event.type === 'compaction/prune') {
+    validateShadowedSeqs(trace, event, fail)
+    return undefined
+  }
   if (event.type === 'user/message'
     && isReplacementSurfaceEvent(event)
     && isCompactCheckpointSource(event.data.source)) {
@@ -182,11 +227,7 @@ function validateCompactionEvent(
     validateSourceCommandId('compaction/summary', event.data.sourceCommandId, open.sourceCommandId, fail)
     validateOwner(open.turn, trace.openTurn, event.type, fail)
     if (open.summarized) fail('compaction/summary repeated within one compaction')
-    const seqs = event.data.shadowedSeqs
-    if (seqs.length === 0) fail('compaction/summary shadowedSeqs must be non-empty')
-    if (seqs[0] !== event.data.shadowedRange.start || seqs.at(-1) !== event.data.shadowedRange.end) {
-      fail('compaction/summary shadowedRange must match the first and last shadowedSeqs')
-    }
+    validateShadowedSeqs(trace, event, fail)
     if (!Number.isSafeInteger(event.data.shadowedTokenCount) || event.data.shadowedTokenCount < 0) {
       fail('compaction/summary shadowedTokenCount must be a non-negative safe integer')
     }
@@ -249,7 +290,13 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
   const traces = new WeakMap<Session, SessionTrace>()
   const staged = new WeakMap<SessionEvent, { session: Session; transition: CompactionTransition }>()
   const seed = (session: Session): SessionTrace => {
-    const trace: SessionTrace = { openTurn: null, compaction: undefined }
+    const surfaceEvents: SessionEvent[] = []
+    const trace: SessionTrace = {
+      openTurn: null,
+      compaction: undefined,
+      surfaceEvents,
+      surface: new SurfaceManager(surfaceEvents),
+    }
     traces.set(session, trace)
     const events = session.snapshotEvents()
     const staleOrphanStartSeqs = inheritedOrphanStartSeqs(events)
@@ -266,6 +313,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
       const transition = validateCompactionEvent(trace, event, fail)
       if (transition !== undefined) trace.compaction = applyCompactionTransition(transition)
       applyTurnBoundary(trace, event)
+      trace.surfaceEvents.push(event)
     }
     return trace
   }
@@ -276,16 +324,22 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
   ctx.on('session/event', (session, event) => {
     const trace = traceFor(session)
     validateTurnBoundary(trace, event, fail)
-    if (applyTurnBoundary(trace, event)) return
-    if (event.type !== 'session/end-seed'
+    const changedTurn = applyTurnBoundary(trace, event)
+    if (!changedTurn && event.type !== 'session/end-seed'
       && event.type !== 'compaction/start'
       && event.type !== 'compaction/summary'
-      && event.type !== 'compaction/end') return
-    const candidate = staged.get(event)
-    /* v8 ignore next -- internal/dispatch stages every compaction event */
-    if (candidate === undefined || candidate.session !== session) return fail('compaction event published without pre-commit validation')
-    staged.delete(event)
-    trace.compaction = applyCompactionTransition(candidate.transition)
+      && event.type !== 'compaction/end') {
+      trace.surfaceEvents.push(event)
+      return
+    }
+    if (!changedTurn) {
+      const candidate = staged.get(event)
+      /* v8 ignore next -- internal/dispatch stages every compaction event */
+      if (candidate === undefined || candidate.session !== session) return fail('compaction event published without pre-commit validation')
+      staged.delete(event)
+      trace.compaction = applyCompactionTransition(candidate.transition)
+    }
+    trace.surfaceEvents.push(event)
   }, { global: true })
   ctx.on('internal/dispatch', (_mode, eventName, args) => {
     if (eventName !== 'session/event') return
diff --git a/packages/compaction/compaction/src/tool-pairing.ts b/packages/compaction/compaction/src/tool-pairing.ts
index c492d53a70..56ec6a2368 100644
--- a/packages/compaction/compaction/src/tool-pairing.ts
+++ b/packages/compaction/compaction/src/tool-pairing.ts
@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-compaction/tool-pairing
  */
 
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionSeq } from '@deepseek-ai/dsh-session'
 
 /** Incremental balance state for one session surface generation. */
 interface BalanceCache {
@@ -18,7 +18,7 @@ interface BalanceCache {
    */
   cutBalanced: readonly boolean[]
   /** Current surface position of each event seq, indexing {@link cutBalanced}. */
-  indexBySeq: Map<number, number>
+  indexBySeq: Map<SessionSeq, number>
   /** In-progress tool-call count after the processed surface tail. */
   inProgressToolCalls: number
 }
@@ -41,7 +41,7 @@ function eventDelta(event: SessionEvent): number {
 function extendCache(
   session: Session,
   cache: BalanceCache,
-  seqs: readonly number[],
+  seqs: readonly SessionSeq[],
 ): BalanceCache {
   const processed = cache.cutBalanced.length - 1
   const tail = seqs.slice(processed)
@@ -91,7 +91,7 @@ function balanceCache(session: Session): BalanceCache {
 }
 
 /** Balance of the cut at a sequence's position plus offset, rejecting seqs outside current membership. */
-function cutBalance(cache: BalanceCache, seq: number, offset: 0 | 1): boolean {
+function cutBalance(cache: BalanceCache, seq: SessionSeq, offset: 0 | 1): boolean {
   const index = cache.indexBySeq.get(seq)
   const balanced = index === undefined ? undefined : cache.cutBalanced[index + offset]
   if (balanced === undefined) {
@@ -108,7 +108,7 @@ function cutBalance(cache: BalanceCache, seq: number, offset: 0 | 1): boolean {
  * @throws when the seq is absent from the current surface, a surface sequence has no
  * matching log event, or a tool result has no preceding open call.
  */
-export function toolPairingBalancedBefore(session: Session, seq: number): boolean {
+export function toolPairingBalancedBefore(session: Session, seq: SessionSeq): boolean {
   return cutBalance(balanceCache(session), seq, 0)
 }
 
@@ -120,6 +120,6 @@ export function toolPairingBalancedBefore(session: Session, seq: number): boolea
  * @throws when the seq is absent from the current surface, a surface sequence has no
  * matching log event, or a tool result has no preceding open call.
  */
-export function toolPairingBalancedAfter(session: Session, seq: number): boolean {
+export function toolPairingBalancedAfter(session: Session, seq: SessionSeq): boolean {
   return cutBalance(balanceCache(session), seq, 1)
 }
diff --git a/packages/compaction/compaction/src/types.ts b/packages/compaction/compaction/src/types.ts
index 0ad5796d93..5a7d12c1b2 100644
--- a/packages/compaction/compaction/src/types.ts
+++ b/packages/compaction/compaction/src/types.ts
@@ -9,6 +9,7 @@
 
 import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { CompactionId } from './brand.ts'
 
 export type { CompactionId }
@@ -34,8 +35,8 @@ declare module '@deepseek-ai/dsh-session/types' {
       compactionId: CompactionId
       sourceCommandId?: CommandId
       summary: ContentBlock[]
-      shadowedRange: { start: number; end: number }
-      shadowedSeqs: number[]
+      shadowedRange: { start: SessionSeq; end: SessionSeq }
+      shadowedSeqs: SessionSeq[]
       shadowedTokenCount: number
       /** The provider route that wrote the summary. */
       provider: string
@@ -80,9 +81,9 @@ declare module '@deepseek-ai/dsh-session/types' {
      */
     'compaction/prune': {
       /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
-      shadowedRange: { start: number; end: number }
+      shadowedRange: { start: SessionSeq; end: SessionSeq }
       /** The seqs of all shadowed surface nodes, in surface order. */
-      shadowedSeqs: number[]
+      shadowedSeqs: SessionSeq[]
       /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
       shadowedTokenCount: number
     }
@@ -96,11 +97,11 @@ export interface CompactionResult {
   /** Human command that initiated this compaction, when it was manual. */
   sourceCommandId?: CommandId
   /** The seq of the appended `compaction/start` event. */
-  startSeq: number
+  startSeq: SessionSeq
   /** The seq of the appended `compaction/summary` event. */
-  summarySeq: number
+  summarySeq: SessionSeq
   /** The seq of the appended `compaction/end` event. */
-  endSeq: number
+  endSeq: SessionSeq
   /** The summary content blocks produced by the backend. */
   summary: ContentBlock[]
   /**
@@ -111,9 +112,9 @@ export interface CompactionResult {
    * can be GREATER than `end`. {@link CompactionResult.shadowedSeqs} is the
    * authoritative set of shadowed nodes, in surface order.
    */
-  shadowedRange: { start: number; end: number }
+  shadowedRange: { start: SessionSeq; end: SessionSeq }
   /** The seqs of all shadowed surface nodes, in surface order. */
-  shadowedSeqs: number[]
+  shadowedSeqs: SessionSeq[]
   /** Estimated token count of the shadowed content. */
   shadowedTokenCount: number
 }
diff --git a/packages/compaction/compaction/tests/compaction.spec.ts b/packages/compaction/compaction/tests/compaction.spec.ts
index 8b02f5f811..d0436da6d3 100644
--- a/packages/compaction/compaction/tests/compaction.spec.ts
+++ b/packages/compaction/compaction/tests/compaction.spec.ts
@@ -9,6 +9,7 @@ import {
 } from '@deepseek-ai/dsh-compaction'
 import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compaction'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { CompactionAgentContext } from '@deepseek-ai/dsh-compaction'
 import type { ManualCompactAgentContext } from '@deepseek-ai/dsh-compaction'
 
@@ -40,8 +41,8 @@ class StubCompactionEngine extends CompactionEngine {
   }
 
   override async compactRegion(
-    start: number,
-    end: number,
+    start: SessionSeq,
+    end: SessionSeq,
     agent: CompactionAgentContext,
     signal?: AbortSignal,
   ): Promise<CompactionResult> {
diff --git a/packages/compaction/compaction/tests/invariant.spec.ts b/packages/compaction/compaction/tests/invariant.spec.ts
index 1aa8682e6a..6bae84418d 100644
--- a/packages/compaction/compaction/tests/invariant.spec.ts
+++ b/packages/compaction/compaction/tests/invariant.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { CompactionId, compactCheckpointSource } from '@deepseek-ai/dsh-compaction'
 import * as CompactionInvariant from '@deepseek-ai/dsh-compaction/invariant'
@@ -20,16 +20,27 @@ const NEXT_COMPACTION_ID = CompactionId('next-test-compaction')
 const TEST_COMMAND_ID = CommandId('test-command')
 const NEXT_COMMAND_ID = CommandId('next-test-command')
 
-const summary = (overrides: Record<string, unknown> = {}) => ({
-  compactionId: TEST_COMPACTION_ID,
-  summary: [{ type: 'text' as const, text: 'short' }],
-  shadowedRange: { start: 2, end: 4 },
-  shadowedSeqs: [2, 3, 4],
-  shadowedTokenCount: 12,
-  provider: 'mock',
-  model: 'mock',
-  ...overrides,
-})
+const summary = (session: Session, overrides: Record<string, unknown> = {}) => {
+  const appendMessage = (text: string) => session.append(
+    'user/message',
+    createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }),
+    { surfaceOp: 'append' },
+  )
+  const first = appendMessage('first')
+  const second = appendMessage('second')
+  const third = appendMessage('third')
+  const shadowedSeqs: [SessionSeq, SessionSeq, SessionSeq] = [first.seq, second.seq, third.seq]
+  return {
+    compactionId: TEST_COMPACTION_ID,
+    summary: [{ type: 'text' as const, text: 'short' }],
+    shadowedRange: { start: first.seq, end: third.seq },
+    shadowedSeqs,
+    shadowedTokenCount: 12,
+    provider: 'mock',
+    model: 'mock',
+    ...overrides,
+  }
+}
 
 function startTurn(session: ReturnType<Context['sessions']['create']>, turn = 1): void {
   session.append('turn/start', { turn })
@@ -41,7 +52,15 @@ describe('compaction invariants', () => {
     const success = ctx.sessions.create()
     startTurn(success)
     success.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
-    success.append('compaction/summary', summary())
+    const summaryData = summary(success)
+    success.append('compaction/summary', summaryData)
+    success.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }],
+      source: compactCheckpointSource(TEST_COMPACTION_ID),
+    }), {
+      surfaceOp: { op: 'replace', ...summaryData.shadowedRange },
+      sourceEventSeqs: summaryData.shadowedSeqs,
+    })
     success.append('compaction/end', { compactionId: TEST_COMPACTION_ID, turn: 1 })
 
     const failed = ctx.sessions.create()
@@ -50,11 +69,54 @@ describe('compaction invariants', () => {
     failed.append('compaction/end', { compactionId: TEST_COMPACTION_ID, turn: 2, error: 'provider failed' })
   })
 
+  it('rejects shadow identities outside the exact earlier surface span', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    const turn = session.append('turn/start', { turn: 1 })
+    session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+    const valid = summary(session)
+    const current = SessionSeq(session.seq)
+    expect(() => session.append('compaction/summary', {
+      ...valid,
+      shadowedRange: { start: current, end: current },
+      shadowedSeqs: [current],
+    })).toThrow(/must name an earlier current surface span/)
+    expect(() => session.append('compaction/summary', {
+      ...valid,
+      shadowedRange: { start: turn.seq, end: turn.seq },
+      shadowedSeqs: [turn.seq],
+    })).toThrow(/must name an earlier current surface span/)
+    expect(() => session.append('compaction/summary', {
+      ...valid,
+      shadowedSeqs: [valid.shadowedSeqs[0], valid.shadowedSeqs[2]],
+    })).toThrow(/must list every node in the current surface span/)
+    expect(() => session.append('compaction/summary', {
+      ...valid,
+      shadowedRange: { start: valid.shadowedSeqs[2], end: valid.shadowedSeqs[0] },
+      shadowedSeqs: [valid.shadowedSeqs[2], valid.shadowedSeqs[0]],
+    })).toThrow(/must name an earlier current surface span/)
+    expect(() => session.append('compaction/summary', {
+      ...valid,
+      shadowedSeqs: [valid.shadowedSeqs[0], valid.shadowedSeqs[2], valid.shadowedSeqs[2]],
+    })).toThrow(/must list every node in the current surface span/)
+  })
+
+  it('validates a model-free prune against the current surface', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    const shadow = summary(session)
+    expect(() => session.append('compaction/prune', {
+      shadowedRange: shadow.shadowedRange,
+      shadowedSeqs: shadow.shadowedSeqs,
+      shadowedTokenCount: shadow.shadowedTokenCount,
+    })).not.toThrow()
+  })
+
   it('accepts standalone successful and failed compaction lifecycles between turns', async () => {
     const ctx = await setup()
     const success = ctx.sessions.create()
     success.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: null })
-    success.append('compaction/summary', summary())
+    success.append('compaction/summary', summary(success))
     success.append('compaction/end', { compactionId: TEST_COMPACTION_ID, turn: null })
 
     const failed = ctx.sessions.create()
@@ -168,14 +230,14 @@ describe('compaction invariants', () => {
     const session = Session.create(SessionId('bare-compaction-session'))
     expect(() => {
       ctx.emit('session/event', session, {
-        type: 'turn/start', seq: 0, time: 0,
+        type: 'turn/start', seq: SessionSeq(0), time: 0,
         data: { turn: 1 },
       })
       ctx.emit('session/event', session, {
-        type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 },
+        type: 'step/start', seq: SessionSeq(1), time: 1, data: { turn: 1, step: 1 },
       })
       ctx.emit('session/event', session, {
-        type: 'compaction/start', seq: 2, time: 2,
+        type: 'compaction/start', seq: SessionSeq(2), time: 2,
         data: { compactionId: TEST_COMPACTION_ID, turn: 1 },
       })
     }).not.toThrow()
@@ -257,7 +319,7 @@ describe('compaction invariants', () => {
     }), { surfaceOp: 'append' })
     startTurn(session)
     session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
-    session.append('compaction/summary', summary())
+    session.append('compaction/summary', summary(session))
 
     expect(() => session.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'checkpoint' }],
@@ -311,7 +373,7 @@ describe('compaction invariants', () => {
       })
     }, /compaction\/start sourceCommandId must be a non-empty string/],
     ['summary without start', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compaction/summary', summary())
+      session.append('compaction/summary', summary(session))
     }, /no matching compaction\/start/],
     ['nested start', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
@@ -319,12 +381,12 @@ describe('compaction invariants', () => {
     }, /still compacting/],
     ['repeated summary', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
-      session.append('compaction/summary', summary())
-      session.append('compaction/summary', summary())
+      session.append('compaction/summary', summary(session))
+      session.append('compaction/summary', summary(session))
     }, /repeated within one compaction/],
     ['summary for another compaction', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
-      session.append('compaction/summary', summary({ compactionId: NEXT_COMPACTION_ID }))
+      session.append('compaction/summary', summary(session, { compactionId: NEXT_COMPACTION_ID }))
     }, /compaction\/summary id .* does not match compaction\/start id/],
     ['summary for another source command', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compaction/start', {
@@ -332,19 +394,31 @@ describe('compaction invariants', () => {
         sourceCommandId: TEST_COMMAND_ID,
         turn: 1,
       })
-      session.append('compaction/summary', summary({ sourceCommandId: NEXT_COMMAND_ID }))
+      session.append('compaction/summary', summary(session, { sourceCommandId: NEXT_COMMAND_ID }))
     }, /compaction\/summary sourceCommandId .* does not match compaction\/start sourceCommandId/],
     ['empty shadow set', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
-      session.append('compaction/summary', summary({ shadowedSeqs: [] }))
+      session.append('compaction/summary', summary(session, { shadowedSeqs: [] }))
     }, /shadowedSeqs must be non-empty/],
     ['wrong endpoints', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
-      session.append('compaction/summary', summary({ shadowedRange: { start: 1, end: 4 } }))
+      session.append('compaction/summary', summary(session, { shadowedRange: { start: 1, end: 4 } }))
     }, /shadowedRange must match/],
+    ['non-numeric shadow seq', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compaction/summary', summary(session, {
+        shadowedRange: { start: 'bad', end: 'bad' }, shadowedSeqs: ['bad'],
+      }))
+    }, /non-negative safe integer event seq/],
+    ['negative shadow seq', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compaction/summary', summary(session, {
+        shadowedRange: { start: -1, end: -1 }, shadowedSeqs: [-1],
+      }))
+    }, /non-negative safe integer event seq/],
     ['invalid token count', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compaction/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
-      session.append('compaction/summary', summary({ shadowedTokenCount: -1 }))
+      session.append('compaction/summary', summary(session, { shadowedTokenCount: -1 }))
     }, /non-negative safe integer/],
     ['end without start', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compaction/end', { compactionId: TEST_COMPACTION_ID, turn: 1, error: 'failed' })
diff --git a/packages/compaction/compaction/tests/tool-pairing.spec.ts b/packages/compaction/compaction/tests/tool-pairing.spec.ts
index 8478f47edd..19b5a460c5 100644
--- a/packages/compaction/compaction/tests/tool-pairing.spec.ts
+++ b/packages/compaction/compaction/tests/tool-pairing.spec.ts
@@ -1,16 +1,16 @@
 import { describe, expect, it } from 'vitest'
 import { createUserMessage, ToolCallId , createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
 import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionSeq as SessionSeqType } from '@deepseek-ai/dsh-session'
 
 const SURFACE = { surfaceOp: 'append' as const }
 
-function seqOf(session: Session, type: SessionEvent['type'], nth = 0): number {
+function seqOf(session: Session, type: SessionEvent['type'], nth = 0): SessionSeqType {
   return session.snapshotEvents().filter(event => event.type === type)[nth]!.seq
 }
 
-function surfaceSeq(session: Session, seq: number): number {
+function surfaceSeq(session: Session, seq: SessionSeqType): SessionSeqType {
   const current = session.surface.nodes.find(candidate => candidate === seq)
   if (current === undefined) throw new Error(`seq ${seq} is not on the surface`)
   return current
@@ -188,7 +188,7 @@ describe('tool-pairing surface identity', () => {
 
   it('rejects missing seqs before and after, including an empty surface', () => {
     const session = Session.create(SessionId('missing-membership'))
-    const missing = 999
+    const missing = SessionSeq(999)
     expect(() => toolPairingBalancedBefore(session, missing)).toThrow(/surface seq 999 not found/)
     expect(() => toolPairingBalancedAfter(session, missing)).toThrow(/surface seq 999 not found/)
 
@@ -204,14 +204,14 @@ describe('tool-pairing cache refresh', () => {
   it('does no event reads for unchanged or log-only growth, folds only appended nodes, and rebuilds on replace', () => {
     const events: SessionEvent[] = [
       {
-        type: 'user/message', seq: 0, time: 0,
+        type: 'user/message', seq: SessionSeq(0), time: 0,
         data: createUserMessage({
           content: [{ type: 'text', text: 'user' }], source: { kind: 'user' },
         }),
         surfaceOp: 'append',
       },
       {
-        type: 'assistant/message', seq: 1, time: 1,
+        type: 'assistant/message', seq: SessionSeq(1), time: 1,
         data: {
           turn: 1,
           step: 1,
@@ -227,7 +227,7 @@ describe('tool-pairing cache refresh', () => {
         surfaceOp: 'append',
       },
       {
-        type: 'tool/result', seq: 2, time: 2,
+        type: 'tool/result', seq: SessionSeq(2), time: 2,
         data: {
           turn: 1, step: 1,
           message: createToolResultMessage({
@@ -239,7 +239,7 @@ describe('tool-pairing cache refresh', () => {
         surfaceOp: 'append',
       },
     ]
-    const nodes: number[] = [0, 1, 2]
+    const nodes: SessionSeqType[] = [SessionSeq(0), SessionSeq(1), SessionSeq(2)]
     let generation = 0
     let eventReads = 0
     const surface = {
@@ -262,25 +262,25 @@ describe('tool-pairing cache refresh', () => {
     expect(eventReads).toBe(3)
 
     events.push({
-      type: 'turn/end', seq: 3, time: 3, data: { turn: 1, reason: { kind: 'completed' } },
+      type: 'turn/end', seq: SessionSeq(3), time: 3, data: { turn: 1, reason: { kind: 'completed' } },
     })
     expect(toolPairingBalancedAfter(session, nodes[2]!)).toBe(true)
     expect(eventReads).toBe(3)
 
     events.push({
-      type: 'user/message', seq: 4, time: 4,
+      type: 'user/message', seq: SessionSeq(4), time: 4,
       data: createUserMessage({
         content: [{ type: 'text', text: 'tail' }], source: { kind: 'user' },
       }),
       surfaceOp: 'append',
     })
-    nodes.push(4)
+    nodes.push(SessionSeq(4))
     expect(toolPairingBalancedAfter(session, nodes[3]!)).toBe(true)
     expect(eventReads).toBe(4)
 
     events.push(
       {
-        type: 'assistant/message', seq: 5, time: 5,
+        type: 'assistant/message', seq: SessionSeq(5), time: 5,
         data: {
           turn: 2,
           step: 1,
@@ -296,7 +296,7 @@ describe('tool-pairing cache refresh', () => {
         surfaceOp: 'append',
       },
       {
-        type: 'tool/result', seq: 6, time: 6,
+        type: 'tool/result', seq: SessionSeq(6), time: 6,
         data: {
           turn: 2, step: 1,
           message: createToolResultMessage({
@@ -308,18 +308,18 @@ describe('tool-pairing cache refresh', () => {
         surfaceOp: 'append',
       },
     )
-    nodes.push(5, 6)
+    nodes.push(SessionSeq(5), SessionSeq(6))
     expect(toolPairingBalancedAfter(session, nodes[5]!)).toBe(true)
     expect(eventReads).toBe(6)
 
     events.push({
-      type: 'user/message', seq: 7, time: 7,
+      type: 'user/message', seq: SessionSeq(7), time: 7,
       data: createUserMessage({
         content: [{ type: 'text', text: 'replacement' }], source: { kind: 'user' },
       }),
-      surfaceOp: { op: 'replace', start: 0, end: 6 },
+      surfaceOp: { op: 'replace', start: SessionSeq(0), end: SessionSeq(6) },
     })
-    nodes.splice(0, nodes.length, 7)
+    nodes.splice(0, nodes.length, SessionSeq(7))
     generation += 1
     expect(toolPairingBalancedAfter(session, nodes[0]!)).toBe(true)
     expect(eventReads).toBe(7)
@@ -328,19 +328,19 @@ describe('tool-pairing cache refresh', () => {
   it('rebuilds defensively when a same-generation surface entry count regresses', () => {
     const events: SessionEvent[] = [
       {
-        type: 'user/message', seq: 0, time: 0,
+        type: 'user/message', seq: SessionSeq(0), time: 0,
         data: createUserMessage({
           content: [], source: { kind: 'user' },
         }), surfaceOp: 'append',
       },
       {
-        type: 'user/message', seq: 1, time: 1,
+        type: 'user/message', seq: SessionSeq(1), time: 1,
         data: createUserMessage({
           content: [], source: { kind: 'user' },
         }), surfaceOp: 'append',
       },
     ]
-    const nodes: number[] = [0, 1]
+    const nodes: SessionSeqType[] = [SessionSeq(0), SessionSeq(1)]
     const session = {
       eventAt: (seq: number) => events[seq],
       surface: { nodes, replaceGeneration: 0 },
@@ -384,10 +384,10 @@ describe('tool-pairing corrupt surfaces', () => {
   })
 
   it('throws when a current surface seq has no matching event or indexes the wrong event', () => {
-    const missingSeq = 1
+    const missingSeq = SessionSeq(1)
     const missing = {
       eventAt: (seq: number) => [{
-        type: 'user/message', seq: 0, time: 0,
+        type: 'user/message', seq: SessionSeq(0), time: 0,
         data: createUserMessage({
           content: [], source: { kind: 'user' },
         }), surfaceOp: 'append',
@@ -396,10 +396,10 @@ describe('tool-pairing corrupt surfaces', () => {
     } as unknown as Session
     expect(() => toolPairingBalancedBefore(missing, missingSeq)).toThrow(/no matching session event/)
 
-    const mismatchedSeq = 0
+    const mismatchedSeq = SessionSeq(0)
     const mismatched = {
       eventAt: (seq: number) => [{
-        type: 'user/message', seq: 99, time: 0,
+        type: 'user/message', seq: SessionSeq(99), time: 0,
         data: createUserMessage({
           content: [], source: { kind: 'user' },
         }), surfaceOp: 'append',
diff --git a/packages/context/agent-instructions/tests/agent-instructions.spec.ts b/packages/context/agent-instructions/tests/agent-instructions.spec.ts
index 37e9db46a9..af270437b1 100644
--- a/packages/context/agent-instructions/tests/agent-instructions.spec.ts
+++ b/packages/context/agent-instructions/tests/agent-instructions.spec.ts
@@ -6,7 +6,7 @@ import { Context } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import * as workspaceContext from '@deepseek-ai/dsh-agent-instructions'
 import LlmRuntime, { createUserMessage, ToolCallId, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId, SESSION_FORMAT_VERSION, type SessionEvent, type UserMessage } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq, SESSION_FORMAT_VERSION, type SessionEvent, type UserMessage } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import AgentRegistry, { agentEvents, Inbox, type Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { turnBoundaryProjectionDefinition } from '@deepseek-ai/dsh-agent-loop'
@@ -190,7 +190,9 @@ async function mountFileToolsAndWorkspaceContext(ctx: Context, config: workspace
 
 function stubAgent(cwd?: string, seed: readonly SessionEvent[] = []): Agent {
   const id = SessionId('s1')
-  const session = Session.create(id, seed, cwd === undefined ? undefined : { version: SESSION_FORMAT_VERSION, id, createdAt: 0, cwd })
+  const session = Session.create(id, seed, cwd === undefined
+    ? undefined
+    : { version: SESSION_FORMAT_VERSION, id, createdAt: 0, cwd, isSeeded: false })
   return {
     ctx: new Context(),
     id: SessionId('a1'),
@@ -253,9 +255,9 @@ function baselineEvents(agent: Agent): SessionEvent[] {
     && event.data.source.baseline === true)
 }
 
-async function appendAdditionalContexts(ctx: Context, agent: Agent): Promise<number | undefined> {
+async function appendAdditionalContexts(ctx: Context, agent: Agent): Promise<SessionSeq | undefined> {
   await syncedWorkspaceContext(ctx, agent)
-  let lastSeq: number | undefined
+  let lastSeq: SessionSeq | undefined
   for (const claimed of agent.inbox.claim('next-step', 1)) {
     if (claimed.source.kind !== 'agent-instructions') continue
     const event = agent.session.append('user/message', claimed, { surfaceOp: 'append' })
@@ -3620,8 +3622,8 @@ describe('dynamic nested workspace context injection', () => {
         content: [{ type: 'text', text: 'compacted summary' }],
         source: { kind: 'plugin', plugin: 'compact' },
       }), {
-        surfaceOp: { op: 'replace', start: contextSeq, end: contextSeq },
-        sourceEventSeqs: [contextSeq],
+        surfaceOp: { op: 'replace', start: SessionSeq(contextSeq), end: SessionSeq(contextSeq) },
+        sourceEventSeqs: [SessionSeq(contextSeq)],
       })
 
       const afterCompact = await ctx.tools.execute({
diff --git a/packages/context/session-reference/src/index.ts b/packages/context/session-reference/src/index.ts
index 14ce656f94..fb7c6ca22a 100644
--- a/packages/context/session-reference/src/index.ts
+++ b/packages/context/session-reference/src/index.ts
@@ -11,6 +11,7 @@ import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { createUserMessage, freezeMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, UserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 // Type-only: the `title` projection key plus the live registry and durable
 // cache Context merges — the two projection faces discovery labels from.
@@ -229,7 +230,12 @@ export class SessionReferenceResolver extends TypertRemoteService {
     if (attached !== undefined && projections !== undefined) {
       return titleOf(projections.snapshot(attached, ['title']))
     }
-    return titleOf(this.ctx.get('sessionProjectionCache')?.cachedSnapshot(record.header, ['title']))
+    if (record.header.isSeeded) return undefined
+    return titleOf(this.ctx.get('sessionProjectionCache')?.cachedSnapshot(
+      record.header,
+      SessionLogOffset(0),
+      ['title'],
+    ))
   }
 
   /**
diff --git a/packages/context/session-reference/src/projection.ts b/packages/context/session-reference/src/projection.ts
index 83efaf5d87..06f0b83489 100644
--- a/packages/context/session-reference/src/projection.ts
+++ b/packages/context/session-reference/src/projection.ts
@@ -4,6 +4,8 @@ import { isCompactCheckpointSource } from '@deepseek-ai/dsh-compaction'
 import type { SessionSurfaceSnapshot } from '@deepseek-ai/dsh-session-query'
 import { TextRetainer } from '@deepseek-ai/dsh-output-retention'
 import { assertNever } from '@deepseek-ai/dsh-util-values'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
+import type { OptionalSessionSeq } from '@deepseek-ai/dsh-session'
 import { stringifyTagSafeJson } from './serialization.ts'
 import type { ReferencedConversationItem } from './types.ts'
 
@@ -18,7 +20,7 @@ export interface ReferencedSessionData {
   sessionId: string
   label: string
   cwd: string | null
-  capturedThroughSeq: number | null
+  capturedThroughSeq: OptionalSessionSeq
   conversation: ReferencedConversationItem[]
 }
 
@@ -79,7 +81,9 @@ export function retainReferencedSession(
     sessionId: snapshot.session.id,
     label,
     cwd: snapshot.session.cwd ?? null,
-    capturedThroughSeq: snapshot.capturedThroughSeq,
+    capturedThroughSeq: snapshot.capturedThroughSeq === null
+      ? null
+      : SessionSeq(snapshot.capturedThroughSeq),
     conversation: retained.map(({ role, text }) => ({ role, text })),
   })
   const size = (): number => Buffer.byteLength(stringifyTagSafeJson(data()), 'utf8')
diff --git a/packages/context/session-reference/src/types.ts b/packages/context/session-reference/src/types.ts
index 87c11cd4c2..47965e9528 100644
--- a/packages/context/session-reference/src/types.ts
+++ b/packages/context/session-reference/src/types.ts
@@ -7,7 +7,7 @@
 
 import type { UserMessage } from '@deepseek-ai/dsh-llm/message'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { OptionalSessionSeq, SessionId } from '@deepseek-ai/dsh-session/types'
 
 /** Durable source session, cited event seqs, and snapshot facts for prepared cross-session context. */
 export interface SessionReferenceSource {
@@ -18,7 +18,7 @@ export interface SessionReferenceSource {
   references: {
     sessionId: string
     label: string
-    capturedThroughSeq: number | null
+    capturedThroughSeq: OptionalSessionSeq
     compacted: boolean
     originalMessages: number
     retainedMessages: number
diff --git a/packages/context/session-reference/tests/session-reference.spec.ts b/packages/context/session-reference/tests/session-reference.spec.ts
index d2b2a205ba..07eb12113d 100644
--- a/packages/context/session-reference/tests/session-reference.spec.ts
+++ b/packages/context/session-reference/tests/session-reference.spec.ts
@@ -3,7 +3,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import { CompactionId, compactCheckpointSource } from '@deepseek-ai/dsh-compaction'
 import { createUserMessage, ToolCallId , createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SessionQueryEngine from '@deepseek-ai/dsh-session-query'
 import SessionTitleService from '@deepseek-ai/dsh-session-title'
@@ -55,7 +55,7 @@ async function harness(config: Config = {}): Promise<Context> {
 function withProjectionCache(ctx: Context, rows: Record<string, string | null>): void {
   ctx.provide('sessionProjectionCache', {
     cachedSnapshot: (meta: { id: SessionId }) => (
-      meta.id in rows ? { asOfSeq: 0, values: { title: rows[meta.id] } } : undefined
+      meta.id in rows ? { asOfSeq: SessionSeq(0), values: { title: rows[meta.id] } } : undefined
     ),
   })
 }
@@ -343,9 +343,15 @@ describe('session reference discovery and preparation', () => {
   it('labels a session no projection answers for by its id, still without a log read', async () => {
     const ctx = await harness()
     const target = ctx.sessions.create(SessionId('target'), { meta: { cwd: '/same' } })
-    const seeded = { id: SessionId('seeded'), createdAt: 10, cwd: '/same' }
+    const seeded = {
+      version: 0,
+      id: SessionId('seeded'),
+      createdAt: 10,
+      cwd: '/same',
+      isSeeded: true,
+    }
     // Persisted before the cache was composed: the title lives only in its log.
-    withProjectionCache(ctx, {})
+    withProjectionCache(ctx, { seeded: 'Unsafe body-free title' })
     vi.spyOn(ctx.sessionQuery, 'listSessions').mockResolvedValue([
       { header: seeded, live: false, persisted: true },
     ] as never)
diff --git a/packages/context/time-context/src/index.ts b/packages/context/time-context/src/index.ts
index 87f09e2241..02cf81d738 100644
--- a/packages/context/time-context/src/index.ts
+++ b/packages/context/time-context/src/index.ts
@@ -11,6 +11,7 @@ import { z as zod } from 'zod'
 import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { UserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-session-projection'
 import {
   deriveBrowserTimeZoneContext,
@@ -79,7 +80,7 @@ function formatDuration(elapsedMs: number): string {
 function requestMessages(agent: Agent, turn: number, proposed: readonly UserMessage[]): UserMessage[] {
   const entered: UserMessage[] = []
   for (let seq = agent.session.seq - 1; seq >= 0; seq -= 1) {
-    const event = agent.session.eventAt(seq)
+    const event = agent.session.eventAt(SessionSeq(seq))
     if (event?.type === 'turn/start' && event.data.turn === turn) {
       return [...entered.reverse(), ...proposed]
     }
diff --git a/packages/context/time-context/tests/invariant.spec.ts b/packages/context/time-context/tests/invariant.spec.ts
index c294890045..4abc2059a5 100644
--- a/packages/context/time-context/tests/invariant.spec.ts
+++ b/packages/context/time-context/tests/invariant.spec.ts
@@ -2,7 +2,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session'
 import * as TimeInvariant from '@deepseek-ai/dsh-time-context/invariant'
 import InvariantRegistry from '@deepseek-ai/dsh-invariants'
 
@@ -24,7 +24,7 @@ function event(
 ): SessionEvent<'user/message'> {
   return {
     type: 'user/message',
-    seq: 0,
+    seq: SessionSeq(0),
     time,
     data: createUserMessage({
       content: (content ?? [{ type: 'text', text }]) as ContentBlock[],
@@ -322,9 +322,9 @@ describe('time-context invariants', () => {
     expect(() => {
       ctx.sessions.create(SessionId('time-invariant-created-invalid'), {
         seed: [
-          { type: 'turn/start', seq: 0, time: SECOND, data: { turn: 1 } },
-          { type: 'step/start', seq: 1, time: SECOND, data: { turn: 1, step: 1 } },
-          { ...event(text), seq: 2, surfaceOp: 'append' },
+          { type: 'turn/start', seq: SessionSeq(0), time: SECOND, data: { turn: 1 } },
+          { type: 'step/start', seq: SessionSeq(1), time: SECOND, data: { turn: 1, step: 1 } },
+          { ...event(text), seq: SessionSeq(2), surfaceOp: 'append' },
         ],
       })
     }).toThrow(/expected turn 1\/step 1/)
@@ -345,7 +345,7 @@ describe('time-context invariants', () => {
     expect(() => { ctx.emit('session/event', preparing(1, 1), user) }).not.toThrow()
     expect(() => {
       ctx.emit('session/event', preparing(1, 1), {
-        type: 'turn/start', seq: 0, time: 0, data: { turn: 1 },
+        type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 },
       })
       ctx.emit('tools/change')
     }).not.toThrow()
diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index bf020b457a..1b8448e693 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -27,7 +27,7 @@ import {
 import { deepFreeze } from '@deepseek-ai/dsh-util-values'
 import type { Scope } from '@deepseek-ai/dsh-scope'
 import { createScope } from '@deepseek-ai/dsh-scope'
-import type { EpochHeader, RequestContext, Session, SessionId, TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session'
+import type { EpochHeader, RequestContext, Session, SessionId, SessionSeq, TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session'
 import { canonicalHeader, headerEquals } from '@deepseek-ai/dsh-session'
 import { joinContextSections, renderContextSections, renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
@@ -359,7 +359,7 @@ export class ReactLoopAgent implements Agent {
       )
       startsRequestSeries = false
       const assembler = new BlockAssembler()
-      const chunkSeqs: number[] = []
+      const chunkSeqs: SessionSeq[] = []
       try {
         const stream = preparedCall?.stream(request) ?? this.loopCtx.llm.stream(request)
         signal.throwIfAborted()
diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts
index ba784df9d1..572f2bcc7b 100644
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -24,7 +24,7 @@ import type {
 } from '@deepseek-ai/dsh-agent'
 import { errorChain, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-settings'
-import { SessionPreparation } from '@deepseek-ai/dsh-session'
+import { SessionPreparation, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
@@ -42,11 +42,11 @@ const INACTIVE_STATES: ReadonlySet<FiberState> = new Set([
 ])
 
 const turnBoundaryProjectionSchema: zod.ZodType<TurnBoundaryProjection> = zod.object({
-  openTurnStartSeq: zod.number().int().nonnegative().nullable(),
-  lastStepStartSeq: zod.number().int().nonnegative().nullable(),
+  openTurnStartSeq: zod.number().int().nonnegative().transform(SessionSeq).nullable(),
+  lastStepStartSeq: zod.number().int().nonnegative().transform(SessionSeq).nullable(),
   lastStepBoundary: zod.object({
     kind: zod.union([zod.literal('start'), zod.literal('end')]),
-    seq: zod.number().int().nonnegative(),
+    seq: zod.number().int().nonnegative().transform(SessionSeq),
   }).nullable(),
   lastTurn: zod.number().int().nonnegative(),
 })
@@ -670,6 +670,7 @@ export class AgentLoop extends Service implements AgentFactory {
     const preparation = SessionPreparation.create(this.runtime.ctx.sessions.prepare(options.sessionId, {
       ...options.seed === undefined ? {} : { seed: options.seed },
       ...options.meta === undefined ? {} : { meta: options.meta },
+      ...options.inheritedEventCount === undefined ? {} : { inheritedEventCount: options.inheritedEventCount },
     }))
     const published = this.setupAndPublish(
       ownerCtx,
diff --git a/packages/core/agent-loop/src/runtime-context.ts b/packages/core/agent-loop/src/runtime-context.ts
index e83f0dfc9d..19a3fd0110 100644
--- a/packages/core/agent-loop/src/runtime-context.ts
+++ b/packages/core/agent-loop/src/runtime-context.ts
@@ -6,7 +6,7 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContextSnapshotSection } from '@deepseek-ai/dsh-llm'
 import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
-import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session'
+import { isReplacementSurfaceEvent, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Context } from '@deepseek-ai/cordis'
 
 const SOURCE = '@deepseek-ai/dsh-system-prompt'
@@ -24,7 +24,7 @@ function textOf(message: UserMessage): string | undefined {
 /** Tracks the last retained runtime-context snapshot without owning its commit. */
 export class RuntimeContextProjection {
   /** `undefined` means no snapshot ever existed; `null` means none is retained. */
-  private retained: { seq: number; text: string | undefined } | null | undefined
+  private retained: { seq: SessionSeq; text: string | undefined } | null | undefined
 
   /**
    * Restore projection state once, then follow authoritative session events.
@@ -34,7 +34,7 @@ export class RuntimeContextProjection {
   constructor(ctx: Context, session: Session) {
     const surface = new Set(session.surface.nodes)
     for (let index = session.seq - 1; index >= 0; index -= 1) {
-      const event = session.eventAt(index)
+      const event = session.eventAt(SessionSeq(index))
       if (event?.type !== 'user/message' || !isOwned(event.data)) continue
       this.retained ??= null
       if (surface.has(event.seq)) {
diff --git a/packages/core/agent-loop/src/tool-calls.ts b/packages/core/agent-loop/src/tool-calls.ts
index bbf616f364..e6aca31f56 100644
--- a/packages/core/agent-loop/src/tool-calls.ts
+++ b/packages/core/agent-loop/src/tool-calls.ts
@@ -13,7 +13,7 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { createToolResultMessage, type ToolCallBlock } from '@deepseek-ai/dsh-llm'
-import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
+import type { Session, SessionSeq, UserMessage } from '@deepseek-ai/dsh-session'
 import { TOOL_ABORTED_BEFORE_DISPATCH, TOOL_RUNTIME_SCHEDULER, type ToolExecutionInput, type ToolExecutionMode, type ToolExecutionResult, type ToolRunContext } from '@deepseek-ai/dsh-tools'
 import { assertNever } from '@deepseek-ai/dsh-util-values'
 
@@ -132,7 +132,7 @@ async function runGroup(
   const { maxParallelToolCalls } = ctx.agentLoop.config
   const slots: (Slot | undefined)[] = group.map(() => undefined)
   // Started slots retain their `tool/call` seq so the result can cite it.
-  const callSeqs: number[] = group.map(() => -1)
+  const callSeqs: Array<SessionSeq | undefined> = group.map(() => undefined)
   let nextToStart = 0
   let committed = 0
   let started = 0
@@ -260,7 +260,7 @@ function appendSkippedToolCall(session: Session, turn: number, step: number, blo
 }
 
 /** Append a started call and return the event seq that its result must cite. */
-function appendToolCall(session: Session, turn: number, step: number, block: ToolCallBlock): number {
+function appendToolCall(session: Session, turn: number, step: number, block: ToolCallBlock): SessionSeq {
   const event = session.append('tool/call', { turn, step, callId: block.id, name: block.name, arguments: block.arguments })
   return event.seq
 }
@@ -272,7 +272,7 @@ function appendToolResult(
   step: number,
   block: ToolCallBlock,
   result: ToolExecutionResult,
-  callSeq: number,
+  callSeq: SessionSeq,
 ): void {
   const message = createToolResultMessage({
     callId: block.id,
diff --git a/packages/core/agent-loop/tests/resume.spec.ts b/packages/core/agent-loop/tests/resume.spec.ts
index 320d5ce81f..457de1a306 100644
--- a/packages/core/agent-loop/tests/resume.spec.ts
+++ b/packages/core/agent-loop/tests/resume.spec.ts
@@ -5,8 +5,8 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import LlmRuntime from '@deepseek-ai/dsh-llm'
-import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionId, SessionPreparation } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionId, SessionLogOffset, SessionPreparation, SessionSeq } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
@@ -45,8 +45,8 @@ async function persistSession(sessionId: SessionId): Promise<string> {
   // balanced completed turn is the smallest resumable log and avoids running
   // the model merely to construct this lifecycle fixture.
   const seed: SessionEvent[] = [
-    { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-    { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+    { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
   const session = ctx.sessions.create(sessionId, { seed })
   await ctx.sessions.flush(session)
@@ -57,11 +57,16 @@ async function persistSession(sessionId: SessionId): Promise<string> {
 /** Build a detached preparation for lifecycle-race test doubles. */
 function preparationFromSnapshot(
   ctx: Context,
-  snapshot: { meta: SessionHeader; events: readonly SessionEvent[] },
+  snapshot: {
+    meta: SessionHeader
+    inheritedEventCount: SessionLogOffsetType
+    events: readonly SessionEvent[]
+  },
 ): SessionPreparation {
   return SessionPreparation.create(ctx.sessions.prepare(snapshot.meta.id, {
     seed: structuredClone(snapshot.events) as SessionEvent[],
     meta: structuredClone(snapshot.meta),
+    inheritedEventCount: snapshot.inheritedEventCount,
     seedSource: 'persistence',
   }))
 }
@@ -98,6 +103,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
       version: SESSION_FORMAT_VERSION,
       id: sessionId,
       createdAt: 1,
+      isSeeded: false,
     })
     await first.ctx.sessionPersistence.append(sessionId, [
       {
@@ -565,27 +571,26 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
   })
 
   it('resume of a forked session preserves the lineage, seed boundary, and delegation depth in the header', async () => {
-    // Lifecycle 1: persist a FORKED session (carries parentSession + seedLength
-    // in its header) by creating it with a complete-turn seed — the write path
+    // Lifecycle 1: persist a FORKED session (carries parentSession + isSeeded
+    // in its header and an exact Session-owned cut) with a complete-turn seed — the write path
     // materializes the fork (header + seed) on disk.
     const seed: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const forked = ctx1.sessions.create(SessionId('forked-sess'), {
       seed,
-      meta: { cwd: '/w', parentSession: SessionId('parent-sess'), seedLength: seed.length, delegationDepth: 1 },
+      inheritedEventCount: SessionLogOffset(seed.length),
+      meta: { cwd: '/w', parentSession: SessionId('parent-sess'), isSeeded: true, delegationDepth: 1 },
     })
     await ctx1.sessions.flush(forked)
     await ctx1.fiber.dispose()
 
-    // Lifecycle 2: resume it; the parentSession + seedLength header survives the
-    // round-trip (exercises resume's parentSession- and seedLength-present
-    // branches). seedLength must come from the PERSISTED header, not from the
-    // resume seed length (which is the whole stored log, not the original
-    // boundary).
+    // Lifecycle 2: resume it; parentSession, isSeeded, and the exact cut survive
+    // the round-trip. The inherited count must come from persisted storage,
+    // not the resume seed length (the whole stored log).
     const adapter2 = new MockAdapter([textResponse('b')])
     const ctx2 = new Context()
     await ctx2.plugin(LlmRuntime)
@@ -600,7 +605,8 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('forked-sess') })).agent
     expect(a2.session.header.parentSession).toBe('parent-sess')
     expect(a2.session.header.cwd).toBe('/w')
-    expect(a2.session.header.seedLength).toBe(seed.length)
+    expect(a2.session.header.isSeeded).toBe(true)
+    expect(a2.session.inheritedEventCount).toBe(seed.length)
     // The recursion budget survives resume — a dropped depth would let a
     // resumed child delegate as if it were top-level.
     expect(a2.session.header.delegationDepth).toBe(1)
diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts
index fccfdcba64..c5d50b222a 100644
--- a/packages/core/agent/src/inbox.ts
+++ b/packages/core/agent/src/inbox.ts
@@ -29,7 +29,7 @@ export class Inbox {
     private readonly session: Session,
     private readonly notifications: InboxNotifications,
   ) {
-    for (const event of session.snapshotEvents(session.header.seedLength ?? 0)) {
+    for (const event of session.ownEvents()) {
       if (event.type !== 'agent/inbox/spliced') continue
       try {
         this.apply(event.data)
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index ef7371231b..6e3db1edb0 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -11,7 +11,7 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 import { isPromise } from 'node:util/types'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { Agent } from './types.ts'
 import type { AgentOptions } from './runtime-types.ts'
 
@@ -73,9 +73,9 @@ export interface CreateAgentOptions {
   readonly sessionId: SessionId
   /**
    * Session creation metadata: validated absolute `cwd`, `parentSession`
-   * fork lineage, the `seedLength` seed boundary, the coarse `origin`
+   * fork lineage, the `isSeeded` fork marker, the coarse `origin`
    * classification, and the `delegationDepth` recursion budget. Mirrors the
-   * `cwd`/`parentSession`/`seedLength`/`origin`/`delegationDepth` fields of
+   * `cwd`/`parentSession`/`isSeeded`/`origin`/`delegationDepth` fields of
    * {@link CreateSessionOptions.meta} in dsh-session (the internal-only
    * `createdAt`, used when reconstructing a persisted session, is deliberately
    * excluded — a factory caller never sets it). This is durable session data,
@@ -85,11 +85,13 @@ export interface CreateAgentOptions {
   readonly meta?: {
     readonly cwd?: string
     readonly parentSession?: SessionId
-    readonly seedLength?: number
+    readonly isSeeded?: boolean
     readonly origin?: 'subagent'
     readonly delegationDepth?: number
     readonly agentPreset?: string
   }
+  /** Exact fork-inherited prefix length when the session metadata sets `isSeeded`. */
+  readonly inheritedEventCount?: SessionLogOffset
   /**
    * Initial replay/fork history. A fork supplies a balanced completed-turn
    * prefix of the parent's log. The complete seed must be contiguous from seq
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index e570ccf7e7..c7b82e243e 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -5,7 +5,7 @@
  */
 
 import type { UserMessage } from '@deepseek-ai/dsh-llm/types'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { OptionalSessionSeq, SessionId, SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { TypertContext, TypertLookup } from '@deepseek-ai/dsh-typert-protocol'
 
 /** Public live-agent handle; the runtime face augments its live capabilities. */
@@ -39,11 +39,11 @@ export type InboxTarget = 'next-turn' | 'next-step'
  */
 export interface TurnBoundaryProjection {
   /** Seq of the open turn's `turn/start`, or null between turns. */
-  readonly openTurnStartSeq: number | null
+  readonly openTurnStartSeq: OptionalSessionSeq
   /** Seq of the latest `step/start` event, or null before the first step. */
-  readonly lastStepStartSeq: number | null
+  readonly lastStepStartSeq: OptionalSessionSeq
   /** The latest step boundary (`step/start` or `step/end`) and its seq, or null before the first step boundary. */
-  readonly lastStepBoundary: { readonly kind: 'start' | 'end'; readonly seq: number } | null
+  readonly lastStepBoundary: { readonly kind: 'start' | 'end'; readonly seq: SessionSeq } | null
   /** Turn number of the latest `turn/start`; 0 before the first turn. */
   readonly lastTurn: number
 }
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 5475521b65..71c2828f9c 100644
--- 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: fde5d3846ef36dff56b7656068603ae9dd148fcf
-README.zh.md: 78c52323fe6a541b2d73b55195aaf7b4274b1411
+README.md: f5cf910854203021a619cc786dfd13705927ffc1
+README.zh.md: 385d7fd63a6e4dec9c23c9d38a352942d7dbc7f9
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index fde5d3846e..f5cf910854 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -53,10 +53,14 @@ Surface events (`user/message`, `assistant/message`, `tool/result`) must declare
 
 `session.seq` reads the current log length without materializing an array, and `session.eventAt(seq)` reads one accepted, deeply frozen event by sequence number. `session.snapshotEvents(fromSeq?, toSeqExclusive?)` materializes a frozen, stable snapshot of a half-open range; a complete current snapshot is cached until the next append. Callers that only need a length or one event use `seq` or `eventAt()`.
 
+Session log positions use two numeric types. `SessionSeq` identifies an existing event or inclusive event watermark; `SessionLogOffset` identifies a gap, prefix length, or read boundary and may equal the event count. `SessionSeqCursor` adds the `-1` “no event yet” value, while `OptionalSessionSeq` uses `null` when absence is data. The constructors validate non-negative safe integers, and the brands disappear at runtime, so durable JSON and wire values remain ordinary numbers.
+
 ### Fork a session
 
 `ctx.sessions.fork(source, boundary?, childSessionId?)` selects source events through an inclusive `boundary` seq (default: the current last event), requires the prefix to end outside an open turn, and creates a live child session with lineage metadata. A tool-time delegation that must branch mid-turn clips to a completed prefix instead.
 
+The logical `SessionHeader.isSeeded` field reports whether fork history exists without exposing a positional integer. `Session.inheritedEventCount` retains the exact checked `SessionLogOffset`; `ownEvents()` returns events at and after that cut, and `isOwnSeq(seq)` accepts only an existing child-owned position. A low-level seeded constructor must supply an explicit `seed` and `inheritedEventCount` because the constructor seed can contain child-owned setup events after the inherited prefix.
+
 ### Flush durable state
 
 `ctx.sessions.flush(session)` dispatches the awaited durability checkpoint: every persistence listener flushes and the call settles after all of them. A producer that needs an immediate durability barrier awaits it instead of assuming the write-behind drained.
@@ -94,7 +98,7 @@ The package is built on event sourcing: a `Session` is an append-only log of typ
 
 ### Append validation
 
-Every append uses the shared iterative `snapshotJsonValue()` pass, which reads, validates, and copies each nested value once, so a stateful getter cannot supply one value to validation and another to storage. Non-lossless-JSON payloads (BigInt, cycles, sparse arrays, `-0`, exotic prototypes) are rejected at the append site, before any backend flush. Surface events additionally validate marker shape, cited source-event seqs, and complete shadowed-node coverage for replacements.
+Every append uses the shared iterative `snapshotJsonValue()` pass, which reads, validates, and copies each nested value once, so a stateful getter cannot supply one value to validation and another to storage. Non-lossless-JSON payloads (BigInt, cycles, sparse arrays, `-0`, exotic prototypes) are rejected at the append site, before any backend flush. The append path constructs each `SessionSeq`; surface events additionally validate marker shape, cited source-event sequences, and complete shadowed-node coverage for replacements.
 
 ### Derived history
 
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index 78c52323fe..385d7fd63a 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -53,10 +53,14 @@ session.deriveMessages()         // the derived model history
 
 `session.seq` 无需物化数组即可读取当前日志长度，`session.eventAt(seq)` 按序列号读取单个已接受且深度冻结的事件。`session.snapshotEvents(fromSeq?, toSeqExclusive?)` 会物化半开区间的冻结稳定快照；当前完整快照会缓存到下一次追加。只需要长度或单个事件的调用方使用 `seq` 或 `eventAt()`。
 
+会话日志位置使用两种数字类型。`SessionSeq` 标识已有事件或包含端点的事件水位；`SessionLogOffset` 标识间隙、前缀长度或读取边界，并且可以等于事件数量。`SessionSeqCursor` 添加 `-1` 这个“尚无事件”值，`OptionalSessionSeq` 则在缺失本身属于数据时使用 `null`。构造函数会校验非负安全整数，品牌在运行时会被擦除，因此持久 JSON 与 wire 值仍是普通数字。
+
 ### 派生会话的 fork
 
 `ctx.sessions.fork(source, boundary?, childSessionId?)` 选取截至 `boundary` 事件序号（含该事件）的源事件（默认：当前最后一个事件），要求所选前缀结束时没有开放轮次，再创建带谱系元数据的实时子会话。必须在轮次中途分支的工具时委派会裁剪到已完成前缀。
 
+逻辑 `SessionHeader.isSeeded` 字段报告是否存在 fork 历史，而不公开位置整数。`Session.inheritedEventCount` 保留经过校验的精确 `SessionLogOffset`；`ownEvents()` 返回从该切点开始的事件，`isOwnSeq(seq)` 只接受已存在且由 child 拥有的位置。底层带 seed 构造必须显式提供 `seed` 与 `inheritedEventCount`，因为构造 seed 可以在继承前缀之后包含 child 自有的设置事件。
+
 ### 刷新持久状态
 
 `ctx.sessions.flush(session)` 分发需等待完成的持久性检查点：每个持久化监听器都会刷新，调用在所有监听器结算后完成。需要立即持久性屏障的生产方应等待它，而不是假定写后刷新已完成。
@@ -94,7 +98,7 @@ session.deriveMessages()         // the derived model history
 
 ### 追加校验
 
-每次追加都会使用共享的迭代式 `snapshotJsonValue()` 流程，对每个嵌套值只读取、校验并复制一次，因此有状态的 getter 无法给校验提供一个值、给存储提供另一个值。非无损 JSON 载荷（BigInt、循环、稀疏数组、`-0`、特殊原型）会在追加位置被拒绝，先于任何后端刷新。表层事件还会校验标记形态、被引用的源事件 seq，以及替换的完整遮蔽节点覆盖。
+每次追加都会使用共享的迭代式 `snapshotJsonValue()` 流程，对每个嵌套值只读取、校验并复制一次，因此有状态的 getter 无法给校验提供一个值、给存储提供另一个值。非无损 JSON 载荷（BigInt、循环、稀疏数组、`-0`、特殊原型）会在追加位置被拒绝，先于任何后端刷新。追加路径会构造每个 `SessionSeq`；surface 事件还会校验标记形态、被引用的源事件序号，以及替换的完整遮蔽节点覆盖。
 
 ### 派生历史
 
diff --git a/packages/core/session/src/chunk-rows.ts b/packages/core/session/src/chunk-rows.ts
index 0feda80880..8289b59b5a 100644
--- a/packages/core/session/src/chunk-rows.ts
+++ b/packages/core/session/src/chunk-rows.ts
@@ -22,7 +22,8 @@
 import { brandString } from '@deepseek-ai/dsh-brand'
 import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand'
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
-import type { SessionEvent } from './types.ts'
+import { SessionSeq } from './types.ts'
+import type { SessionEvent, SessionSeq as SessionSeqType } from './types.ts'
 
 /** The chunk kinds that may pack; block boundaries, usage, and finish chunks always stay one event per line. */
 type DeltaKind = 'text-delta' | 'reasoning-delta' | 'tool-call-delta'
@@ -64,9 +65,9 @@ interface ToolCallRunData extends RunDataBase {
  * {@link TextRunData} payload, tool-call rows carry {@link ToolCallRunData}.
  */
 export type ChunkRow =
-  | { type: 'text-chunks'; seq0: number; time0: number; data: TextRunData }
-  | { type: 'reasoning-chunks'; seq0: number; time0: number; data: TextRunData }
-  | { type: 'tool-call-chunks'; seq0: number; time0: number; data: ToolCallRunData }
+  | { type: 'text-chunks'; seq0: SessionSeqType; time0: number; data: TextRunData }
+  | { type: 'reasoning-chunks'; seq0: SessionSeqType; time0: number; data: TextRunData }
+  | { type: 'tool-call-chunks'; seq0: SessionSeqType; time0: number; data: ToolCallRunData }
 
 /** One durable log line's JSON value: a session event verbatim, or a packed chunk row. */
 export type StorageRecord = SessionEvent | ChunkRow
@@ -118,7 +119,8 @@ function hasExactKeys(value: object, keys: readonly string[]): boolean {
 function classify(event: SessionEvent): DeltaKind | undefined {
   if (event.type !== 'assistant/chunk') return undefined
   if (!hasExactKeys(event, ['type', 'seq', 'time', 'data'])) return undefined
-  if (!Number.isSafeInteger(event.seq) || event.seq < 0 || !Number.isSafeInteger(event.time)) return undefined
+  if (!Number.isSafeInteger(event.seq) || event.seq < 0 || Object.is(event.seq, -0)
+    || !Number.isSafeInteger(event.time)) return undefined
   const data: unknown = event.data
   if (!isRecord(data) || !hasExactKeys(data, ['turn', 'step', 'chunk'])) return undefined
   if (typeof data.turn !== 'number' || typeof data.step !== 'number') return undefined
@@ -271,7 +273,7 @@ function validateRow(value: Record<string, unknown>, tag: ChunkRow['type']): Chu
   if (!hasExactKeys(value, ['type', 'seq0', 'time0', 'data'])) {
     malformed(tag, 'envelope must be exactly {type, seq0, time0, data}')
   }
-  if (!Number.isSafeInteger(value.seq0) || (value.seq0 as number) < 0) {
+  if (!Number.isSafeInteger(value.seq0) || (value.seq0 as number) < 0 || Object.is(value.seq0, -0)) {
     malformed(tag, 'seq0 must be a non-negative safe integer')
   }
   if (!Number.isSafeInteger(value.time0)) {
@@ -308,6 +310,7 @@ function validateRow(value: Record<string, unknown>, tag: ChunkRow['type']): Chu
     time += gap
     if (!Number.isSafeInteger(time)) malformed(tag, 'member times must stay safe integers')
   }
+  SessionSeq(value.seq0 as number)
   return value as unknown as ChunkRow
 }
 
@@ -343,7 +346,7 @@ function expandRow(row: ChunkRow): SessionEvent[] {
     }
     events.push({
       type: 'assistant/chunk',
-      seq: row.seq0 + k,
+      seq: SessionSeq(row.seq0 + k),
       time,
       data: { turn: row.data.turn, step: row.data.step, chunk },
     })
@@ -355,7 +358,8 @@ function expandRow(row: ChunkRow): SessionEvent[] {
  * Decode one parsed JSONL line value into the session event(s) it stores.
  * Chunk-row-tagged values validate and expand (a malformed row throws — it is
  * corrupt storage, and treating it as an event would silently drop a whole
- * run); every other value passes through as a single event, unvalidated.
+ * run); every other value passes through as a single event after admitting a
+ * numeric `seq` through the Session-sequence constructor.
  *
  * @param value - one line's `JSON.parse` result.
  * @returns the stored events, in log order.
@@ -364,7 +368,8 @@ export function decodeStorageRecord(value: unknown): SessionEvent[] {
   if (!isRecord(value)) return [value as SessionEvent]
   const tag = value.type
   if (tag !== 'text-chunks' && tag !== 'reasoning-chunks' && tag !== 'tool-call-chunks') {
-    return [value as SessionEvent]
+    if (typeof value.seq === 'number') SessionSeq(value.seq)
+    return [value as unknown as SessionEvent]
   }
   return expandRow(validateRow(value, tag))
 }
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index bf08a17535..c55cc5fb6a 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -13,7 +13,7 @@ import { deepFreeze, snapshotJsonValue } from '@deepseek-ai/dsh-util-values'
 import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { Message } from '@deepseek-ai/dsh-llm'
-import { SESSION_FORMAT_VERSION } from './types.ts'
+import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from './types.ts'
 import type { TypertLookup } from '@deepseek-ai/dsh-typert-protocol'
 import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { deriveEventMessage, SurfaceManager } from './surface.ts'
@@ -96,6 +96,9 @@ function validateSessionHeader(id: SessionId, input: unknown): SessionHeader {
     throw new Error('session header is not a plain JSON record')
   }
   const record = input as Record<string, unknown>
+  if (Object.hasOwn(record, 'seedLength')) {
+    throw new Error('session header has invalid field "seedLength"')
+  }
   if (record.version !== SESSION_FORMAT_VERSION) {
     throw new Error(`session header version must be ${SESSION_FORMAT_VERSION}, got ${String(record.version)}`)
   }
@@ -116,9 +119,8 @@ function validateSessionHeader(id: SessionId, input: unknown): SessionHeader {
   if (record.parentSession !== undefined && typeof record.parentSession !== 'string') {
     throw new Error('session header parentSession must be a string')
   }
-  if (record.seedLength !== undefined
-    && (typeof record.seedLength !== 'number' || !Number.isSafeInteger(record.seedLength) || record.seedLength < 0)) {
-    throw new Error('session header seedLength must be a non-negative safe integer')
+  if (typeof record.isSeeded !== 'boolean') {
+    throw new Error('session header isSeeded must be a boolean')
   }
   if (record.origin !== undefined && record.origin !== 'subagent') {
     throw new Error('session header origin must be "subagent"')
@@ -147,7 +149,7 @@ function validateRestoredSessionHeader(id: SessionId, input: unknown): SessionHe
 /** 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() }
+    ? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now(), isSeeded: false }
     : source
   const snapshot = snapshotJsonValue(input)
   if (snapshot === undefined) throw new Error('session header is not losslessly JSON-serializable')
@@ -231,7 +233,7 @@ function assertSessionEventEnvelope(value: Record<string, unknown>, index: numbe
   const seq = event['seq']
   const time = event['time']
   if (typeof type !== 'string'
-    || typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0
+    || typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0 || Object.is(seq, -0)
     || typeof time !== 'number' || !Number.isSafeInteger(time)
     || event['data'] === undefined
     || (event['ignorable'] !== undefined && event['ignorable'] !== true)) {
@@ -432,7 +434,7 @@ export class Session {
 
   /**
    * Detached, deep-frozen creation metadata (format version, cwd, lineage,
-   * seed boundary). Supplied by the store via `ctx.sessions.create()`. When a
+   * and whether fork history exists). Supplied by the store via `ctx.sessions.create()`. When a
    * `Session` is created without a store-owned header, a minimal header is
    * synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
    * `session.header` is always present. Kept out of the event log — it is a
@@ -440,6 +442,9 @@ export class Session {
    */
   readonly header: SessionHeader
 
+  /** Number of leading events inherited from this Session's fork parent. */
+  readonly inheritedEventCount: SessionLogOffset
+
   /** The session identity, derived from its durable header's single copy. */
   get id(): SessionId {
     return this.header.id
@@ -451,9 +456,9 @@ export class Session {
    * construction — replay, fork, or resume — and were never published on the
    * `session/event` firehose (constructor seeds do not emit), so consumers
    * that replay the log as a publication substitute (telemetry adoption)
-   * start here. Distinct from `header.seedLength`, the DURABLE fork-lineage
-   * boundary: a resumed session's constructor seed is its full stored log,
-   * while its header keeps the original fork value — this field is the
+   * start here. Distinct from {@link inheritedEventCount}, the DURABLE
+   * fork-lineage cut: a resumed session's constructor seed is its full stored
+   * log, while the inherited count keeps the original fork value — this field is the
    * in-process construction fact.
    *
    * Not persisted itself: a seeded session projects it into the log as the
@@ -467,7 +472,7 @@ export class Session {
    * store attaches and therefore does not publish either. Otherwise this seq
    * holds an ordinary published write.
    */
-  readonly firstLiveSeq: number
+  readonly firstLiveSeq: SessionLogOffset
 
   /**
    * Create a detached session by validating and snapshotting borrowed seed
@@ -475,10 +480,16 @@ export class Session {
    * @param id - session identity.
    * @param seed - optional borrowed replay or fork events.
    * @param header - optional borrowed storage metadata.
+   * @param inheritedEventCount - exact fork-inherited prefix length for a seeded header.
    * @returns a detached session.
    */
-  static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session {
-    return new Session(id, seed, header)
+  static create(
+    id: SessionId,
+    seed?: readonly SessionEvent[],
+    header?: SessionHeader,
+    inheritedEventCount?: SessionLogOffset,
+  ): Session {
+    return new Session(id, seed, header, 'snapshot', inheritedEventCount)
   }
 
   /**
@@ -488,10 +499,16 @@ export class Session {
    * @param id - restored session identity.
    * @param seed - fresh detached events whose ownership is transferred.
    * @param header - fresh detached metadata whose ownership is transferred.
+   * @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
    * @returns a restored detached session.
    */
-  static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session {
-    return new Session(id, seed, header, 'restore')
+  static fromRestore(
+    id: SessionId,
+    seed: readonly SessionEvent[],
+    header: SessionHeader,
+    inheritedEventCount: SessionLogOffset,
+  ): Session {
+    return new Session(id, seed, header, 'restore', inheritedEventCount)
   }
 
   private constructor(
@@ -499,6 +516,7 @@ export class Session {
     seed?: readonly SessionEvent[],
     header?: SessionHeader,
     mode: 'snapshot' | 'restore' = 'snapshot',
+    suppliedInheritedEventCount?: SessionLogOffset,
   ) {
     const restoredHeader = mode === 'restore'
       ? validateRestoredSessionHeader(id, header)
@@ -534,8 +552,22 @@ export class Session {
         this.log.push(mode === 'restore' ? freezeRestoredObject(snapshot) : deepFreeze(snapshot))
       }
     }
-    this.firstLiveSeq = this.log.length
+    this.firstLiveSeq = SessionLogOffset(this.log.length)
     this.header = restoredHeader ?? snapshotSessionHeader(id, header)
+    if (this.header.isSeeded && seed === undefined) {
+      throw new Error('seeded session requires an explicit constructor seed')
+    }
+    if (this.header.isSeeded && suppliedInheritedEventCount === undefined) {
+      throw new Error('seeded session requires an inherited event count')
+    }
+    const inheritedEventCount = SessionLogOffset(suppliedInheritedEventCount ?? 0)
+    if (!this.header.isSeeded && inheritedEventCount !== 0) {
+      throw new Error('unseeded session inherited event count must be 0')
+    }
+    if (inheritedEventCount > this.log.length) {
+      throw new Error('session inherited event count exceeds its event log')
+    }
+    this.inheritedEventCount = inheritedEventCount
     // Appended here so the marker is already in `events` when a backend
     // captures the creation seed: no load-time write. Re-marking is skipped
     // because a cold session is resumed on first touch, so repeatedly opening
@@ -553,7 +585,7 @@ export class Session {
    * @param seq - event sequence number.
    * @returns the accepted event, or undefined when the log does not contain it.
    */
-  eventAt(seq: number): SessionEvent | undefined {
+  eventAt(seq: SessionSeq): SessionEvent | undefined {
     return this.log[seq]
   }
 
@@ -565,7 +597,10 @@ export class Session {
    * @param toSeqExclusive - non-negative exclusive sequence number; defaults to the current end.
    * @returns a frozen array of the selected deeply frozen events.
    */
-  snapshotEvents(fromSeq: number = 0, toSeqExclusive: number = this.log.length): readonly SessionEvent[] {
+  snapshotEvents(
+    fromSeq: SessionLogOffset = SessionLogOffset(0),
+    toSeqExclusive: SessionLogOffset = this.seq,
+  ): readonly SessionEvent[] {
     if (fromSeq === 0 && toSeqExclusive === this.log.length) {
       this.eventsSnapshot ??= Object.freeze([...this.log])
       return this.eventsSnapshot
@@ -573,9 +608,26 @@ export class Session {
     return Object.freeze(this.log.slice(fromSeq, toSeqExclusive))
   }
 
+  /**
+   * Return this Session's events after its fork-inherited prefix.
+   * @returns a fresh array containing child-owned events in log order.
+   */
+  ownEvents(): readonly SessionEvent[] {
+    return this.snapshotEvents(this.inheritedEventCount)
+  }
+
+  /**
+   * Whether one existing event position is outside the fork-inherited prefix.
+   * @param seq - event position in this Session.
+   * @returns true when the event belongs to this Session rather than its parent.
+   */
+  isOwnSeq(seq: SessionSeq): boolean {
+    return seq >= this.inheritedEventCount && seq < this.seq
+  }
+
   /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
-  get seq(): number {
-    return this.log.length
+  get seq(): SessionLogOffset {
+    return SessionLogOffset(this.log.length)
   }
 
   /**
@@ -638,7 +690,7 @@ export class Session {
     }
     const event = deepFreeze({
       type,
-      seq: this.log.length,
+      seq: SessionSeq(this.log.length),
       time: Date.now(),
       data: dataSnapshot,
       ...(surfaceMetadataSnapshot as { surfaceOp?: unknown; sourceEventSeqs?: unknown }),
@@ -882,7 +934,7 @@ export class SessionStore extends Service {
     }
     if (this.store.has(sessionId)) throw new Error(`session "${sessionId}" already exists`)
     if (options?.seedSource === 'persistence') {
-      return Session.fromRestore(sessionId, options.seed, options.meta)
+      return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount)
     }
     const seed = options?.seed
     const meta = options?.meta
@@ -892,12 +944,12 @@ export class SessionStore extends Service {
       createdAt: meta?.createdAt ?? Date.now(),
       ...meta?.cwd === undefined ? {} : { cwd: meta.cwd },
       ...meta?.parentSession === undefined ? {} : { parentSession: meta.parentSession },
-      ...meta?.seedLength === undefined ? {} : { seedLength: meta.seedLength },
+      isSeeded: meta?.isSeeded ?? false,
       ...meta?.origin === undefined ? {} : { origin: meta.origin },
       ...meta?.delegationDepth === undefined ? {} : { delegationDepth: meta.delegationDepth },
       ...meta?.agentPreset === undefined ? {} : { agentPreset: meta.agentPreset },
     }
-    return Session.create(sessionId, seed, header)
+    return Session.create(sessionId, seed, header, options?.inheritedEventCount)
   }
 
   /**
@@ -1090,7 +1142,7 @@ export class SessionStore extends Service {
    *   `SessionStore`'s id policy.
    * @returns The created live child session.
    */
-  fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session {
+  fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session {
     if (childSessionId !== undefined && this.get(childSessionId) !== undefined) {
       throw new SessionForkError(`session "${childSessionId}" already exists`, 'SESSION_ALREADY_EXISTS')
     }
@@ -1098,17 +1150,18 @@ export class SessionStore extends Service {
     const seed = this._forkSeed(liveSource, boundary)
     return this.create(childSessionId, {
       seed,
+      inheritedEventCount: SessionLogOffset(seed.length),
       meta: {
         ...liveSource.header.cwd !== undefined ? { cwd: liveSource.header.cwd } : {},
         parentSession: liveSource.id,
-        seedLength: seed.length,
+        isSeeded: true,
       },
     })
   }
 
-  private _forkSeed(session: Session, requestedBoundary: number | undefined): readonly SessionEvent[] {
-    const lastEvent = session.eventAt(session.seq - 1)
-    let boundary: number
+  private _forkSeed(session: Session, requestedBoundary: SessionSeq | undefined): readonly SessionEvent[] {
+    const lastEvent = session.snapshotEvents().at(-1)
+    let boundary: SessionSeq
     if (requestedBoundary !== undefined) {
       boundary = requestedBoundary
     } else {
@@ -1136,7 +1189,7 @@ export class SessionStore extends Service {
         'INVALID_BOUNDARY',
       )
     }
-    const events = session.snapshotEvents(0, boundary + 1)
+    const events = session.snapshotEvents(SessionLogOffset(0), SessionLogOffset(boundary + 1))
     const lastTurnBoundary = events
       .findLast(event => event.type === 'turn/start' || event.type === 'turn/end')
     if (lastTurnBoundary?.type === 'turn/start') {
diff --git a/packages/core/session/src/invariant.ts b/packages/core/session/src/invariant.ts
index ca95319afe..e479835d3f 100644
--- a/packages/core/session/src/invariant.ts
+++ b/packages/core/session/src/invariant.ts
@@ -8,7 +8,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type { ToolCallId } from '@deepseek-ai/dsh-llm'
 import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionSeqCursor } from '@deepseek-ai/dsh-session'
 import { assertNever } from '@deepseek-ai/dsh-util-values'
 import { TOOL_NOT_STARTED } from './repair.ts'
 
@@ -21,7 +21,7 @@ export const inject = ['invariants']
 
 /** Per-session bookkeeping for relational log checks. */
 interface SessionTrace {
-  lastSeq: number
+  lastSeq: SessionSeqCursor
   openTurn: number | null
   openStep: number | null
   nextTurn: number
diff --git a/packages/core/session/src/repair.ts b/packages/core/session/src/repair.ts
index d009ceb3f5..e78187df6f 100644
--- a/packages/core/session/src/repair.ts
+++ b/packages/core/session/src/repair.ts
@@ -8,7 +8,8 @@
 import { brandString } from '@deepseek-ai/dsh-brand'
 import type { MessageId, ToolCallId, ToolResultMessage } from '@deepseek-ai/dsh-llm'
 import { deepFreeze } from '@deepseek-ai/dsh-util-values'
-import type { SessionEvent } from './types.ts'
+import { SessionSeq } from './types.ts'
+import type { SessionEvent, SessionSeq as SessionSeqType } from './types.ts'
 
 /** Recovery code for an assistant tool request that never reached a recorded call start. */
 export const TOOL_NOT_STARTED = 'TOOL_NOT_STARTED'
@@ -30,7 +31,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   let openStep: number | null = null
   // Reset at each turn boundary so earlier calls cannot leak into tail repair.
   // Assistant blocks register calls; later `tool/call` events add their seqs to `sourceEventSeqs`.
-  const pendingCalls = new Map<ToolCallId, { step: number; callSeq?: number }>()
+  const pendingCalls = new Map<ToolCallId, { step: number; callSeq?: SessionSeqType }>()
   for (const event of events) {
     switch (event.type) {
       case 'turn/start':
@@ -109,7 +110,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
     })
     closers.push({
       type: 'tool/result',
-      seq: seq++,
+      seq: SessionSeq(seq++),
       time,
       data: {
         turn: openTurn,
@@ -127,8 +128,8 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   // Close an open step next — a turn/end while a step is open is an invariant
   // violation, so the step's boundary must be synthesized before the turn's.
   if (openStep !== null) {
-    closers.push({ type: 'step/end', seq: seq++, time, data: { turn: openTurn, step: openStep } })
+    closers.push({ type: 'step/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, step: openStep } })
   }
-  closers.push({ type: 'turn/end', seq: seq++, time, data: { turn: openTurn, reason: { kind: 'interrupted' } } })
+  closers.push({ type: 'turn/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, reason: { kind: 'interrupted' } } })
   return closers
 }
diff --git a/packages/core/session/src/seq-ranges.ts b/packages/core/session/src/seq-ranges.ts
index 7b2605652c..fc77fc397e 100644
--- a/packages/core/session/src/seq-ranges.ts
+++ b/packages/core/session/src/seq-ranges.ts
@@ -1,10 +1,13 @@
 /** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
 
+import { SessionSeq } from './types.ts'
+import type { SessionSeq as SessionSeqType } from './types.ts'
+
 /** A stored source sequence or inclusive consecutive range. */
 export type EncodedSeq = number | [number, number]
 
-function isStrictlyIncreasing(values: readonly number[]): boolean {
-  return values.every((value, index) => index === 0 || value > (values[index - 1] as number))
+function isStrictlyIncreasing(values: readonly SessionSeqType[]): boolean {
+  return values.every((value, index) => index === 0 || value > (values[index - 1] as SessionSeqType))
 }
 
 /**
@@ -12,7 +15,7 @@ function isStrictlyIncreasing(values: readonly number[]): boolean {
  * @param values - validated in-memory source sequences.
  * @returns a lossless JSON storage form.
  */
-export function encodeSeqRanges(values: readonly number[]): EncodedSeq[] {
+export function encodeSeqRanges(values: readonly SessionSeqType[]): EncodedSeq[] {
   if (!isStrictlyIncreasing(values)) return [...values]
   const encoded: EncodedSeq[] = []
   for (let start = 0; start < values.length;) {
@@ -31,15 +34,15 @@ export function encodeSeqRanges(values: readonly number[]): EncodedSeq[] {
  * @param maxEntries - largest list permitted by the owning event.
  * @returns the in-memory source sequences.
  */
-export function decodeSeqRanges(value: unknown, maxEntries = Number.MAX_SAFE_INTEGER): number[] {
+export function decodeSeqRanges(value: unknown, maxEntries = Number.MAX_SAFE_INTEGER): SessionSeqType[] {
   if (!Array.isArray(value)) throw new TypeError('sourceEventSeqs must be an array')
-  const decoded: number[] = []
+  const decoded: SessionSeqType[] = []
   let hasRange = false
   for (const entry of value) {
     if (typeof entry === 'number') {
       assertSeq(entry)
       if (decoded.length >= maxEntries) throw new TypeError('sourceEventSeqs exceeds its event sequence')
-      decoded.push(entry)
+      decoded.push(SessionSeq(entry))
       continue
     }
     if (!Array.isArray(entry) || entry.length !== 2) {
@@ -54,7 +57,7 @@ export function decodeSeqRanges(value: unknown, maxEntries = Number.MAX_SAFE_INT
     if (length > maxEntries - decoded.length) {
       throw new TypeError('sourceEventSeqs range exceeds its event sequence')
     }
-    for (let seq = start; seq <= end; seq += 1) decoded.push(seq)
+    for (let seq = start; seq <= end; seq += 1) decoded.push(SessionSeq(seq))
     hasRange = true
   }
   if (hasRange && !isStrictlyIncreasing(decoded)) {
diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts
index ba6c2dda80..bfb331eb22 100644
--- a/packages/core/session/src/surface.ts
+++ b/packages/core/session/src/surface.ts
@@ -9,7 +9,14 @@
  */
 
 import type { Message } from '@deepseek-ai/dsh-llm'
-import type { SessionEvent, SurfaceEvent, SurfaceEventType, SurfaceOp } from './types.ts'
+import { SessionLogOffset, SessionSeq } from './types.ts'
+import type {
+  SessionEvent,
+  SessionSeqCursor,
+  SurfaceEvent,
+  SurfaceEventType,
+  SurfaceOp,
+} from './types.ts'
 
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set<string>([
@@ -116,19 +123,19 @@ export function deriveEventMessage(event: SessionEvent): Message | null {
 /** One replacement operation observed while folding a session surface. */
 export interface SurfaceFoldReplacement {
   /** Seq of the event that replaced the prior surface range. */
-  seq: number
+  seq: SessionSeq
   /** Declared inclusive start seq of the replaced surface range. */
-  start: number
+  start: SessionSeq
   /** Declared inclusive end seq of the replaced surface range. */
-  end: number
+  end: SessionSeq
   /** Actual surface entries removed by the operation, in surface order. */
-  shadowedSeqs: number[]
+  shadowedSeqs: SessionSeq[]
 }
 
 /** Complete result of replaying the surface operations in a session log. */
 export interface SurfaceFoldResult {
   /** Current surface event sequences in model-visible order. */
-  nodes: number[]
+  nodes: SessionSeq[]
   /** Replacement operations in event order. */
   replacements: SurfaceFoldReplacement[]
 }
@@ -136,14 +143,14 @@ export interface SurfaceFoldResult {
 /** Readonly live projection of the message-producing session events. */
 export interface SessionSurface {
   /** Current surface event sequences in model-visible order. */
-  readonly nodes: readonly number[]
+  readonly nodes: readonly SessionSeq[]
   /** Monotonic count of committed positional replacements. */
   readonly replaceGeneration: number
 }
 
 /** Mutable state shared by complete and incremental folds. */
 interface SurfaceFoldState {
-  nodes: number[]
+  nodes: SessionSeq[]
   replaceGeneration: number
 }
 
@@ -156,7 +163,7 @@ interface SurfaceReplacePlan extends SurfaceFoldReplacement {
 
 /** One validated surface transition that has not mutated fold state yet. */
 type SurfacePlan =
-  | { kind: 'append'; seq: number }
+  | { kind: 'append'; seq: SessionSeq }
   | SurfaceReplacePlan
 
 /** Create an empty surface fold state. */
@@ -165,8 +172,11 @@ function createFoldState(): SurfaceFoldState {
 }
 
 /** Whether a runtime value is a non-negative safe event sequence. */
-function isEventSeq(value: unknown): value is number {
-  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+function isEventSeq(value: unknown): value is SessionSeq {
+  return typeof value === 'number'
+    && Number.isSafeInteger(value)
+    && value >= 0
+    && !Object.is(value, -0)
 }
 
 /** Whether a runtime value is the exact positional-replacement shape. */
@@ -210,10 +220,10 @@ function surfaceOpOf(event: SessionEvent): SurfaceOp | undefined {
 /** Validate cited source-event seqs against prior log entries and the replacement range. */
 function assertProvenance(
   event: SessionEvent,
-  shadowedSeqs: readonly number[],
+  shadowedSeqs: readonly SessionSeq[],
 ): void {
   const raw = (event as SessionEvent & { sourceEventSeqs?: unknown }).sourceEventSeqs
-  const sources = new Set<number>()
+  const sources = new Set<SessionSeq>()
   if (raw !== undefined) {
     if (!Array.isArray(raw)) {
       throw new Error(`sourceEventSeqs on event at seq ${event.seq} must be an array when present`)
@@ -221,7 +231,7 @@ function assertProvenance(
     if (raw.length === 0 && event.type !== 'assistant/message') {
       throw new Error('sourceEventSeqs must not be empty except on assistant/message')
     }
-    let nonEarlierSource: number | undefined
+    let nonEarlierSource: SessionSeq | undefined
     for (const source of raw) {
       if (!isEventSeq(source)) {
         throw new Error(`session event "${event.type}" sourceEventSeqs must densely contain non-negative safe integers`)
@@ -286,9 +296,9 @@ function isDeepEqualJson(a: unknown, b: unknown): boolean {
 /** Restrict a tool-result replacement to one current result's content. */
 function assertToolResultRewrite(
   event: SessionEvent,
-  shadowedSeqs: readonly number[],
+  shadowedSeqs: readonly SessionSeq[],
   events: readonly SessionEvent[],
-  baseSeq: number,
+  baseSeq: SessionLogOffset,
 ): void {
   if (event.type !== 'tool/result') return
   if (shadowedSeqs.length !== 1) {
@@ -321,9 +331,9 @@ function assertToolResultRewrite(
 function planSurfaceEvent(
   state: SurfaceFoldState,
   event: SessionEvent,
-  expectedSeq: number,
+  expectedSeq: SessionSeq,
   events: readonly SessionEvent[],
-  baseSeq: number,
+  baseSeq: SessionLogOffset,
 ): SurfacePlan | undefined {
   if (event.seq !== expectedSeq) {
     throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`)
@@ -350,9 +360,9 @@ function planSurfaceEvent(
 function applySurfaceEvent(
   state: SurfaceFoldState,
   event: SessionEvent,
-  expectedSeq: number,
+  expectedSeq: SessionSeq,
   events: readonly SessionEvent[],
-  baseSeq: number,
+  baseSeq: SessionLogOffset,
 ): SurfaceFoldReplacement | undefined {
   const plan = planSurfaceEvent(state, event, expectedSeq, events, baseSeq)
   return applySurfacePlan(state, plan)
@@ -388,7 +398,13 @@ export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult
   const state = createFoldState()
   const replacements: SurfaceFoldReplacement[] = []
   for (const [index, event] of events.entries()) {
-    const replacement = applySurfaceEvent(state, event, index, events, 0)
+    const replacement = applySurfaceEvent(
+      state,
+      event,
+      SessionSeq(index),
+      events,
+      SessionLogOffset(0),
+    )
     if (replacement !== undefined) replacements.push(replacement)
   }
   return { nodes: [...state.nodes], replacements }
@@ -399,9 +415,9 @@ export class SurfaceManager implements SessionSurface {
   /** Shared transition state; replacement history is not retained. */
   private _state = createFoldState()
   /** Last processed absolute seq. */
-  private _lastProcessedSeq: number
+  private _lastProcessedSeq: SessionSeqCursor
   /** Candidate already validated by `validateNext`, pending exact log admission. */
-  private _pendingPlan: { event: SessionEvent; expectedSeq: number; plan: SurfacePlan | undefined } | undefined
+  private _pendingPlan: { event: SessionEvent; expectedSeq: SessionSeq; plan: SurfacePlan | undefined } | undefined
 
   /**
    * @param log - Contiguous complete log or loaded event window.
@@ -409,9 +425,9 @@ export class SurfaceManager implements SessionSurface {
    */
   constructor(
     private log: readonly SessionEvent[],
-    private readonly baseSeq = 0,
+    private readonly baseSeq: SessionLogOffset = SessionLogOffset(0),
   ) {
-    this._lastProcessedSeq = baseSeq - 1
+    this._lastProcessedSeq = baseSeq === 0 ? -1 : SessionSeq(baseSeq - 1)
   }
 
   /**
@@ -420,7 +436,7 @@ export class SurfaceManager implements SessionSurface {
    */
   validateNext(event: SessionEvent): void {
     if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta()
-    const expectedSeq = this.baseSeq + this.log.length
+    const expectedSeq = SessionSeq(this.baseSeq + this.log.length)
     this._pendingPlan = {
       event,
       expectedSeq,
@@ -435,7 +451,7 @@ export class SurfaceManager implements SessionSurface {
   }
 
   /** Surface event sequences in model-visible order. */
-  get nodes(): readonly number[] {
+  get nodes(): readonly SessionSeq[] {
     if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta()
     return this._state.nodes
   }
@@ -451,10 +467,10 @@ export class SurfaceManager implements SessionSurface {
       if (pending?.event === event && pending.expectedSeq === seq) {
         applySurfacePlan(this._state, pending.plan)
       } else {
-        applySurfaceEvent(this._state, event, seq, this.log, this.baseSeq)
+        applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq)
       }
       if (pending !== undefined && pending.expectedSeq <= seq) this._pendingPlan = undefined
-      this._lastProcessedSeq = seq
+      this._lastProcessedSeq = SessionSeq(seq)
     }
   }
 }
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index d6ae6c5764..461c31ad36 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -1,4 +1,4 @@
-import { brandString, type Branded } from '@deepseek-ai/dsh-brand'
+import { brandNumber, brandString, type Branded, type BrandedNumber } from '@deepseek-ai/dsh-brand'
 import type {
   AssistantMessage,
   ToolCallId,
@@ -25,6 +25,42 @@ export function SessionId(id: string): SessionId {
   return brandString<SessionId>(id)
 }
 
+/** Sequence number of one existing event in a Session log. */
+export type SessionSeq = BrandedNumber<'SessionSeq'>
+
+/**
+ * Admit a numeric value as an existing Session event position.
+ * @param value - non-negative safe integer admitted by the owning log operation.
+ * @returns the same number with the Session-sequence brand.
+ */
+export function SessionSeq(value: number): SessionSeq {
+  if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) {
+    throw new TypeError(`SessionSeq must be a non-negative safe integer, got ${String(value)}`)
+  }
+  return brandNumber<SessionSeq>(value)
+}
+
+/** A Session log gap, prefix length, or read offset, which may equal the event count. */
+export type SessionLogOffset = BrandedNumber<'SessionLogOffset'>
+
+/**
+ * Admit a numeric value as a Session log offset.
+ * @param value - non-negative safe integer used as a gap or prefix length.
+ * @returns the same number with the Session-log-offset brand.
+ */
+export function SessionLogOffset(value: number): SessionLogOffset {
+  if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) {
+    throw new TypeError(`SessionLogOffset must be a non-negative safe integer, got ${String(value)}`)
+  }
+  return brandNumber<SessionLogOffset>(value)
+}
+
+/** Inclusive Session event watermark, or `-1` before any event exists. */
+export type SessionSeqCursor = SessionSeq | -1
+
+/** One existing Session event position, or explicit absence. */
+export type OptionalSessionSeq = SessionSeq | null
+
 /**
  * The on-disk session format version, stamped into every newly-written {@link SessionHeader}
  * and enforced by every persistence backend on load. The single source of truth for the
@@ -69,10 +105,10 @@ export interface SessionHeader {
   /** The session this one was forked from (seed lineage), if any. */
   readonly parentSession?: SessionId
   /**
-   * How many leading events were inherited through a seed. Persisting this
-   * boundary lets resume and replay distinguish parent history from child work.
+   * Whether this Session contains a fork-inherited event prefix. The exact prefix
+   * length is Session state rather than ordinary header metadata.
    */
-  readonly seedLength?: number
+  readonly isSeeded: boolean
   /**
    * Coarse product classification for a session created as a subagent child.
    * This is presentation metadata, not proof that the child is continuable.
@@ -102,14 +138,19 @@ export interface CreateSessionOptions {
   /** Initial replay or fork history supplied at construction. */
   readonly seed?: readonly SessionEvent[]
   /**
-   * Storage metadata read once before publication. `seedLength` is explicit
-   * because a resumed seed contains the full stored log, not only its inherited prefix.
+   * Exact fork-inherited prefix length when `meta.isSeeded` is true. A
+   * constructor seed may also contain child-owned setup events after this cut.
+   */
+  readonly inheritedEventCount?: SessionLogOffset
+  /**
+   * Storage metadata read once before publication. `isSeeded` marks fork
+   * lineage; supplying replay history alone does not make it inherited.
    */
   readonly meta?: {
     readonly cwd?: string
     readonly parentSession?: SessionId
     readonly createdAt?: number
-    readonly seedLength?: number
+    readonly isSeeded?: boolean
     readonly origin?: 'subagent'
     readonly delegationDepth?: number
     readonly agentPreset?: string
@@ -125,6 +166,8 @@ export interface RestoredSessionOptions {
   readonly seed: SessionEvent[]
   /** Fresh detached storage metadata to validate and freeze in place. */
   readonly meta: SessionHeader
+  /** Exact number of fork-inherited leading events decoded from storage. */
+  readonly inheritedEventCount: SessionLogOffset
   /** Select the persistence ownership-transfer path. */
   readonly seedSource: 'persistence'
 }
@@ -358,7 +401,7 @@ export type SurfaceEvent = SessionEvent<SurfaceEventType> & { surfaceOp: Surface
  */
 export type SurfaceOp =
   | 'append'
-  | { op: 'replace'; start: number; end: number }
+  | { op: 'replace'; start: SessionSeq; end: SessionSeq }
 
 /**
  * Surface placement and cited source-event seqs for {@link Session.append}. Required on
@@ -372,7 +415,7 @@ export interface SurfaceIntent {
    * absent, the event does not record which earlier events produced the message.
    * Other surface events require a non-empty set when this field is present.
    */
-  sourceEventSeqs?: number[]
+  sourceEventSeqs?: SessionSeq[]
 }
 
 /**
@@ -392,7 +435,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
   [K in SessionEventType]: {
     type: K
     /** Monotonic sequence number within the session. */
-    seq: number
+    seq: SessionSeq
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
@@ -416,7 +459,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * provider stream; when the field is absent, the event does not record which
      * earlier events produced the message.
      */
-    sourceEventSeqs?: number[]
+    sourceEventSeqs?: SessionSeq[]
     /** How this event entered the surface; absent for non-surface events. */
     surfaceOp?: SurfaceOp
   } : object)
diff --git a/packages/core/session/tests/chunk-rows.spec.ts b/packages/core/session/tests/chunk-rows.spec.ts
index 500355a4fe..b18046914b 100644
--- a/packages/core/session/tests/chunk-rows.spec.ts
+++ b/packages/core/session/tests/chunk-rows.spec.ts
@@ -8,19 +8,19 @@ import { describe, expect, it } from 'vitest'
 import fc from 'fast-check'
 import { ToolCallId } from '@deepseek-ai/dsh-llm'
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
-import { decodeStorageRecord, packChunkRuns } from '@deepseek-ai/dsh-session'
+import { decodeStorageRecord, packChunkRuns, SessionSeq } from '@deepseek-ai/dsh-session'
 import { chunkRowLength, isChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
 import type { ChunkRow, SessionEvent, StorageRecord } from '@deepseek-ai/dsh-session'
 
 /** Build an `assistant/chunk` event with the exact live-append shape. */
-function chunkEvent(seq: number, time: number, chunk: StreamChunk, turn = 1, step = 1): SessionEvent {
+function chunkEvent(seq: SessionSeq, time: number, chunk: StreamChunk, turn = 1, step = 1): SessionEvent {
   return { type: 'assistant/chunk', seq, time, data: { turn, step, chunk } }
 }
 
 /** Sequential delta events (contiguous seqs, fixed 10ms gaps) of one kind. */
 function deltaRun(kind: 'text-delta' | 'reasoning-delta', count: number, seq0 = 0, index = 0): SessionEvent[] {
   return Array.from({ length: count }, (_, k) =>
-    chunkEvent(seq0 + k, 1000 + 10 * k, { type: kind, index, text: `t${k}` }))
+    chunkEvent(SessionSeq(seq0 + k), 1000 + 10 * k, { type: kind, index, text: `t${k}` }))
 }
 
 /** Decode a packed record list back to a flat event list. */
@@ -47,7 +47,7 @@ describe('packChunkRuns', () => {
   it('packs reasoning and tool-call runs under their own tags', () => {
     const reasoning = deltaRun('reasoning-delta', 3)
     const toolCall = [4, 5, 6].map(seq =>
-      chunkEvent(seq, 1000 + seq, { type: 'tool-call-delta', index: 1, id: ToolCallId('c1'), name: 'write', argumentsDelta: `a${seq}` }))
+      chunkEvent(SessionSeq(seq), 1000 + seq, { type: 'tool-call-delta', index: 1, id: ToolCallId('c1'), name: 'write', argumentsDelta: `a${seq}` }))
     const packed = packChunkRuns([...reasoning, ...toolCall])
     expect(packed.map(r => (r as ChunkRow).type)).toStrictEqual(['reasoning-chunks', 'tool-call-chunks'])
     const row = packed[1] as ChunkRow & { type: 'tool-call-chunks' }
@@ -58,7 +58,7 @@ describe('packChunkRuns', () => {
 
   it('packs a name-less tool-call run and round-trips field absence', () => {
     const events = [0, 1, 2].map(seq =>
-      chunkEvent(seq, 1000, { type: 'tool-call-delta', index: 0, id: ToolCallId('c1'), argumentsDelta: `a${seq}` }))
+      chunkEvent(SessionSeq(seq), 1000, { type: 'tool-call-delta', index: 0, id: ToolCallId('c1'), argumentsDelta: `a${seq}` }))
     const packed = packChunkRuns(events)
     expect(packed).toHaveLength(1)
     expect(Object.hasOwn((packed[0] as ChunkRow).data, 'name')).toBe(false)
@@ -74,10 +74,10 @@ describe('packChunkRuns', () => {
 
   it('leaves non-delta chunks and non-chunk events verbatim between runs', () => {
     const events: SessionEvent[] = [
-      chunkEvent(0, 1000, { type: 'block-start', index: 0, blockType: 'text' }),
+      chunkEvent(SessionSeq(0), 1000, { type: 'block-start', index: 0, blockType: 'text' }),
       ...deltaRun('text-delta', 3, 1),
-      chunkEvent(4, 1040, { type: 'block-end', index: 0, block: { type: 'text', text: 't0t1t2' } }),
-      { type: 'step/end', seq: 5, time: 1050, data: { turn: 1, step: 1 } },
+      chunkEvent(SessionSeq(4), 1040, { type: 'block-end', index: 0, block: { type: 'text', text: 't0t1t2' } }),
+      { type: 'step/end', seq: SessionSeq(5), time: 1050, data: { turn: 1, step: 1 } },
     ]
     const packed = packChunkRuns(events)
     expect(packed).toHaveLength(4)
@@ -86,27 +86,27 @@ describe('packChunkRuns', () => {
   })
 
   it.each([
-    ['a seq gap', deltaRun('text-delta', 3).map((e, k) => ({ ...e, seq: k === 2 ? 9 : e.seq }))],
+    ['a seq gap', deltaRun('text-delta', 3).map((e, k) => ({ ...e, seq: k === 2 ? SessionSeq(9) : e.seq }))],
     ['a kind switch', [...deltaRun('text-delta', 2), ...deltaRun('reasoning-delta', 1, 2)]],
     ['a block-index switch', [...deltaRun('text-delta', 2), ...deltaRun('text-delta', 1, 2, 7)]],
-    ['a step switch', deltaRun('text-delta', 3).map((e, k) => k === 2 ? chunkEvent(e.seq, e.time, (e.data as { chunk: StreamChunk }).chunk, 1, 2) : e)],
+    ['a step switch', deltaRun('text-delta', 3).map((e, k) => k === 2 ? chunkEvent(SessionSeq(e.seq), e.time, (e.data as { chunk: StreamChunk }).chunk, 1, 2) : e)],
   ])('breaks a run on %s (both halves too short to pack)', (_label, events) => {
     expect(packChunkRuns(events)).toStrictEqual(events)
   })
 
   it('breaks a tool-call run on call-id or name change', () => {
-    const call = (seq: number, id: string, name?: string): SessionEvent =>
+    const call = (seq: SessionSeq, id: string, name?: string): SessionEvent =>
       chunkEvent(seq, 1000, { type: 'tool-call-delta', index: 0, id: ToolCallId(id), ...name !== undefined ? { name } : {}, argumentsDelta: 'a' })
-    const idSwitch = [call(0, 'c1', 'w'), call(1, 'c1', 'w'), call(2, 'c2', 'w')]
+    const idSwitch = [call(SessionSeq(0), 'c1', 'w'), call(SessionSeq(1), 'c1', 'w'), call(SessionSeq(2), 'c2', 'w')]
     expect(packChunkRuns(idSwitch)).toStrictEqual(idSwitch)
-    const namePresence = [call(0, 'c1', 'w'), call(1, 'c1', 'w'), call(2, 'c1')]
+    const namePresence = [call(SessionSeq(0), 'c1', 'w'), call(SessionSeq(1), 'c1', 'w'), call(SessionSeq(2), 'c1')]
     expect(packChunkRuns(namePresence)).toStrictEqual(namePresence)
   })
 
   it('stores an off-whitelist delta verbatim (extra field, bad type, fractional time)', () => {
-    const extraField = { ...chunkEvent(0, 1000, { type: 'text-delta', index: 0, text: 'x' }), surfaceOp: 'append' }
-    const badText = chunkEvent(1, 1001, { type: 'text-delta', index: 0, text: 7 as unknown as string })
-    const fractionalTime = chunkEvent(2, 1001.5, { type: 'text-delta', index: 0, text: 'y' })
+    const extraField = { ...chunkEvent(SessionSeq(0), 1000, { type: 'text-delta', index: 0, text: 'x' }), surfaceOp: 'append' }
+    const badText = chunkEvent(SessionSeq(1), 1001, { type: 'text-delta', index: 0, text: 7 as unknown as string })
+    const fractionalTime = chunkEvent(SessionSeq(2), 1001.5, { type: 'text-delta', index: 0, text: 'y' })
     const events = [extraField, badText, fractionalTime] as SessionEvent[]
     expect(packChunkRuns(events)).toStrictEqual(events)
   })
@@ -119,43 +119,48 @@ describe('packChunkRuns', () => {
     const b = Number.MAX_SAFE_INTEGER - 1
     expect(a + (b - a)).not.toBe(b) // the rounding this guard exists for
     const events = [
-      chunkEvent(0, a, { type: 'text-delta', index: 0, text: 'x' }),
-      chunkEvent(1, b, { type: 'text-delta', index: 0, text: 'y' }),
-      chunkEvent(2, b + 1, { type: 'text-delta', index: 0, text: 'z' }),
+      chunkEvent(SessionSeq(0), a, { type: 'text-delta', index: 0, text: 'x' }),
+      chunkEvent(SessionSeq(1), b, { type: 'text-delta', index: 0, text: 'y' }),
+      chunkEvent(SessionSeq(2), b + 1, { type: 'text-delta', index: 0, text: 'z' }),
     ]
     expect(packChunkRuns(events)).toStrictEqual(events) // split at the gap; halves too short
     expect(decodeAll(packChunkRuns(events))).toStrictEqual(events)
   })
 
   it('stores a delta with an off-whitelist data envelope verbatim (parsed-fixture shapes)', () => {
-    const mk = (seq: number, data: unknown): SessionEvent =>
+    const mk = (seq: SessionSeq, data: unknown): SessionEvent =>
       ({ type: 'assistant/chunk', seq, time: 1000, data } as SessionEvent)
     const events = [
-      mk(0, 'not-an-object'),
-      mk(1, { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'a' }, extra: 1 }),
-      mk(2, { turn: 'x', step: 1, chunk: { type: 'text-delta', index: 0, text: 'a' } }),
-      mk(3, { turn: 1, step: 1, chunk: 'not-an-object' }),
-      mk(4, { turn: 1, step: 1, chunk: { type: 'text-delta', index: 'x', text: 'a' } }),
-      mk(5, { turn: 1, step: 1, chunk: { type: 'tool-call-delta', index: 0, id: 7, argumentsDelta: 'a' } }),
-      mk(6, { turn: 1, step: 1, chunk: { type: 'tool-call-delta', index: 0, id: 'c', name: 7, argumentsDelta: 'a' } }),
+      mk(SessionSeq(0), 'not-an-object'),
+      mk(SessionSeq(1), { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'a' }, extra: 1 }),
+      mk(SessionSeq(2), { turn: 'x', step: 1, chunk: { type: 'text-delta', index: 0, text: 'a' } }),
+      mk(SessionSeq(3), { turn: 1, step: 1, chunk: 'not-an-object' }),
+      mk(SessionSeq(4), { turn: 1, step: 1, chunk: { type: 'text-delta', index: 'x', text: 'a' } }),
+      mk(SessionSeq(5), { turn: 1, step: 1, chunk: { type: 'tool-call-delta', index: 0, id: 7, argumentsDelta: 'a' } }),
+      mk(SessionSeq(6), { turn: 1, step: 1, chunk: { type: 'tool-call-delta', index: 0, id: 'c', name: 7, argumentsDelta: 'a' } }),
     ]
     expect(packChunkRuns(events)).toStrictEqual(events)
   })
 })
 
 describe('decodeStorageRecord', () => {
-  it('passes non-row values through as single events, unvalidated', () => {
+  it('passes non-row values through after sequence admission', () => {
     const event = { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }
-    expect(decodeStorageRecord(event)).toStrictEqual([event])
+    const decoded = decodeStorageRecord(event)
+    expect(decoded).toStrictEqual([event])
+    expect(decoded[0]).toBe(event)
     expect(decodeStorageRecord('junk')).toStrictEqual(['junk'])
     expect(decodeStorageRecord(null)).toStrictEqual([null])
+    const withoutSeq = { type: 'future/event', data: {} }
+    expect(decodeStorageRecord(withoutSeq)).toStrictEqual([withoutSeq])
+    expect(() => decodeStorageRecord({ ...event, seq: -0 })).toThrow(/SessionSeq/)
   })
 
   it('reconstructs timestamps through negative dt gaps (clock stepped back)', () => {
     const events = [
-      chunkEvent(0, 1000, { type: 'text-delta', index: 0, text: 'a' }),
-      chunkEvent(1, 990, { type: 'text-delta', index: 0, text: 'b' }),
-      chunkEvent(2, 995, { type: 'text-delta', index: 0, text: 'c' }),
+      chunkEvent(SessionSeq(0), 1000, { type: 'text-delta', index: 0, text: 'a' }),
+      chunkEvent(SessionSeq(1), 990, { type: 'text-delta', index: 0, text: 'b' }),
+      chunkEvent(SessionSeq(2), 995, { type: 'text-delta', index: 0, text: 'c' }),
     ]
     expect(decodeAll(packChunkRuns(events))).toStrictEqual(events)
   })
@@ -164,6 +169,7 @@ describe('decodeStorageRecord', () => {
     ['a non-object data', { type: 'text-chunks', seq0: 0, time0: 1, data: 'x' }],
     ['an envelope with extra keys', { type: 'text-chunks', seq0: 0, time0: 1, data: { turn: 1, step: 1, index: 0, dt: [], texts: ['a'] }, extra: 1 }],
     ['a negative seq0', { type: 'text-chunks', seq0: -1, time0: 1, data: { turn: 1, step: 1, index: 0, dt: [], texts: ['a'] } }],
+    ['a negative-zero seq0', { type: 'text-chunks', seq0: -0, time0: 1, data: { turn: 1, step: 1, index: 0, dt: [], texts: ['a'] } }],
     ['a non-finite time0', { type: 'text-chunks', seq0: 0, time0: Infinity, data: { turn: 1, step: 1, index: 0, dt: [], texts: ['a'] } }],
     ['a fractional time0', { type: 'text-chunks', seq0: 0, time0: 1.5, data: { turn: 1, step: 1, index: 0, dt: [], texts: ['a'] } }],
     ['a data shape mismatch', { type: 'text-chunks', seq0: 0, time0: 1, data: { turn: 1, step: 1, index: 0, dt: [], args: ['a'] } }],
@@ -229,7 +235,7 @@ const batchArb: fc.Arbitrary<SessionEvent[]> = fc.array(
   // plain objects real log events are (the log is JSON), so equality compares
   // values, not prototypes.
 ).map(entries => JSON.parse(JSON.stringify(
-  entries.map((entry, k) => chunkEvent(k, entry.time, entry.chunk, entry.turn, entry.step)),
+  entries.map((entry, k) => chunkEvent(SessionSeq(k), entry.time, entry.chunk, entry.turn, entry.step)),
 )) as SessionEvent[])
 
 describe('chunk-row codec properties', () => {
diff --git a/packages/core/session/tests/fork.spec.ts b/packages/core/session/tests/fork.spec.ts
index 537bf9c3ee..b5f1c02cad 100644
--- a/packages/core/session/tests/fork.spec.ts
+++ b/packages/core/session/tests/fork.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { createUserMessage, ToolCallId , createMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionForkError, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionForkError, SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
 
 declare module '@deepseek-ai/dsh-session/types' {
@@ -46,18 +46,15 @@ function firstUserMessage(events: readonly SessionEvent[]): SessionEvent<'user/m
   return event
 }
 
-function lastSeq(session: Session): number {
+function lastSeq(session: Session): SessionSeq {
   const event = session.snapshotEvents().at(-1)
   if (event === undefined) throw new Error('missing last event')
   return event.seq
 }
 
-/** A seeded child's constructor seed: its log minus the end-seed marker. */
+/** A seeded child's fork-inherited prefix. */
 function inherited(session: Session): readonly SessionEvent[] {
-  const events = session.snapshotEvents()
-  const last = events.at(-1)
-  if (last?.type !== 'session/end-seed') throw new Error('seeded child is missing its end-seed marker')
-  return events.slice(0, -1)
+  return session.snapshotEvents(SessionLogOffset(0), session.inheritedEventCount)
 }
 
 describe('SessionStore.fork', () => {
@@ -72,8 +69,9 @@ describe('SessionStore.fork', () => {
       id: SessionId('empty-child'),
       cwd: '/workspace',
       parentSession: SessionId('empty-parent'),
-      seedLength: 0,
+      isSeeded: true,
     })
+    expect(child.inheritedEventCount).toBe(0)
   })
 
   it('forks the latest completed boundary by default into detached frozen seed events', async () => {
@@ -95,8 +93,9 @@ describe('SessionStore.fork', () => {
       id: SessionId('child'),
       cwd: '/workspace',
       parentSession: SessionId('parent'),
-      seedLength: source.snapshotEvents().length,
+      isSeeded: true,
     })
+    expect(child.inheritedEventCount).toBe(source.seq)
   })
 
   it('includes stable log-only events appended after a closed turn', async () => {
@@ -125,7 +124,7 @@ describe('SessionStore.fork', () => {
     const child = sessions.fork(source, firstBoundary, SessionId('child-from-first'))
 
     expect(inherited(child)).toEqual(source.snapshotEvents().slice(0, firstBoundary + 1))
-    expect(child.header.seedLength).toBe(firstBoundary + 1)
+    expect(child.inheritedEventCount).toBe(firstBoundary + 1)
     expect(child.deriveMessages()).toEqual([{
       id: expect.any(String) as unknown,
       role: 'user',
@@ -152,7 +151,7 @@ describe('SessionStore.fork', () => {
       const child = sessions.fork(source, lastSeq(source), SessionId(`child-${index}`))
 
       expect(inherited(child).at(-1)?.type).toBe('turn/end')
-      expect(child.header.seedLength).toBe(source.snapshotEvents().length)
+      expect(child.inheritedEventCount).toBe(source.seq)
     }
   })
 
@@ -180,19 +179,19 @@ describe('SessionStore.fork', () => {
   it('rejects invalid boundaries before creating a child', async () => {
     const { ctx, sessions } = await setup()
     const empty = ctx.sessions.create(SessionId('empty'))
-    expect(() => sessions.fork(empty, 0, SessionId('empty-child')))
+    expect(() => sessions.fork(empty, SessionSeq(0), SessionId('empty-child')))
       .toThrow(new SessionForkError('fork boundary 0 does not exist in session "empty" (last seq: none)', 'INVALID_BOUNDARY'))
     expect(ctx.sessions.get(SessionId('empty-child'))).toBeUndefined()
 
     const source = ctx.sessions.create(SessionId('parent'))
     appendClosedTurn(source, 1)
-    expect(() => sessions.fork(source, -1, SessionId('negative')))
+    expect(() => sessions.fork(source, -1 as never, SessionId('negative')))
       .toThrow(/non-negative safe integer/)
-    expect(() => sessions.fork(source, 0.5, SessionId('fraction')))
+    expect(() => sessions.fork(source, 0.5 as never, SessionId('fraction')))
       .toThrow(/non-negative safe integer/)
-    expect(() => sessions.fork(source, Number.MAX_SAFE_INTEGER + 1, SessionId('unsafe')))
+    expect(() => sessions.fork(source, (Number.MAX_SAFE_INTEGER + 1) as never, SessionId('unsafe')))
       .toThrow(/non-negative safe integer/)
-    expect(() => sessions.fork(source, source.seq, SessionId('past-end')))
+    expect(() => sessions.fork(source, SessionSeq(source.seq), SessionId('past-end')))
       .toThrow(new SessionForkError(`fork boundary ${source.seq} does not exist in session "parent" (last seq: ${source.seq - 1})`, 'INVALID_BOUNDARY'))
   })
 
@@ -201,9 +200,9 @@ describe('SessionStore.fork', () => {
     const source = ctx.sessions.create(SessionId('corrupt-parent'))
     appendClosedTurn(source, 1)
     const mutableLog = (source as unknown as { log: SessionEvent[] }).log
-    mutableLog[2] = { ...mutableLog[2]!, seq: 99 }
+    mutableLog[2] = { ...mutableLog[2]!, seq: SessionSeq(99) }
 
-    expect(() => sessions.fork(source, 2, SessionId('corrupt-child')))
+    expect(() => sessions.fork(source, SessionSeq(2), SessionId('corrupt-child')))
       .toThrow(new SessionForkError('fork boundary 2 does not match a contiguous event seq in session "corrupt-parent"', 'INVALID_BOUNDARY'))
     expect(ctx.sessions.get(SessionId('corrupt-child'))).toBeUndefined()
   })
@@ -292,7 +291,7 @@ describe('SessionStore.fork', () => {
       const source = ctx.sessions.create(SessionId(`open-${lastType}`))
       const boundary = build(source)
 
-      expect(() => sessions.fork(source, boundary))
+      expect(() => sessions.fork(source, SessionSeq(boundary)))
         .toThrow(new SessionForkError(`fork boundary ${boundary} in session "open-${lastType}" ends inside open turn 1`, 'OPEN_TURN'))
     }
   })
diff --git a/packages/core/session/tests/invariant.spec.ts b/packages/core/session/tests/invariant.spec.ts
index 26aede8930..8f6767411d 100644
--- a/packages/core/session/tests/invariant.spec.ts
+++ b/packages/core/session/tests/invariant.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { createScope, scopeTarget } from '@deepseek-ai/dsh-scope'
 import { createUserMessage, ToolCallId, createMessage, createToolResultMessage, freezeMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId, TOOL_NOT_STARTED } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionSeq, TOOL_NOT_STARTED } from '@deepseek-ai/dsh-session'
 import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
 import InvariantRegistry, { InvariantError } from '@deepseek-ai/dsh-invariants'
 
@@ -374,8 +374,8 @@ describe('session-log invariants', () => {
   it('replays seeded sessions and tracks each session independently', async () => {
     const { ctx } = await setup()
     const badSeed = [
-      { type: 'turn/start' as const, seq: 0, time: 0, data: { turn: 1 } },
-      { type: 'turn/start' as const, seq: 1, time: 0, data: { turn: 2 } },
+      { type: 'turn/start' as const, seq: SessionSeq(0), time: 0, data: { turn: 1 } },
+      { type: 'turn/start' as const, seq: SessionSeq(1), time: 0, data: { turn: 2 } },
     ]
     expect(() => ctx.sessions.create(undefined, { seed: badSeed })).toThrow(InvariantError)
 
@@ -406,12 +406,12 @@ describe('session-log invariants', () => {
     const { ctx } = await setup()
     // Balanced seed: between turns.
     expect(() => ctx.sessions.create(SessionId('inherited-between-turns'), { seed: [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
     ] })).not.toThrow()
     // Unbalanced seed: inside the open turn, which the relation permits.
     const open = ctx.sessions.create(SessionId('inherited-inside-open-turn'), { seed: [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
     ] })
     expect(open.snapshotEvents().map(event => event.type)).toEqual(['turn/start', 'session/end-seed'])
     // Still open afterwards: the boundary moves no cursor.
diff --git a/packages/core/session/tests/repair.spec.ts b/packages/core/session/tests/repair.spec.ts
index c671d079d1..d4955d0110 100644
--- a/packages/core/session/tests/repair.spec.ts
+++ b/packages/core/session/tests/repair.spec.ts
@@ -1,7 +1,20 @@
 import { describe, expect, it } from 'vitest'
 import { ToolCallId , createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
-import { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from '../src/index.ts'
-import type { SessionEvent, SurfaceEvent } from '../src/index.ts'
+import { interruptedTurnClosers as repairInterruptedTurn, SessionSeq, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from '../src/index.ts'
+import type { SessionEvent as LogicalSessionEvent, SurfaceEvent } from '../src/index.ts'
+
+interface SessionEvent {
+  type: string
+  seq: number
+  time: number
+  data: unknown
+  [key: string]: unknown
+}
+
+function interruptedTurnClosers(events: readonly SessionEvent[]): LogicalSessionEvent[] {
+  for (const event of events) SessionSeq(event.seq)
+  return repairInterruptedTurn(events as unknown as readonly LogicalSessionEvent[])
+}
 
 /**
  * Unit coverage for the crash-recovery closer synthesis. The persistence
diff --git a/packages/core/session/tests/request-header.spec.ts b/packages/core/session/tests/request-header.spec.ts
index 17d7ba80de..e3b7bdb92b 100644
--- a/packages/core/session/tests/request-header.spec.ts
+++ b/packages/core/session/tests/request-header.spec.ts
@@ -1,7 +1,7 @@
 /** Request-header canonicalization, equality, snapshot folding, and format rejection. */
 
 import { describe, expect, it } from 'vitest'
-import { Session, SessionId, canonicalHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, SessionSeq, canonicalHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session'
 import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
 import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
@@ -68,7 +68,7 @@ describe('foldRequestHeader', () => {
   it('returns the supplied baseline when no snapshot follows', () => {
     const from: EpochHeader = { config: CONFIG, system: 'baseline' }
     const unrelated: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
     ]
     expect(foldRequestHeader(unrelated)).toBeUndefined()
     expect(foldRequestHeader(unrelated, from)).toBe(from)
@@ -121,10 +121,10 @@ describe('Session.requestContext', () => {
   /** A turn-enclosed capacity record; the invariant rejects one outside a turn. */
   function seedWith(...records: { provider: string; model: string; contextWindow?: number }[]): SessionEvent[] {
     const events: SessionEvent[] = [{
-      type: 'turn/start', seq: 0, time: 1, data: { turn: 1 },
+      type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 },
     }]
     for (const data of records) {
-      events.push({ type: 'request/context', seq: events.length, time: 1, data })
+      events.push({ type: 'request/context', seq: SessionSeq(events.length), time: 1, data })
     }
     return events
   }
diff --git a/packages/core/session/tests/seq-ranges.spec.ts b/packages/core/session/tests/seq-ranges.spec.ts
index d86bb71e6c..cace9b53c3 100644
--- a/packages/core/session/tests/seq-ranges.spec.ts
+++ b/packages/core/session/tests/seq-ranges.spec.ts
@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest'
-import { decodeSeqRanges, encodeSeqRanges } from '@deepseek-ai/dsh-session'
+import { decodeSeqRanges, encodeSeqRanges, SessionSeq } from '@deepseek-ai/dsh-session'
+
+const seqs = (values: readonly number[]) => values.map(SessionSeq)
 
 describe('sourceEventSeqs ranges', () => {
   it.each([
@@ -10,17 +12,17 @@ describe('sourceEventSeqs ranges', () => {
     [3, 2],
     [Number.MAX_SAFE_INTEGER - 1, 0, Number.MAX_SAFE_INTEGER - 2],
   ].map(values => [values]))('round-trips %j', (values) => {
-    expect(decodeSeqRanges(encodeSeqRanges(values))).toEqual(values)
+    expect(decodeSeqRanges(encodeSeqRanges(seqs(values)))).toEqual(values)
   })
 
   it('encodes only profitable increasing runs', () => {
-    expect(encodeSeqRanges([1, 3, 4, 5, 7])).toEqual([1, [3, 5], 7])
-    expect(encodeSeqRanges([1, 3, 4, 7])).toEqual([1, 3, 4, 7])
-    expect(encodeSeqRanges([3, 2])).toEqual([3, 2])
+    expect(encodeSeqRanges(seqs([1, 3, 4, 5, 7]))).toEqual([1, [3, 5], 7])
+    expect(encodeSeqRanges(seqs([1, 3, 4, 7]))).toEqual([1, 3, 4, 7])
+    expect(encodeSeqRanges(seqs([3, 2]))).toEqual([3, 2])
   })
 
   it('does not impose a persistence-only provenance length limit', () => {
-    const values = Array.from({ length: 1_000_001 }, (_, index) => index)
+    const values = Array.from({ length: 1_000_001 }, (_, index) => SessionSeq(index))
     expect(encodeSeqRanges(values)).toEqual([[0, 1_000_000]])
   })
 
diff --git a/packages/core/session/tests/sequence-types.spec.ts b/packages/core/session/tests/sequence-types.spec.ts
new file mode 100644
index 0000000000..11ac49b301
--- /dev/null
+++ b/packages/core/session/tests/sequence-types.spec.ts
@@ -0,0 +1,153 @@
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import {
+  Session,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+  type OptionalSessionSeq,
+  type SessionLogOffset as SessionLogOffsetType,
+  type SessionHeader,
+  type SessionSeq as SessionSeqType,
+  type SessionSeqCursor,
+} from '@deepseek-ai/dsh-session'
+
+describe('Session log positions', () => {
+  it('admits non-negative safe integers into distinct sequence roles', () => {
+    const seq = SessionSeq(3)
+    const offset = SessionLogOffset(4)
+
+    expect(seq).toBe(3)
+    expect(offset).toBe(4)
+    expectTypeOf(seq).toEqualTypeOf<SessionSeqType>()
+    expectTypeOf(offset).toEqualTypeOf<SessionLogOffsetType>()
+    expectTypeOf(seq).not.toEqualTypeOf<SessionLogOffsetType>()
+    expectTypeOf<SessionSeqCursor>().toEqualTypeOf<SessionSeqType | -1>()
+    expectTypeOf<OptionalSessionSeq>().toEqualTypeOf<SessionSeqType | null>()
+  })
+
+  it.each([-1, -0, 0.5, Number.MAX_SAFE_INTEGER + 1, Number.NaN])(
+    'rejects invalid Session sequence positions (%s)',
+    (value) => {
+      expect(() => SessionSeq(value)).toThrow(/SessionSeq must be a non-negative safe integer/)
+      expect(() => SessionLogOffset(value)).toThrow(/SessionLogOffset must be a non-negative safe integer/)
+    },
+  )
+
+  it('keeps event identities separate from log offsets', () => {
+    const session = Session.create(SessionId('typed-positions'))
+    const event = session.append('turn/start', { turn: 1 })
+
+    expect(event.seq).toBe(0)
+    expect(session.firstLiveSeq).toBe(0)
+    expect(session.seq).toBe(1)
+    expectTypeOf(event.seq).toEqualTypeOf<SessionSeqType>()
+    expectTypeOf(session.firstLiveSeq).toEqualTypeOf<SessionLogOffsetType>()
+    expectTypeOf(session.seq).toEqualTypeOf<SessionLogOffsetType>()
+  })
+
+  it('rejects a negative-zero seq at the restored event boundary', () => {
+    const id = SessionId('negative-zero-event')
+    expect(() => Session.fromRestore(id, [{
+      type: 'turn/start', seq: -0, time: 1, data: { turn: 1 },
+    }] as never, {
+      version: 0, id, createdAt: 1, isSeeded: false,
+    }, SessionLogOffset(0))).toThrow(/invalid event envelope/)
+  })
+
+  it('keeps fork lineage outside the logical header integer fields', () => {
+    const source = Session.create(SessionId('source'))
+    source.append('turn/start', { turn: 1 })
+    source.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    const id = SessionId('child')
+    const header: SessionHeader = {
+      version: 0,
+      id,
+      createdAt: 1,
+      isSeeded: true,
+    }
+
+    const child = Session.create(id, source.snapshotEvents(), header, source.seq)
+
+    expect(child.header.isSeeded).toBe(true)
+    expect('seedLength' in child.header).toBe(false)
+    expect(child.inheritedEventCount).toBe(2)
+    expect(child.ownEvents().map(event => event.type)).toEqual(['session/end-seed'])
+    expect(child.isOwnSeq(SessionSeq(1))).toBe(false)
+    expect(child.isOwnSeq(SessionSeq(2))).toBe(true)
+    expect(child.isOwnSeq(SessionSeq(3))).toBe(false)
+
+    const fresh = Session.create(SessionId('fresh'))
+    expect(fresh.header.isSeeded).toBe(false)
+    expect(fresh.inheritedEventCount).toBe(0)
+  })
+
+  it('retains a child-owned constructor-seed suffix after the inherited cut', () => {
+    const parent = Session.create(SessionId('suffix-parent'))
+    parent.append('turn/start', { turn: 1 })
+    parent.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    const assembled = Session.create(SessionId('assembled-seed'), parent.snapshotEvents())
+    assembled.append('request/context', { provider: 'provider', model: 'model' })
+    const id = SessionId('suffix-child')
+
+    const child = Session.create(id, assembled.snapshotEvents(), {
+      version: 0,
+      id,
+      createdAt: 1,
+      isSeeded: true,
+    }, parent.seq)
+
+    expect(child.ownEvents().map(event => event.type)).toEqual([
+      'session/end-seed',
+      'request/context',
+      'session/end-seed',
+    ])
+    expect(child.isOwnSeq(SessionSeq(1))).toBe(false)
+    expect(child.isOwnSeq(SessionSeq(2))).toBe(true)
+    expect(child.isOwnSeq(SessionSeq(3))).toBe(true)
+  })
+
+  it('requires a separately supplied inherited cut for a seeded header', () => {
+    const id = SessionId('missing-cut')
+    expect(() => Session.create(id, [], {
+      version: 0,
+      id,
+      createdAt: 1,
+      isSeeded: true,
+    })).toThrow(/seeded session requires an inherited event count/)
+  })
+
+  it('requires an explicit constructor seed for seeded lineage', () => {
+    const id = SessionId('missing-seed')
+    expect(() => Session.create(id, undefined, {
+      version: 0,
+      id,
+      createdAt: 1,
+      isSeeded: true,
+    }, SessionLogOffset(0))).toThrow(/seeded session requires an explicit constructor seed/)
+  })
+
+  it('requires the exact cut to agree with lineage and log length', () => {
+    const unseededId = SessionId('unseeded-nonzero-cut')
+    expect(() => Session.create(unseededId, [], {
+      version: 0, id: unseededId, createdAt: 1, isSeeded: false,
+    }, SessionLogOffset(1))).toThrow(/unseeded session inherited event count must be 0/)
+
+    const seededId = SessionId('seeded-oversized-cut')
+    expect(() => Session.create(seededId, [], {
+      version: 0, id: seededId, createdAt: 1, isSeeded: true,
+    }, SessionLogOffset(1))).toThrow(/inherited event count exceeds its event log/)
+  })
+
+  it.each([-1, 0.5, Number.MAX_SAFE_INTEGER + 1])(
+    'revalidates a supplied inherited event count (%s)',
+    (value) => {
+      const id = SessionId(`bad-inherited-count-${value}`)
+      expect(() => Session.create(id, [], {
+        version: 0,
+        id,
+        createdAt: 1,
+        isSeeded: true,
+      }, value as SessionLogOffsetType)).toThrow(/SessionLogOffset must be a non-negative safe integer/)
+    },
+  )
+})
diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts
index 09badf180f..790af32632 100644
--- a/packages/core/session/tests/session.spec.ts
+++ b/packages/core/session/tests/session.spec.ts
@@ -7,6 +7,8 @@ import SessionStore, {
   Session,
   SessionEvent,
   SessionId,
+  SessionLogOffset,
+  SessionSeq,
   snapshotSessionEvent,
 } from '@deepseek-ai/dsh-session'
 import type { CreateSessionOptions, SessionEventType, SessionHeader, SessionSurface } from '@deepseek-ai/dsh-session'
@@ -305,20 +307,20 @@ describe('Session', () => {
   it('snapshots message events without validating plugin-owned block details', () => {
     const boundary = snapshotSessionEvent({
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
     })
     expect(boundary).toEqual({
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
     })
 
     const extended = snapshotSessionEvent({
       type: 'user/message',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       surfaceOp: 'append',
       data: {
@@ -374,7 +376,7 @@ describe('Session', () => {
   it('round-trips a non-empty reasoning effort and rejects invalid durable values', () => {
     const valid = {
       type: 'request/header',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: {
         header: {
@@ -403,7 +405,7 @@ describe('Session', () => {
   it('round-trips adapter-default markers and rejects invalid durable values', () => {
     const valid = {
       type: 'request/header',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: {
         header: {
@@ -639,7 +641,7 @@ describe('Session', () => {
   it('rejects an exotic seed event shell before spreading erases its prototype', () => {
     class SeedEvent {
       readonly type = 'turn/start' as const
-      readonly seq = 0
+      readonly seq = SessionSeq(0)
       readonly time = 1
       readonly data = { turn: 1 }
     }
@@ -810,8 +812,8 @@ describe('Session', () => {
   it('rejects exotic surface metadata before cloning can erase its prototype', () => {
     class ReplaceOp {
       readonly op = 'replace' as const
-      readonly start = 0
-      readonly end = 0
+      readonly start = SessionSeq(0)
+      readonly end = SessionSeq(0)
     }
     const session = Session.create(SessionId('append-exotic-metadata'))
 
@@ -892,7 +894,7 @@ describe('Session', () => {
     )).toThrow(/not surface-eligible and cannot carry surfaceOp/)
     expect(() => Session.create(SessionId('non-surface-metadata-seed'), [{
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
       surfaceOp: 'append',
@@ -903,7 +905,7 @@ describe('Session', () => {
   it('deep-freezes seeded and appended event snapshots', () => {
     const seeded = Session.create(SessionId('seed-frozen'), [{
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
     }])
@@ -941,7 +943,8 @@ describe('Session', () => {
       version: SESSION_FORMAT_VERSION,
       id: SessionId('deep-restore'),
       createdAt: 1,
-    })).not.toThrow()
+      isSeeded: false,
+    }, SessionLogOffset(0))).not.toThrow()
 
     let current: unknown = event
     let frozenNodes = 0
@@ -979,11 +982,11 @@ describe('Session', () => {
     const start = session.append('turn/start', { turn: 1 })
     const end = session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
 
-    expect(session.eventAt(0)).toBe(start)
-    expect(session.eventAt(1)).toBe(end)
-    expect(session.eventAt(2)).toBeUndefined()
+    expect(session.eventAt(SessionSeq(0))).toBe(start)
+    expect(session.eventAt(SessionSeq(1))).toBe(end)
+    expect(session.eventAt(SessionSeq(2))).toBeUndefined()
 
-    const range = session.snapshotEvents(1, 2)
+    const range = session.snapshotEvents(SessionLogOffset(1), SessionLogOffset(2))
     expect(range).toEqual([end])
     expect(Object.isFrozen(range)).toBe(true)
 
@@ -998,10 +1001,10 @@ describe('Session', () => {
       createdAt: 123,
       cwd: '/accepted',
       parentSession: SessionId('parent'),
-      seedLength: 2,
+      isSeeded: true,
     }
 
-    const session = Session.create(SessionId('header-owned'), undefined, input)
+    const session = Session.create(SessionId('header-owned'), [], input, SessionLogOffset(0))
     input.cwd = '/caller-mutated'
 
     expect(session.header).toEqual({
@@ -1010,7 +1013,7 @@ describe('Session', () => {
       createdAt: 123,
       cwd: '/accepted',
       parentSession: 'parent',
-      seedLength: 2,
+      isSeeded: true,
     })
     expect(session.header).not.toBe(input)
     expect(Object.isFrozen(session.header)).toBe(true)
@@ -1024,29 +1027,33 @@ describe('Session', () => {
       readonly version = SESSION_FORMAT_VERSION
       readonly id = SessionId('header-invalid')
       readonly createdAt = 123
+      readonly isSeeded = false
     }
 
     expect(() => Session.create(SessionId('header-invalid'), undefined, new ExoticHeader()))
       .toThrow(/not losslessly JSON-serializable/)
-    expect(() => Session.fromRestore(SessionId('header-invalid'), [], new ExoticHeader()))
+    expect(() => Session.fromRestore(SessionId('header-invalid'), [], new ExoticHeader(), SessionLogOffset(0)))
       .toThrow(/not a plain JSON record/)
     for (const header of [null, 1, []]) {
       expect(() => Session.fromRestore(
         SessionId('header-invalid'),
         [],
         header as unknown as SessionHeader,
+        SessionLogOffset(0),
       )).toThrow(/not a plain JSON record/)
     }
     expect(() => Session.create(SessionId('header-invalid'), undefined, {
       version: SESSION_FORMAT_VERSION,
       id: SessionId('header-invalid'),
       createdAt: 123,
+      isSeeded: false,
       parentSession: 1n,
     } as unknown as SessionHeader)).toThrow(/not losslessly JSON-serializable/)
     expect(() => Session.create(SessionId('header-invalid'), undefined, {
       version: SESSION_FORMAT_VERSION,
       id: SessionId('other'),
       createdAt: 123,
+      isSeeded: false,
     })).toThrow(/does not match session id/)
   })
 
@@ -1055,6 +1062,7 @@ describe('Session', () => {
       version: SESSION_FORMAT_VERSION,
       id: SessionId('header-shape'),
       createdAt: 123,
+      isSeeded: false,
     }
     const cases: Array<{ header: unknown; error: RegExp }> = [
       { header: 1, error: /not a plain JSON record/ },
@@ -1064,9 +1072,8 @@ describe('Session', () => {
       { header: { ...base, cwd: 1 }, error: /header cwd must be a string/ },
       { header: { ...base, cwd: 'relative' }, error: /header cwd must be an absolute path/ },
       { header: { ...base, parentSession: 1 }, error: /header parentSession must be a string/ },
-      { header: { ...base, seedLength: '1' }, error: /seedLength must be a non-negative safe integer/ },
-      { header: { ...base, seedLength: 0.5 }, error: /seedLength must be a non-negative safe integer/ },
-      { header: { ...base, seedLength: -1 }, error: /seedLength must be a non-negative safe integer/ },
+      { header: { ...base, isSeeded: 'yes' }, error: /isSeeded must be a boolean/ },
+      { header: { ...base, seedLength: 1 }, error: /invalid field "seedLength"/ },
     ]
 
     for (const { header, error } of cases) {
@@ -1074,6 +1081,20 @@ describe('Session', () => {
     }
   })
 
+  it('retains opaque logical header metadata except the physical v0 seed field', () => {
+    const id = SessionId('header-extension')
+    const session = Session.create(id, undefined, {
+      version: SESSION_FORMAT_VERSION,
+      id,
+      createdAt: 123,
+      isSeeded: false,
+      extension: { value: 'kept' },
+    } as SessionHeader)
+
+    expect((session.header as SessionHeader & { extension: { value: string } }).extension)
+      .toEqual({ value: 'kept' })
+  })
+
   it('rejects seed records with invalid fixed-envelope fields', () => {
     const base = {
       type: 'turn/start',
@@ -1275,7 +1296,7 @@ describe('SessionStore', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('plain'))
-    expect(session.header).toMatchObject({ version: SESSION_FORMAT_VERSION, id: 'plain' })
+    expect(session.header).toMatchObject({ version: SESSION_FORMAT_VERSION, id: 'plain', isSeeded: false })
     expect(Number.isSafeInteger(session.header.createdAt)).toBe(true)
     expect(session.header.cwd).toBeUndefined()
     expect(session.header.parentSession).toBeUndefined()
@@ -1292,6 +1313,7 @@ describe('SessionStore', () => {
       id: 'child',
       cwd: '/work/project',
       parentSession: 'parent',
+      isSeeded: false,
     })
   })
 
@@ -1320,9 +1342,7 @@ describe('SessionStore', () => {
       { meta: { createdAt: 1.5 }, error: /header createdAt must be a non-negative safe integer/ },
       { meta: { createdAt: -1 }, error: /header createdAt must be a non-negative safe integer/ },
       { meta: { createdAt: Number.MAX_SAFE_INTEGER + 1 }, error: /header createdAt must be a non-negative safe integer/ },
-      { meta: { seedLength: '1' }, error: /seedLength must be a non-negative safe integer/ },
-      { meta: { seedLength: 0.5 }, error: /seedLength must be a non-negative safe integer/ },
-      { meta: { seedLength: -1 }, error: /seedLength must be a non-negative safe integer/ },
+      { meta: { isSeeded: 'yes' }, error: /isSeeded must be a boolean/ },
       { meta: { origin: 'fork' }, error: /origin must be "subagent"/ },
       { meta: { delegationDepth: '1' }, error: /delegationDepth must be a non-negative safe integer/ },
       { meta: { delegationDepth: 0.5 }, error: /delegationDepth must be a non-negative safe integer/ },
@@ -1348,7 +1368,7 @@ describe('SessionStore', () => {
 
   it('a bare Session() constructed without the store still exposes a current-version header', () => {
     const session = Session.create(SessionId('bare'))
-    expect(session.header).toMatchObject({ version: SESSION_FORMAT_VERSION, id: 'bare' })
+    expect(session.header).toMatchObject({ version: SESSION_FORMAT_VERSION, id: 'bare', isSeeded: false })
     expect(typeof session.header.createdAt).toBe('number')
   })
 
@@ -1507,8 +1527,8 @@ describe('SessionStore', () => {
         },
       }),
     }, {
-      surfaceOp: { op: 'replace', start: 2, end: 2 },
-      sourceEventSeqs: [2],
+      surfaceOp: { op: 'replace', start: SessionSeq(2), end: SessionSeq(2) },
+      sourceEventSeqs: [SessionSeq(2)],
     })).toThrow('reject surface candidate')
 
     expect(session.snapshotEvents()).toHaveLength(3)
diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts
index 3a92246a85..d89c77d851 100644
--- a/packages/core/session/tests/surface.spec.ts
+++ b/packages/core/session/tests/surface.spec.ts
@@ -3,6 +3,8 @@ import type { SessionEvent, SurfaceEvent, SurfaceEventType } from '@deepseek-ai/
 import {
   Session,
   SessionId,
+  SessionLogOffset,
+  SessionSeq,
   foldSurface,
   isAppendSurfaceEvent,
   isReplacementSurfaceEvent,
@@ -19,6 +21,18 @@ import {
   MessageId,
 } from '@deepseek-ai/dsh-llm'
 
+type TestSurfaceOp = 'append' | { op: 'replace'; start: number; end: number }
+
+function surfaceOp(value: TestSurfaceOp): SurfaceEvent['surfaceOp'] {
+  return value === 'append'
+    ? value
+    : { op: 'replace', start: SessionSeq(value.start), end: SessionSeq(value.end) }
+}
+
+function sourceSeqs(...values: number[]) {
+  return values.map(SessionSeq)
+}
+
 /** Build a minimal session with turn boundaries and a single user message. */
 function surfaceSession(): Session {
   const s = Session.create(SessionId('ss'))
@@ -41,7 +55,7 @@ function surfaceSession(): Session {
   return s
 }
 
-function provenanceEvent(seq: number, sourceEventSeqs: unknown): SessionEvent {
+function provenanceEvent(seq: SessionSeq, sourceEventSeqs: unknown): SessionEvent {
   return {
     type: 'user/message',
     seq,
@@ -55,9 +69,9 @@ function provenanceEvent(seq: number, sourceEventSeqs: unknown): SessionEvent {
 }
 
 function toolResultEvent(
-  seq: number,
+  seq: SessionSeq,
   callId: string,
-  surfaceOp: SurfaceEvent['surfaceOp'] = 'append',
+  op: TestSurfaceOp = 'append',
   sourceEventSeqs?: number[],
 ): SessionEvent {
   return {
@@ -73,19 +87,19 @@ function toolResultEvent(
         isError: false,
       }),
     },
-    surfaceOp,
-    ...sourceEventSeqs === undefined ? {} : { sourceEventSeqs },
+    surfaceOp: surfaceOp(op),
+    ...sourceEventSeqs === undefined ? {} : { sourceEventSeqs: sourceSeqs(...sourceEventSeqs) },
   }
 }
 
 describe('foldSurface source-event references', () => {
   it('accepts absent or valid source-event references and complete replacement coverage', () => {
     const events = [
-      provenanceEvent(0, undefined),
-      provenanceEvent(1, undefined),
+      provenanceEvent(SessionSeq(0), undefined),
+      provenanceEvent(SessionSeq(1), undefined),
       {
-        ...provenanceEvent(2, [0, 1]),
-        surfaceOp: { op: 'replace', start: 0, end: 1 },
+        ...provenanceEvent(SessionSeq(2), [0, 1]),
+        surfaceOp: surfaceOp({ op: 'replace', start: 0, end: 1 }),
       },
     ] as SessionEvent[]
     expect(() => foldSurface(events)).not.toThrow()
@@ -94,10 +108,10 @@ describe('foldSurface source-event references', () => {
   it('rejects source-event references on a non-surface event', () => {
     const event = {
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
-      sourceEventSeqs: [0],
+      sourceEventSeqs: sourceSeqs(0),
     } as unknown as SessionEvent
     expect(() => foldSurface([event])).toThrow(/cannot carry sourceEventSeqs/)
   })
@@ -105,7 +119,7 @@ describe('foldSurface source-event references', () => {
   it('accepts an explicit empty source-event list on an assistant message', () => {
     const event = {
       type: 'assistant/message',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 0,
       data: {
         turn: 1,
@@ -126,19 +140,19 @@ describe('foldSurface source-event references', () => {
   })
 
   it.each([
-    ['a non-array', [{ ...provenanceEvent(0, undefined), sourceEventSeqs: 'invalid' }], /must be an array/],
-    ['an empty array', [provenanceEvent(0, [])], /must not be empty/],
-    ['duplicates', [provenanceEvent(0, undefined), provenanceEvent(1, [0, 0])], /must not contain duplicates/],
-    ['a sparse array', [provenanceEvent(0, Array<number>(1))], /densely contain/],
-    ['a non-number', [{ ...provenanceEvent(0, undefined), sourceEventSeqs: ['0'] }], /non-negative safe integers/],
-    ['a fractional number', [provenanceEvent(0, [0.5])], /non-negative safe integers/],
-    ['a negative number', [provenanceEvent(0, [-1])], /non-negative safe integers/],
-    ['a self reference', [provenanceEvent(0, [0])], /must reference earlier events/],
-    ['a non-contiguous event seq', [provenanceEvent(0, undefined), provenanceEvent(2, [1])], /seq 2 is not contiguous; expected 1/],
+    ['a non-array', [{ ...provenanceEvent(SessionSeq(0), undefined), sourceEventSeqs: 'invalid' }], /must be an array/],
+    ['an empty array', [provenanceEvent(SessionSeq(0), [])], /must not be empty/],
+    ['duplicates', [provenanceEvent(SessionSeq(0), undefined), provenanceEvent(SessionSeq(1), [0, 0])], /must not contain duplicates/],
+    ['a sparse array', [provenanceEvent(SessionSeq(0), Array<number>(1))], /densely contain/],
+    ['a non-number', [{ ...provenanceEvent(SessionSeq(0), undefined), sourceEventSeqs: ['0'] }], /non-negative safe integers/],
+    ['a fractional number', [provenanceEvent(SessionSeq(0), [0.5])], /non-negative safe integers/],
+    ['a negative number', [provenanceEvent(SessionSeq(0), [-1])], /non-negative safe integers/],
+    ['a self reference', [provenanceEvent(SessionSeq(0), [0])], /must reference earlier events/],
+    ['a non-contiguous event seq', [provenanceEvent(SessionSeq(0), undefined), provenanceEvent(SessionSeq(2), [1])], /seq 2 is not contiguous; expected 1/],
     ['incomplete replacement coverage', [
-      provenanceEvent(0, undefined),
-      provenanceEvent(1, undefined),
-      { ...provenanceEvent(2, [0]), surfaceOp: { op: 'replace', start: 0, end: 1 } },
+      provenanceEvent(SessionSeq(0), undefined),
+      provenanceEvent(SessionSeq(1), undefined),
+      { ...provenanceEvent(SessionSeq(2), [0]), surfaceOp: { op: 'replace', start: 0, end: 1 } },
     ], /missing 1/],
   ] as const)(
     'rejects %s',
@@ -151,25 +165,25 @@ describe('foldSurface source-event references', () => {
 describe('foldSurface tool-result rewrites', () => {
   it('rejects a replacement spanning multiple current nodes', () => {
     const events = [
-      provenanceEvent(0, undefined),
-      provenanceEvent(1, undefined),
-      toolResultEvent(2, 'rewrite', { op: 'replace', start: 0, end: 1 }, [0, 1]),
+      provenanceEvent(SessionSeq(0), undefined),
+      provenanceEvent(SessionSeq(1), undefined),
+      toolResultEvent(SessionSeq(2), 'rewrite', { op: 'replace', start: 0, end: 1 }, [0, 1]),
     ]
     expect(() => foldSurface(events)).toThrow(/must rewrite exactly one current node/)
   })
 
   it('rejects a replacement targeting a non-result node', () => {
     const events = [
-      provenanceEvent(0, undefined),
-      toolResultEvent(1, 'rewrite', { op: 'replace', start: 0, end: 0 }, [0]),
+      provenanceEvent(SessionSeq(0), undefined),
+      toolResultEvent(SessionSeq(1), 'rewrite', { op: 'replace', start: 0, end: 0 }, [0]),
     ]
     expect(() => foldSurface(events)).toThrow(/must target a current tool\/result/)
   })
 
   it('rejects changes outside tool-result content', () => {
     const events = [
-      toolResultEvent(0, 'original'),
-      toolResultEvent(1, 'changed', { op: 'replace', start: 0, end: 0 }, [0]),
+      toolResultEvent(SessionSeq(0), 'original'),
+      toolResultEvent(SessionSeq(1), 'changed', { op: 'replace', start: 0, end: 0 }, [0]),
     ]
     expect(() => foldSurface(events)).toThrow(/may change only content/)
   })
@@ -178,12 +192,12 @@ describe('foldSurface tool-result rewrites', () => {
     ['toolCallId', { toolCallId: ToolCallId('changed') }],
     ['isError', { isError: true }],
   ] as const)('rejects a replacement that changes the result block %s', (_field, patch) => {
-    const original = toolResultEvent(0, 'original')
+    const original = toolResultEvent(SessionSeq(0), 'original')
     const data = original.data as Extract<SessionEvent, { type: 'tool/result' }>['data']
     const result = data.message.content[0]
     const replacement = {
       ...original,
-      seq: 1,
+      seq: SessionSeq(1),
       time: 1,
       data: {
         ...data,
@@ -192,15 +206,15 @@ describe('foldSurface tool-result rewrites', () => {
           content: [{ ...result, ...patch }] as [typeof result],
         }),
       },
-      surfaceOp: { op: 'replace', start: 0, end: 0 },
-      sourceEventSeqs: [0],
+      surfaceOp: surfaceOp({ op: 'replace', start: 0, end: 0 }),
+      sourceEventSeqs: sourceSeqs(0),
     } as SessionEvent
     expect(() => foldSurface([original, replacement])).toThrow(/may change only content/)
   })
 
   it('compares array-valued rest fields structurally (meta arrays: equal accepted, drifted rejected)', () => {
-    const withMeta = (seq: number, meta: unknown, surfaceOp: SurfaceEvent['surfaceOp'] = 'append', sourceEventSeqs?: number[]): SessionEvent => {
-      const event = toolResultEvent(seq, 'c-meta', surfaceOp, sourceEventSeqs)
+    const withMeta = (seq: SessionSeq, meta: unknown, op: TestSurfaceOp = 'append', sourceEventSeqs?: number[]): SessionEvent => {
+      const event = toolResultEvent(SessionSeq(seq), 'c-meta', op, sourceEventSeqs)
       const data = event.data as Extract<SessionEvent, { type: 'tool/result' }>['data']
       return {
         ...event,
@@ -213,28 +227,28 @@ describe('foldSurface tool-result rewrites', () => {
     }
     // Structurally equal arrays (fresh references) pass the rest-field equality.
     expect(() => foldSurface([
-      withMeta(0, { tags: ['a', { n: 1 }] }),
-      withMeta(1, { tags: ['a', { n: 1 }] }, { op: 'replace', start: 0, end: 0 }, [0]),
+      withMeta(SessionSeq(0), { tags: ['a', { n: 1 }] }),
+      withMeta(SessionSeq(1), { tags: ['a', { n: 1 }] }, { op: 'replace', start: 0, end: 0 }, [0]),
     ])).not.toThrow()
     // Same length, drifted element: the array branch must reject.
     expect(() => foldSurface([
-      withMeta(0, { tags: ['a'] }),
-      withMeta(1, { tags: ['b'] }, { op: 'replace', start: 0, end: 0 }, [0]),
+      withMeta(SessionSeq(0), { tags: ['a'] }),
+      withMeta(SessionSeq(1), { tags: ['b'] }, { op: 'replace', start: 0, end: 0 }, [0]),
     ])).toThrow(/may change only content/)
     // Array vs non-array on one side: the mixed-shape guard rejects.
     expect(() => foldSurface([
-      withMeta(0, { tags: ['a'] }),
-      withMeta(1, { tags: 'a' }, { op: 'replace', start: 0, end: 0 }, [0]),
+      withMeta(SessionSeq(0), { tags: ['a'] }),
+      withMeta(SessionSeq(1), { tags: 'a' }, { op: 'replace', start: 0, end: 0 }, [0]),
     ])).toThrow(/may change only content/)
     // Same key count, different key names: the hasOwn branch rejects.
     expect(() => foldSurface([
-      withMeta(0, { left: 1 }),
-      withMeta(1, { right: 1 }, { op: 'replace', start: 0, end: 0 }, [0]),
+      withMeta(SessionSeq(0), { left: 1 }),
+      withMeta(SessionSeq(1), { right: 1 }, { op: 'replace', start: 0, end: 0 }, [0]),
     ])).toThrow(/may change only content/)
     // Different key counts: the key-length branch rejects.
     expect(() => foldSurface([
-      withMeta(0, { one: 1 }),
-      withMeta(1, { one: 1, two: 2 }, { op: 'replace', start: 0, end: 0 }, [0]),
+      withMeta(SessionSeq(0), { one: 1 }),
+      withMeta(SessionSeq(1), { one: 1, two: 2 }, { op: 'replace', start: 0, end: 0 }, [0]),
     ])).toThrow(/may change only content/)
   })
 })
@@ -243,47 +257,47 @@ describe('SurfaceManager', () => {
   it('folds a contiguous window without materializing earlier event sequences', () => {
     const baseSeq = 400_000
     const events = [
-      provenanceEvent(baseSeq, undefined),
-      provenanceEvent(baseSeq + 1, undefined),
+      provenanceEvent(SessionSeq(baseSeq), undefined),
+      provenanceEvent(SessionSeq(baseSeq + 1), undefined),
       {
-        ...provenanceEvent(baseSeq + 2, [baseSeq]),
-        surfaceOp: { op: 'replace', start: baseSeq, end: baseSeq },
+        ...provenanceEvent(SessionSeq(baseSeq + 2), [baseSeq]),
+        surfaceOp: surfaceOp({ op: 'replace', start: baseSeq, end: baseSeq }),
       },
     ] as SessionEvent[]
 
-    const surface = new SurfaceManager(events, baseSeq)
+    const surface = new SurfaceManager(events, SessionLogOffset(baseSeq))
     expect(surface.nodes).toEqual([baseSeq + 2, baseSeq + 1])
     expect(surface.replaceGeneration).toBe(1)
   })
 
   it('validates tool-result rewrites against a nonzero window offset', () => {
     const baseSeq = 400_000
-    const original = toolResultEvent(baseSeq, 'call')
+    const original = toolResultEvent(SessionSeq(baseSeq), 'call')
     const events: SessionEvent[] = [
       original,
       {
         ...original,
-        seq: baseSeq + 1,
+        seq: SessionSeq(baseSeq + 1),
         time: baseSeq + 1,
-        surfaceOp: { op: 'replace' as const, start: baseSeq, end: baseSeq },
-        sourceEventSeqs: [baseSeq],
+        surfaceOp: surfaceOp({ op: 'replace', start: baseSeq, end: baseSeq }),
+        sourceEventSeqs: sourceSeqs(baseSeq),
       } as SessionEvent,
     ]
 
-    expect(new SurfaceManager(events, baseSeq).nodes).toEqual([baseSeq + 1])
+    expect(new SurfaceManager(events, SessionLogOffset(baseSeq)).nodes).toEqual([baseSeq + 1])
   })
 
   it('rejects a replacement that crosses a loaded window head', () => {
     const baseSeq = 400_000
     const events = [
-      provenanceEvent(baseSeq, undefined),
+      provenanceEvent(SessionSeq(baseSeq), undefined),
       {
-        ...provenanceEvent(baseSeq + 1, [baseSeq - 1, baseSeq]),
-        surfaceOp: { op: 'replace', start: baseSeq - 1, end: baseSeq },
+        ...provenanceEvent(SessionSeq(baseSeq + 1), [baseSeq - 1, baseSeq]),
+        surfaceOp: surfaceOp({ op: 'replace', start: baseSeq - 1, end: baseSeq }),
       },
     ] as SessionEvent[]
 
-    expect(() => new SurfaceManager(events, baseSeq).nodes)
+    expect(() => new SurfaceManager(events, SessionLogOffset(baseSeq)).nodes)
       .toThrow(`surface replace: start seq ${baseSeq - 1} not found in surface`)
   })
 
@@ -305,7 +319,7 @@ describe('SurfaceManager', () => {
           ...{ provider: 'mock', model: 'mock' },
         },
       }),
-    }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
+    }, { surfaceOp: surfaceOp({ op: 'replace', start: 0, end: 0 }), sourceEventSeqs: sourceSeqs(0) })
     s.append('assistant/message', {
       turn: 1, step: 2,
       message: createMessage({
@@ -316,7 +330,7 @@ describe('SurfaceManager', () => {
           ...{ provider: 'mock', model: 'mock' },
         },
       }),
-    }, { surfaceOp: { op: 'replace', start: 2, end: 1 }, sourceEventSeqs: [2, 1] })
+    }, { surfaceOp: surfaceOp({ op: 'replace', start: 2, end: 1 }), sourceEventSeqs: sourceSeqs(2, 1) })
 
     const folded = foldSurface(s.snapshotEvents())
     expect(folded.nodes).toEqual(s.surface.nodes)
@@ -324,8 +338,8 @@ describe('SurfaceManager', () => {
       { seq: 2, start: 0, end: 0, shadowedSeqs: [0] },
       { seq: 3, start: 2, end: 1, shadowedSeqs: [2, 1] },
     ])
-    folded.nodes[0] = 99
-    folded.replacements[0]!.shadowedSeqs.push(99)
+    folded.nodes[0] = SessionSeq(99)
+    folded.replacements[0]!.shadowedSeqs.push(SessionSeq(99))
     expect(s.surface.nodes).toEqual([3])
     expect(foldSurface(s.snapshotEvents()).nodes).toEqual([3])
     expect(foldSurface(s.snapshotEvents()).replacements[0]!.shadowedSeqs).toEqual([0])
@@ -346,7 +360,7 @@ describe('SurfaceManager', () => {
           ...{ provider: 'mock', model: 'mock' },
         },
       }),
-    }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
+    }, { surfaceOp: surfaceOp({ op: 'replace', start: 0, end: 0 }), sourceEventSeqs: sourceSeqs(0) })
 
     expect(s.surface.nodes).toEqual([1])
     const manager = s.surface as unknown as { _state: object }
@@ -358,8 +372,8 @@ describe('SurfaceManager', () => {
 
   it('foldSurface reports the same invalid replacement failures as the incremental manager', () => {
     const events = [
-      provenanceEvent(0, undefined),
-      { ...provenanceEvent(1, [0]), surfaceOp: { op: 'replace', start: 42, end: 0 } },
+      provenanceEvent(SessionSeq(0), undefined),
+      { ...provenanceEvent(SessionSeq(1), [0]), surfaceOp: { op: 'replace', start: 42, end: 0 } },
     ] as SessionEvent[]
 
     expect(() => foldSurface(events)).toThrow(/start seq 42 not found/)
@@ -367,6 +381,15 @@ describe('SurfaceManager', () => {
       .toThrow(/start seq 42 not found/)
   })
 
+  it('rejects negative-zero replacement event sequences', () => {
+    const event = {
+      ...provenanceEvent(SessionSeq(0), [0]),
+      surfaceOp: { op: 'replace', start: -0, end: -0 },
+    } as SessionEvent
+
+    expect(() => foldSurface([event])).toThrow(/invalid replace surfaceOp/)
+  })
+
   it('leaves incremental state unchanged when candidate validation fails', () => {
     const s = Session.create(SessionId('atomic-validation'))
     s.append('user/message', createUserMessage({
@@ -391,7 +414,7 @@ describe('SurfaceManager', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 0, end: 0 } },
+      { surfaceOp: surfaceOp({ op: 'replace', start: 0, end: 0 }) },
     )).toThrow(/missing 0/)
 
     expect(s.snapshotEvents()).toHaveLength(1)
@@ -412,7 +435,7 @@ describe('SurfaceManager', () => {
   it('foldSurface rejects a surface-eligible event without its mandatory marker', () => {
     const malformed: SessionEvent = {
       type: 'user/message',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: createUserMessage({
         content: [{ type: 'text', text: 'hidden' }], source: { kind: 'user' },
@@ -426,7 +449,7 @@ describe('SurfaceManager', () => {
   it('foldSurface rejects surfaceOp on a non-surface event', () => {
     const malformed = {
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
       surfaceOp: 'append',
@@ -498,7 +521,7 @@ describe('SurfaceManager', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] },
+      { surfaceOp: surfaceOp({ op: 'replace', start: 1, end: 2 }), sourceEventSeqs: sourceSeqs(1, 2) },
     )
     expect(s.surface.nodes).toEqual([4])
   })
@@ -527,7 +550,7 @@ describe('SurfaceManager', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 0, end: 1 }, sourceEventSeqs: [0, 1] },
+      { surfaceOp: surfaceOp({ op: 'replace', start: 0, end: 1 }), sourceEventSeqs: sourceSeqs(0, 1) },
     ) // seq 3
     expect(s.surface.nodes).toEqual([3, 2])
   })
@@ -553,7 +576,7 @@ describe('SurfaceManager', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
+      { surfaceOp: surfaceOp({ op: 'replace', start: 1, end: 1 }), sourceEventSeqs: sourceSeqs(1) },
     ) // seq 2
     expect(s.surface.nodes).toEqual([0, 2])
   })
@@ -575,7 +598,7 @@ describe('SurfaceManager', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 5, end: 0 }, sourceEventSeqs: [0] },
+      { surfaceOp: surfaceOp({ op: 'replace', start: 5, end: 0 }), sourceEventSeqs: sourceSeqs(0) },
     )).toThrow(/surface replace: start seq 5 not found/)
   })
 
@@ -596,7 +619,7 @@ describe('SurfaceManager', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 0, end: 99 }, sourceEventSeqs: [0] },
+      { surfaceOp: surfaceOp({ op: 'replace', start: 0, end: 99 }), sourceEventSeqs: sourceSeqs(0) },
     )).toThrow(/surface replace: end seq 99 not found/)
   })
 
@@ -621,7 +644,7 @@ describe('SurfaceManager', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 1, end: 0 }, sourceEventSeqs: [1, 0] },
+      { surfaceOp: surfaceOp({ op: 'replace', start: 1, end: 0 }), sourceEventSeqs: sourceSeqs(1, 0) },
     )).toThrow(/start seq 1.*after end seq 0/)
   })
 
@@ -630,7 +653,7 @@ describe('SurfaceManager', () => {
     s.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'source' }], source: { kind: 'user' },
     }), { surfaceOp: 'append' })
-    const sources = [0]
+    const sources = sourceSeqs(0)
     s.append('assistant/message', {
       turn: 1, step: 1,
       message: createMessage({
@@ -643,8 +666,8 @@ describe('SurfaceManager', () => {
       }),
     }, { surfaceOp: 'append', sourceEventSeqs: sources })
     // Mutate caller's array after append.
-    sources.push(1)
-    sources[0] = 99
+    sources.push(SessionSeq(1))
+    sources[0] = SessionSeq(99)
     const logged = s.snapshotEvents()[1]! as SurfaceEvent
     expect(logged.sourceEventSeqs).toEqual([0])
   })
@@ -673,7 +696,7 @@ describe('SurfaceManager', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
+      { surfaceOp: surfaceOp({ op: 'replace', start: 1, end: 1 }), sourceEventSeqs: sourceSeqs(1) },
     ) // seq 3
     expect(s.surface.nodes).toEqual([0, 3, 2])
   })
@@ -683,7 +706,7 @@ describe('SurfaceManager', () => {
     s.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'a' }], source: { kind: 'user' },
     }), { surfaceOp: 'append' })
-    const op = { op: 'replace' as const, start: 0, end: 0 }
+    const op = { op: 'replace' as const, start: SessionSeq(0), end: SessionSeq(0) }
     s.append('assistant/message', {
       turn: 1, step: 1,
       message: createMessage({
@@ -694,9 +717,9 @@ describe('SurfaceManager', () => {
           ...{ provider: 'mock', model: 'mock' },
         },
       }),
-    }, { surfaceOp: op, sourceEventSeqs: [0] })
+    }, { surfaceOp: op, sourceEventSeqs: sourceSeqs(0) })
     // Mutate caller's object after append.
-    op.start = 99
+    op.start = SessionSeq(99)
     const logged = s.snapshotEvents()[1]! as SurfaceEvent
     expect(logged.surfaceOp).toEqual({ op: 'replace', start: 0, end: 0 })
   })
@@ -752,7 +775,7 @@ describe('deriveMessages with surface', () => {
           ...{ provider: 'mock', model: 'mock' },
         },
       }),
-    }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
+    }, { surfaceOp: surfaceOp({ op: 'replace', start: 0, end: 0 }), sourceEventSeqs: sourceSeqs(0) })
     // Only the compaction node is visible.
     const messages = s.deriveMessages()
     expect(messages).toHaveLength(1)
@@ -792,7 +815,7 @@ describe('Session.append surface opts', () => {
           },
         }),
       },
-      { surfaceOp: 'append', sourceEventSeqs: [0, 1] },
+      { surfaceOp: 'append', sourceEventSeqs: sourceSeqs(0, 1) },
     )
     expect(event.sourceEventSeqs).toEqual([0, 1])
     expect(event.surfaceOp).toBe('append')
@@ -806,9 +829,9 @@ describe('Session.append surface opts', () => {
     // but _deriveOneMessage returns null for it, so the surface derivation path's
     // null-check is exercised — the node is on the surface yet produces no message.
     const seed: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
-      { type: 'assistant/message', seq: 2, time: 3, data: {
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'step/start', seq: SessionSeq(1), time: 2, data: { turn: 1, step: 1 } },
+      { type: 'assistant/message', seq: SessionSeq(2), time: 3, data: {
         turn: 1, step: 1,
         message: createMessage({
           role: 'assistant',
@@ -819,8 +842,8 @@ describe('Session.append surface opts', () => {
           },
         }),
       }, surfaceOp: 'append' },
-      { 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' } } },
+      { type: 'step/end', seq: SessionSeq(3), time: 4, data: { turn: 1, step: 1 } },
+      { type: 'turn/end', seq: SessionSeq(4), time: 5, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
     const s = Session.create(SessionId('nomessage'), seed)
     // The empty assistant/message is on the surface but _deriveOneMessage returns null for it.
@@ -856,14 +879,14 @@ describe('Session.append surface opts', () => {
     // surface-eligible type but with no surfaceOp must NOT narrow to a
     // SurfaceEvent — it would otherwise be silently dropped from the surface.
     const noMarker: SessionEvent = {
-      type: 'user/message', seq: 0, time: 1,
+      type: 'user/message', seq: SessionSeq(0), time: 1,
       data: createUserMessage({
         content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
       }),
     }
     expect(isSurfaceEvent(noMarker)).toBe(false)
     // A non-surface type is rejected too (the type gate).
-    const boundary: SessionEvent = { type: 'turn/start', seq: 1, time: 1, data: { turn: 1 } }
+    const boundary: SessionEvent = { type: 'turn/start', seq: SessionSeq(1), time: 1, data: { turn: 1 } }
     expect(isSurfaceEvent(boundary)).toBe(false)
     // A properly-marked surface event narrows.
     const marked = { ...noMarker, surfaceOp: 'append' } as SurfaceEvent
@@ -898,7 +921,7 @@ describe('surface type guards', () => {
     // optional on SessionEvent, so this is a representable runtime value.
     const markerless: SessionEvent = {
       type: 'user/message',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 0,
       data: createUserMessage({
         content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
@@ -912,7 +935,7 @@ describe('surface type guards', () => {
     const s = surfaceSession()
     s.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'checkpoint' }], source: { kind: 'plugin', plugin: 'compact' },
-    }), { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] })
+    }), { surfaceOp: surfaceOp({ op: 'replace', start: 1, end: 2 }), sourceEventSeqs: sourceSeqs(1, 2) })
     const appended = s.snapshotEvents().find(e => e.type === 'user/message')!
     const replacement = s.snapshotEvents().at(-1)!
 
@@ -929,7 +952,7 @@ describe('surface type guards', () => {
     // all: it never entered the surface.
     const markerless: SessionEvent = {
       type: 'user/message',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 0,
       data: createUserMessage({
         content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
diff --git a/packages/experimental/agent-team/src/mailbox.ts b/packages/experimental/agent-team/src/mailbox.ts
index 11f969edf8..0f71a4da37 100644
--- a/packages/experimental/agent-team/src/mailbox.ts
+++ b/packages/experimental/agent-team/src/mailbox.ts
@@ -308,8 +308,7 @@ export class TeamMailbox {
 
   /** Whether a target Session already contains the durable message identity. */
   private targetRecorded(session: Session, messageId: TeamMessageId): boolean {
-    const suffix = session.snapshotEvents(session.header.seedLength ?? 0)
-    return messageAccepted(suffix, message => message.source.kind === 'team-message'
+    return messageAccepted(session.ownEvents(), message => message.source.kind === 'team-message'
       && message.source.messageId === messageId)
   }
 
@@ -329,7 +328,7 @@ export class TeamMailbox {
   ): Promise<boolean | undefined> {
     try {
       const stored = await this.ctx.sessionPersistence.inspect(targetId, signal)
-      const suffix = stored.events.slice(stored.meta.seedLength ?? 0)
+      const suffix = stored.events.slice(stored.inheritedEventCount)
       return messageAccepted(suffix, message => message.source.kind === 'team-message'
         && message.source.messageId === messageId)
     } catch (error: unknown) {
diff --git a/packages/experimental/agent-team/src/roster.ts b/packages/experimental/agent-team/src/roster.ts
index 802d0b4a2d..5035d2209a 100644
--- a/packages/experimental/agent-team/src/roster.ts
+++ b/packages/experimental/agent-team/src/roster.ts
@@ -346,7 +346,7 @@ export class TeamRoster {
       const session = this.ctx.sessions.get(childId)
       if (session === undefined) {
         const stored = await this.ctx.sessionPersistence.inspect(childId, signal)
-        const suffix = stored.events.slice(stored.meta.seedLength ?? 0)
+        const suffix = stored.events.slice(stored.inheritedEventCount)
         if (messageAccepted(suffix, message => message.id === messageId)) return
         throw new TeamError(
           `teammate "${childId}" initial prompt was not durably accepted`,
@@ -374,7 +374,7 @@ export class TeamRoster {
       try {
         signal.throwIfAborted()
         await this.ctx.sessions.flush(session)
-        const suffix = session.snapshotEvents(session.header.seedLength ?? 0)
+        const suffix = session.ownEvents()
         if (messageAccepted(suffix, message => message.id === messageId)) return
         if (this.ctx.sessions.get(childId) !== session) continue
         await progress.promise
@@ -398,7 +398,7 @@ export class TeamRoster {
       let failure = 'provisioning did not leave a resumable child Session'
       try {
         const loaded = await this.ctx.sessionPersistence.inspect(member.id, signal)
-        const suffix = loaded.events.slice(loaded.meta.seedLength ?? 0)
+        const suffix = loaded.events.slice(loaded.inheritedEventCount)
         const descriptor = foldSubagentDescriptor(suffix)
         const acceptedInitialPrompt = messageAccepted(suffix, message => message.source.kind === 'user')
         if (loaded.meta.parentSession === root.id
@@ -481,6 +481,6 @@ export class TeamRoster {
 
   /** Whether a Session's own suffix identifies a provider-owned subagent child. */
   private subagentDescriptor(agent: Agent): boolean {
-    return foldSubagentDescriptor(agent.session.snapshotEvents(agent.session.header.seedLength ?? 0)) !== undefined
+    return foldSubagentDescriptor(agent.session.ownEvents()) !== undefined
   }
 }
diff --git a/packages/experimental/agent-team/tests/persistence.spec.ts b/packages/experimental/agent-team/tests/persistence.spec.ts
index 9c85709e2e..fb115719aa 100644
--- a/packages/experimental/agent-team/tests/persistence.spec.ts
+++ b/packages/experimental/agent-team/tests/persistence.spec.ts
@@ -133,7 +133,7 @@ function persistedChild(
   }))
   const child = ctx.sessions.create(childId, {
     seed,
-    meta: { parentSession: rootId, seedLength: 0, origin: 'subagent' },
+    meta: { parentSession: rootId, origin: 'subagent' },
   })
   child.append('agent/inbox/spliced', {
     target: 'next-turn',
diff --git a/packages/experimental/agent-team/tests/projection-events.spec.ts b/packages/experimental/agent-team/tests/projection-events.spec.ts
index 3cd6b6103c..b2f9911d3a 100644
--- a/packages/experimental/agent-team/tests/projection-events.spec.ts
+++ b/packages/experimental/agent-team/tests/projection-events.spec.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionEventMap, SessionEventType } from '@deepseek-ai/dsh-session'
 import { teamProjectionDefinition } from '../src/projection.ts'
 import type { TeamProjectionState, TeamState } from '../src/projection.ts'
@@ -10,12 +10,12 @@ const ROOT = SessionId('team-root')
 const TEAM = TeamId(ROOT)
 const CHILD = SessionId('child-a')
 
-function event<T extends SessionEventType>(type: T, data: SessionEventMap[T], seq: number): SessionEvent<T> {
+function event<T extends SessionEventType>(type: T, data: SessionEventMap[T], seq: SessionSeq): SessionEvent<T> {
   return { type, data, seq, time: seq } as SessionEvent<T>
 }
 
 function project(rootId: SessionId, events: readonly SessionEvent[]): TeamProjectionState {
-  let state = teamProjectionDefinition.init({ version: 0, id: rootId, createdAt: 0 })
+  let state = teamProjectionDefinition.init({ version: 0, id: rootId, createdAt: 0, isSeeded: false })
   for (const event of events) state = teamProjectionDefinition.apply(state, event)
   return state
 }
@@ -80,15 +80,15 @@ function message(overrides: Partial<TeamMessageSnapshot> = {}): TeamMessageSnaps
 describe('Agent Teams projection events', () => {
   it('projects current-team records independently from inherited records', () => {
     const records: SessionEvent[] = [
-      event('team/member', { version: 1, teamId: TeamId('ancestor'), member: member() }, 0),
-      event('team/member', { version: 1, teamId: TEAM, member: member() }, 1),
+      event('team/member', { version: 1, teamId: TeamId('ancestor'), member: member() }, SessionSeq(0)),
+      event('team/member', { version: 1, teamId: TEAM, member: member() }, SessionSeq(1)),
       event('team/member', {
         version: 1,
         teamId: TEAM,
         member: member({ phase: 'active' }),
-      }, 2),
-      event('team/task', { version: 1, teamId: TEAM, task: task({ id: TeamTaskId('task-7') }) }, 3),
-      event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, 4),
+      }, SessionSeq(2)),
+      event('team/task', { version: 1, teamId: TEAM, task: task({ id: TeamTaskId('task-7') }) }, SessionSeq(3)),
+      event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, SessionSeq(4)),
     ]
     const projected = project(ROOT, records)
     const state = teamState(projected)
@@ -104,51 +104,51 @@ describe('Agent Teams projection events', () => {
   })
 
   it('enforces teammate identity and lifecycle', () => {
-    const base = event('team/member', { version: 1, teamId: TEAM, member: member() }, 0)
+    const base = event('team/member', { version: 1, teamId: TEAM, member: member() }, SessionSeq(0))
     expect(() => projectTeam(ROOT, [event('team/member', {
       version: 1,
       teamId: TEAM,
       member: member({ phase: 'active' }),
-    }, 0)])).toThrow(/must begin provisioning/)
+    }, SessionSeq(0))])).toThrow(/must begin provisioning/)
     expect(() => projectTeam(ROOT, [base, event('team/member', {
       version: 1,
       teamId: TEAM,
       member: member({ name: 'renamed', phase: 'active' }),
-    }, 1)])).toThrow(/immutable identity/)
+    }, SessionSeq(1))])).toThrow(/immutable identity/)
     expect(() => projectTeam(ROOT, [base, event('team/member', {
       version: 1,
       teamId: TEAM,
       member: member({ phase: 'active' }),
-    }, 1), event('team/member', {
+    }, SessionSeq(1)), event('team/member', {
       version: 1,
       teamId: TEAM,
       member: member({ phase: 'failed' }),
-    }, 2)])).toThrow(/invalid active -> failed/)
+    }, SessionSeq(2))])).toThrow(/invalid active -> failed/)
 
     const duplicateName = member({ id: SessionId('child-b') })
     expect(() => projectTeam(ROOT, [base, event('team/member', {
       version: 1,
       teamId: TEAM,
       member: duplicateName,
-    }, 1)])).toThrow(/name .* reused/)
+    }, SessionSeq(1))])).toThrow(/name .* reused/)
   })
 
   it('enforces task revision continuity', () => {
-    const first = event('team/task', { version: 1, teamId: TEAM, task: task() }, 0)
+    const first = event('team/task', { version: 1, teamId: TEAM, task: task() }, SessionSeq(0))
     expect(() => projectTeam(ROOT, [event('team/task', {
       version: 1,
       teamId: TEAM,
       task: task({ revision: 2 }),
-    }, 0)])).toThrow(/begin at revision 1/)
+    }, SessionSeq(0))])).toThrow(/begin at revision 1/)
     expect(() => projectTeam(ROOT, [first, event('team/task', {
       version: 1,
       teamId: TEAM,
       task: task({ revision: 3 }),
-    }, 1)])).toThrow(/revision is not contiguous/)
+    }, SessionSeq(1))])).toThrow(/revision is not contiguous/)
   })
 
   it('rejects every invalid persisted task dependency relation', () => {
-    const first = event('team/task', { version: 1, teamId: TEAM, task: task() }, 0)
+    const first = event('team/task', { version: 1, teamId: TEAM, task: task() }, SessionSeq(0))
     const second = event('team/task', {
       version: 1,
       teamId: TEAM,
@@ -156,14 +156,14 @@ describe('Agent Teams projection events', () => {
         id: TeamTaskId('task-2'),
         blockedBy: [TeamTaskId('task-1')],
       }),
-    }, 1)
+    }, SessionSeq(1))
     const invalid: Array<{ records: SessionEvent[]; message: RegExp }> = [
       {
         records: [event('team/task', {
           version: 1,
           teamId: TEAM,
           task: task({ blockedBy: [TeamTaskId('missing')] }),
-        }, 0)],
+        }, SessionSeq(0))],
         message: /blocker task "missing" .* is missing or deleted/,
       },
       {
@@ -171,14 +171,14 @@ describe('Agent Teams projection events', () => {
           version: 1,
           teamId: TEAM,
           task: task({ blockedBy: [TeamTaskId('task-1')] }),
-        }, 0)],
+        }, SessionSeq(0))],
         message: /cannot block itself/,
       },
       {
         records: [first, event('team/task', {
           ...second.data,
           task: { ...second.data.task, blockedBy: [TeamTaskId('task-1'), TeamTaskId('task-1')] },
-        }, 1)],
+        }, SessionSeq(1))],
         message: /repeats blocker/,
       },
       {
@@ -186,7 +186,7 @@ describe('Agent Teams projection events', () => {
           version: 1,
           teamId: TEAM,
           task: task({ revision: 2, blockedBy: [TeamTaskId('task-2')] }),
-        }, 2)],
+        }, SessionSeq(2))],
         message: /dependency cycle/,
       },
       {
@@ -194,7 +194,7 @@ describe('Agent Teams projection events', () => {
           version: 1,
           teamId: TEAM,
           task: task({ revision: 2, status: 'deleted' }),
-        }, 2)],
+        }, SessionSeq(2))],
         message: /blocker task "task-1" .* is missing or deleted/,
       },
     ]
@@ -209,7 +209,7 @@ describe('Agent Teams projection events', () => {
       version: 1,
       teamId: TEAM,
       task: task({ id: TeamTaskId('external-task') }),
-    }, 0)])
+    }, SessionSeq(0))])
     expect(state.nextTaskNumber).toBe(1)
   })
 
@@ -218,39 +218,39 @@ describe('Agent Teams projection events', () => {
       version: 1,
       teamId: TEAM,
       task: task({ id: TeamTaskId('task-9007199254740992') }),
-    }, 0)])).toThrow(/persisted Agent Teams team\/task payload is invalid/)
+    }, SessionSeq(0))])).toThrow(/persisted Agent Teams team\/task payload is invalid/)
   })
 
   it('enforces mailbox queue and acknowledgement relations', () => {
-    const queued = event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, 0)
+    const queued = event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, SessionSeq(0))
     const delivered = event('team/message/delivered', {
       version: 1,
       teamId: TEAM,
       messageId: TeamMessageId('message-1'),
       targetId: CHILD,
-    }, 1)
+    }, SessionSeq(1))
     expect(pending(projectTeam(ROOT, [queued, delivered]))).toEqual([])
     expect(() => projectTeam(ROOT, [queued, queued])).toThrow(/queued twice/)
     expect(() => projectTeam(ROOT, [delivered])).toThrow(/delivered before queueing/)
     expect(() => projectTeam(ROOT, [queued, event('team/message/delivered', {
       ...delivered.data,
       targetId: SessionId('other'),
-    }, 1)])).toThrow(/target changed/)
-    expect(() => projectTeam(ROOT, [queued, delivered, { ...delivered, seq: 2 }])).toThrow(/delivered twice/)
+    }, SessionSeq(1))])).toThrow(/target changed/)
+    expect(() => projectTeam(ROOT, [queued, delivered, { ...delivered, seq: SessionSeq(2) }])).toThrow(/delivered twice/)
   })
 
   it('validates every current-version persisted payload before projecting it', () => {
     const malformed = [
       {
-        ...event('team/member', { version: 1, teamId: TEAM, member: member() }, 0),
+        ...event('team/member', { version: 1, teamId: TEAM, member: member() }, SessionSeq(0)),
         data: { version: 1, teamId: TEAM, member: { ...member(), name: 42 } },
       },
       {
-        ...event('team/task', { version: 1, teamId: TEAM, task: task() }, 0),
+        ...event('team/task', { version: 1, teamId: TEAM, task: task() }, SessionSeq(0)),
         data: { version: 1, teamId: TEAM, task: { ...task(), blockedBy: [42] } },
       },
       {
-        ...event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, 0),
+        ...event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, SessionSeq(0)),
         data: {
           version: 1,
           teamId: TEAM,
@@ -263,7 +263,7 @@ describe('Agent Teams projection events', () => {
           teamId: TEAM,
           messageId: TeamMessageId('message-1'),
           targetId: CHILD,
-        }, 0),
+        }, SessionSeq(0)),
         data: {
           version: 1,
           teamId: TEAM,
@@ -272,11 +272,11 @@ describe('Agent Teams projection events', () => {
         },
       },
       {
-        ...event('team/member', { version: 1, teamId: TEAM, member: member() }, 0),
+        ...event('team/member', { version: 1, teamId: TEAM, member: member() }, SessionSeq(0)),
         data: { version: 1, teamId: TEAM, member: member(), unexpected: true },
       },
       {
-        ...event('team/task', { version: 1, teamId: TEAM, task: task() }, 0),
+        ...event('team/task', { version: 1, teamId: TEAM, task: task() }, SessionSeq(0)),
         data: { version: 1, teamId: 42, task: task() },
       },
     ] as unknown as SessionEvent[]
@@ -293,7 +293,7 @@ describe('Agent Teams projection events', () => {
       version: 1,
       teamId: TEAM,
       message: message({ content: [extension] }),
-    }, 0)])
+    }, SessionSeq(0))])
     expect(pending(state)[0]?.content).toEqual([extension])
   })
 
@@ -302,12 +302,12 @@ describe('Agent Teams projection events', () => {
       version: 2 as 1,
       teamId: TEAM,
       task: task(),
-    }, 0)
+    }, SessionSeq(0))
     const later = event('team/task', {
       version: 1,
       teamId: TEAM,
       task: task(),
-    }, 1)
+    }, SessionSeq(1))
     const state = project(ROOT, [invalid, later])
     expect(state.failure).toMatch(/unsupported Agent Teams event version 2/)
     expect(isEmptyState(state)).toBe(true)
@@ -318,7 +318,7 @@ describe('Agent Teams projection events', () => {
       version: 2 as 1,
       teamId: TeamId('ancestor'),
       task: task(),
-    }, 0)
+    }, SessionSeq(0))
     const projected = project(ROOT, [inherited])
     expect(projected.failure).toBeUndefined()
     expect(isEmptyState(teamState(projected))).toBe(true)
@@ -330,7 +330,7 @@ describe('Agent Teams projection events', () => {
         version: 1,
         teamId: TeamId('ancestor'),
         task: task(),
-      }, 0),
+      }, SessionSeq(0)),
       data: {
         version: 1,
         teamId: TeamId('ancestor'),
diff --git a/packages/experimental/agent-team/tests/team.spec.ts b/packages/experimental/agent-team/tests/team.spec.ts
index 291fd6b59d..013d6f4cce 100644
--- a/packages/experimental/agent-team/tests/team.spec.ts
+++ b/packages/experimental/agent-team/tests/team.spec.ts
@@ -210,8 +210,12 @@ describe('Team identity and provisioning', () => {
     const fresh = await spawn(ctx, lead, 'fresh-worker')
     await waitNoAgent(ctx, fresh.member.id)
 
-    expect((await ctx.sessionPersistence.inspect(forked.member.id)).meta.seedLength).toBeGreaterThan(0)
-    expect((await ctx.sessionPersistence.inspect(fresh.member.id)).meta.seedLength ?? 0).toBe(0)
+    const forkedInspection = await ctx.sessionPersistence.inspect(forked.member.id)
+    const freshInspection = await ctx.sessionPersistence.inspect(fresh.member.id)
+    expect(forkedInspection.meta.isSeeded).toBe(true)
+    expect(forkedInspection.inheritedEventCount).toBeGreaterThan(0)
+    expect(freshInspection.meta.isSeeded).toBe(false)
+    expect(freshInspection.inheritedEventCount).toBe(0)
     expect(ctx.agentTeams.listMembers(lead).map(row => [row.name, row.context, row.status])).toEqual([
       ['lead', undefined, 'idle'],
       ['fork-worker', 'fork', 'inactive'],
@@ -458,7 +462,8 @@ describe('Team identity and provisioning', () => {
     const handle = await ctx.agents.create({
       sessionId: SessionId('ordinary-fork'),
       seed: lead.session.snapshotEvents(),
-      meta: { parentSession: lead.id, seedLength: lead.session.seq },
+      inheritedEventCount: lead.session.seq,
+      meta: { parentSession: lead.id, isSeeded: true },
       agentOptions: { provider: 'mock', model: 'mock' },
     })
 
diff --git a/packages/experimental/webworker-runtime/tests/fixtures/vfs-example/home/storages/session_projcache.json b/packages/experimental/webworker-runtime/tests/fixtures/vfs-example/home/storages/session_projcache.json
index 9248dd7ae7..e612124830 100644
--- a/packages/experimental/webworker-runtime/tests/fixtures/vfs-example/home/storages/session_projcache.json
+++ b/packages/experimental/webworker-runtime/tests/fixtures/vfs-example/home/storages/session_projcache.json
@@ -1,7 +1,7 @@
 {
   "unit": {
     "name": "session_projcache",
-    "version": 3
+    "version": 5
   },
   "global": null,
   "tables": {
@@ -9,7 +9,9 @@
       "preview-showcase": {
         "identity": {
           "createdAt": 1787472000000,
-          "cwd": "/dsh/workspace"
+          "cwd": "/dsh/workspace",
+          "isSeeded": false,
+          "inheritedEventCount": 0
         },
         "rows": {
           "title": {
diff --git a/packages/experimental/webworker-runtime/tests/vfs-example-fixture.spec.ts b/packages/experimental/webworker-runtime/tests/vfs-example-fixture.spec.ts
index d4d1471d0d..bd7c0f6838 100644
--- a/packages/experimental/webworker-runtime/tests/vfs-example-fixture.spec.ts
+++ b/packages/experimental/webworker-runtime/tests/vfs-example-fixture.spec.ts
@@ -57,11 +57,21 @@ describe('WebWorker preview VFS example', () => {
       'utf8',
     )) as {
       unit: { name: string; version: number }
-      tables: { sessions: Record<string, { identity: { createdAt: number; cwd: string }; rows: { title: unknown } }> }
+      tables: {
+        sessions: Record<string, {
+          identity: { createdAt: number; cwd: string; isSeeded: boolean; inheritedEventCount: number }
+          rows: { title: unknown }
+        }>
+      }
     }
-    expect(cache.unit).toEqual({ name: 'session_projcache', version: 3 })
+    expect(cache.unit).toEqual({ name: 'session_projcache', version: 5 })
     expect(cache.tables.sessions[VFS_EXAMPLE_SESSION_IDS.main]).toMatchObject({
-      identity: { createdAt: 1_787_472_000_000, cwd: '/dsh/workspace' },
+      identity: {
+        createdAt: 1_787_472_000_000,
+        cwd: '/dsh/workspace',
+        isSeeded: false,
+        inheritedEventCount: 0,
+      },
       rows: {
         title: {
           ver: 1,
@@ -72,7 +82,7 @@ describe('WebWorker preview VFS example', () => {
   })
 
   it('restores the main production log with paging and tool coverage', () => {
-    const { meta, events } = readSession(VFS_EXAMPLE_SESSION_IDS.main)
+    const { meta, inheritedEventCount, events } = readSession(VFS_EXAMPLE_SESSION_IDS.main)
     expect(meta).toMatchObject({
       id: VFS_EXAMPLE_SESSION_IDS.main,
       cwd: '/dsh/workspace',
@@ -81,7 +91,12 @@ describe('WebWorker preview VFS example', () => {
     })
     expect(events.map(event => event.seq)).toEqual(events.map((_, index) => index))
     expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'completed' } } })
-    expect(() => Session.fromRestore(SessionId(meta.id), events, meta)).not.toThrow()
+    expect(() => Session.fromRestore(
+      SessionId(meta.id),
+      events,
+      meta,
+      inheritedEventCount,
+    )).not.toThrow()
 
     const messages = events.filter(event =>
       (event.type === 'user/message' || event.type === 'assistant/message') && event.surfaceOp === 'append')
@@ -105,7 +120,7 @@ describe('WebWorker preview VFS example', () => {
       [VFS_EXAMPLE_SESSION_IDS.continuable, 'continuable'],
     ] as const
     for (const [id, mode] of expected) {
-      const { meta, events } = readSession(id)
+      const { meta, inheritedEventCount, events } = readSession(id)
       expect(meta).toMatchObject({
         id,
         cwd: '/dsh/workspace',
@@ -116,8 +131,13 @@ describe('WebWorker preview VFS example', () => {
       })
       expect(events.map(event => event.seq)).toEqual(events.map((_, index) => index))
       expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'completed' } } })
-      expect(foldSubagentDescriptor(events.slice(meta.seedLength ?? 0))).toMatchObject({ mode })
-      expect(() => Session.fromRestore(SessionId(meta.id), events, meta)).not.toThrow()
+      expect(foldSubagentDescriptor(events.slice(inheritedEventCount))).toMatchObject({ mode })
+      expect(() => Session.fromRestore(
+        SessionId(meta.id),
+        events,
+        meta,
+        inheritedEventCount,
+      )).not.toThrow()
     }
   })
 })
diff --git a/packages/experimental/webworker-runtime/tests/vfs-example-fixture.ts b/packages/experimental/webworker-runtime/tests/vfs-example-fixture.ts
index dbc151eb86..20ac1e3838 100644
--- a/packages/experimental/webworker-runtime/tests/vfs-example-fixture.ts
+++ b/packages/experimental/webworker-runtime/tests/vfs-example-fixture.ts
@@ -1,7 +1,15 @@
 /** Deterministic source for the filesystem tree bundled into the WebWorker preview. */
 
 import { fileURLToPath } from 'node:url'
-import { SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import {
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+  type SessionEvent,
+  type SessionHeader,
+  type SessionLogOffset as SessionLogOffsetType,
+  type SessionSeq as SessionSeqType,
+} from '@deepseek-ai/dsh-session'
 import {
   eventLines, projectKey, toHeaderLine,
 } from '@deepseek-ai/dsh-session-persistence-jsonl/src/format.ts'
@@ -71,7 +79,7 @@ interface EventDraft {
   readonly type: string
   readonly data: unknown
   readonly surfaceOp?: 'append'
-  readonly sourceEventSeqs?: number[]
+  readonly sourceEventSeqs?: SessionSeqType[]
   readonly ignorable?: true
 }
 
@@ -84,8 +92,8 @@ class EventLog {
     this.nextTime = Math.max(time, (this.events.at(-1)?.time ?? time - 1) + 1)
   }
 
-  add(draft: EventDraft): number {
-    const seq = this.events.length
+  add(draft: EventDraft): SessionSeqType {
+    const seq = SessionSeq(this.events.length)
     this.events.push({ ...draft, seq, time: this.nextTime++ } as unknown as SessionEvent)
     return seq
   }
@@ -265,10 +273,13 @@ function addClosedTextTurn(log: EventLog, turn: number): void {
   log.add({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
 }
 
-function mainLog(): { readonly events: SessionEvent[]; readonly forkSeedLength: number } {
+function mainLog(): {
+  readonly events: SessionEvent[]
+  readonly forkSeedLength: SessionLogOffsetType
+} {
   const log = new EventLog(CREATED_AT)
   for (let turn = 1; turn <= HISTORICAL_TURNS; turn++) addClosedTextTurn(log, turn)
-  const forkSeedLength = log.events.length
+  const forkSeedLength = SessionLogOffset(log.events.length)
   const turn = HISTORICAL_TURNS + 1
   const calls = galleryCalls()
 
@@ -363,25 +374,36 @@ function continuableLog(): SessionEvent[] {
 function header(
   id: SessionHeader['id'],
   createdAt: number,
-  child?: { readonly parentSession: SessionHeader['id']; readonly mode: 'one-shot' | 'continuable'; readonly seedLength?: number },
-): SessionHeader {
+  child?: {
+    readonly parentSession: SessionHeader['id']
+    readonly mode: 'one-shot' | 'continuable'
+    readonly seedLength?: SessionLogOffsetType
+  },
+): { readonly meta: SessionHeader; readonly inheritedEventCount: SessionLogOffsetType } {
+  const inheritedEventCount = child?.seedLength ?? SessionLogOffset(0)
   return {
-    version: 0,
-    id,
-    createdAt,
-    cwd: WORKSPACE,
-    delegationDepth: child === undefined ? 0 : 1,
-    agentPreset: 'standard',
-    ...child === undefined ? {} : {
-      parentSession: child.parentSession,
-      origin: 'subagent' as const,
-      ...child.seedLength === undefined ? {} : { seedLength: child.seedLength },
+    meta: {
+      version: 0,
+      id,
+      createdAt,
+      cwd: WORKSPACE,
+      isSeeded: child?.seedLength !== undefined,
+      delegationDepth: child === undefined ? 0 : 1,
+      agentPreset: 'standard',
+      ...child === undefined ? {} : {
+        parentSession: child.parentSession,
+        origin: 'subagent' as const,
+      },
     },
+    inheritedEventCount,
   }
 }
 
-function renderLog(meta: SessionHeader, events: readonly SessionEvent[]): string {
-  return `${JSON.stringify(toHeaderLine(meta))}\n${eventLines(events, true)}\n`
+function renderLog(
+  storage: { readonly meta: SessionHeader; readonly inheritedEventCount: SessionLogOffsetType },
+  events: readonly SessionEvent[],
+): string {
+  return `${JSON.stringify(toHeaderLine(storage.meta, storage.inheritedEventCount))}\n${eventLines(events, true)}\n`
 }
 
 /** Build every committed fixture file as repository-relative UTF-8 text. */
@@ -390,12 +412,17 @@ export function buildVfsExampleFiles(): ReadonlyMap<string, string> {
   const project = projectKey(WORKSPACE)
   const sessionPath = (id: string): string => `home/sessions/${project}/${id}/session.jsonl`
   const projectionCache = `${JSON.stringify({
-    unit: { name: 'session_projcache', version: 3 },
+    unit: { name: 'session_projcache', version: 5 },
     global: null,
     tables: {
       sessions: {
         [VFS_EXAMPLE_SESSION_IDS.main]: {
-          identity: { createdAt: CREATED_AT, cwd: WORKSPACE },
+          identity: {
+            createdAt: CREATED_AT,
+            cwd: WORKSPACE,
+            isSeeded: false,
+            inheritedEventCount: 0,
+          },
           rows: {
             title: { ver: 1, seq: main.events.at(-1)?.seq ?? -1, val: VFS_EXAMPLE_TITLE },
           },
diff --git a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
index 55c4f977ef..00c7b4a4b2 100644
--- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
@@ -559,7 +559,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ISession',
-    declaration: 'export interface ISession {\n    readonly sessionId: SessionId;\n    readonly projections: ProjectionsFace;\n    beginSubmission(input: BeginSubmissionInput): SubmissionHandle;\n    prompt(content: PromptContentPart[], mode: \'queue\' | \'steer\', signal?: AbortSignal, requestId?: SessionRequestId): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    readAttachment(attachmentId: AttachmentIdType): Promise<RemoteResult<{\n        attachment: ImageAttachmentRef;\n        data: Uint8Array;\n    }>>;\n    updateQueue(itemId: MessageId, action: QueueAction): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    cancel(): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    rename(title: string): Promise<RemoteResult<{\n        title: string;\n        seq: number;\n    }>>;\n    loadOlder(): Promise<void>;\n    loadThrough(seq: number): Promise<void>;\n    command(line: string): Promise<RemoteResult<{\n        matched: boolean;\n    }>>;\n}',
+    declaration: 'export interface ISession {\n    readonly sessionId: SessionId;\n    readonly projections: ProjectionsFace;\n    beginSubmission(input: BeginSubmissionInput): SubmissionHandle;\n    prompt(content: PromptContentPart[], mode: \'queue\' | \'steer\', signal?: AbortSignal, requestId?: SessionRequestId): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    readAttachment(attachmentId: AttachmentIdType): Promise<RemoteResult<{\n        attachment: ImageAttachmentRef;\n        data: Uint8Array;\n    }>>;\n    updateQueue(itemId: MessageId, action: QueueAction): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    cancel(): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    rename(title: string): Promise<RemoteResult<{\n        title: string;\n        seq: SessionSeq;\n    }>>;\n    loadOlder(): Promise<void>;\n    loadThrough(seq: SessionSeq): Promise<void>;\n    command(line: string): Promise<RemoteResult<{\n        matched: boolean;\n    }>>;\n}',
   },
   {
     name: 'KeyPropsOf',
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index 81890bfd98..dc9c78a9d5 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -204,7 +204,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.assistant-actions\', () => ctx.slots.register(\n      { name: \'conversation.chat.assistant-actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:204',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:205',
   },
   {
     key: 'conversation.chat.commandview',
@@ -249,7 +249,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.commandview\', () => ctx.slots.register(\n      { name: \'conversation.chat.commandview\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:192',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:193',
   },
   {
     key: 'conversation.chat.node',
@@ -313,7 +313,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.node\', () => ctx.slots.register(\n      { name: \'conversation.chat.node\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:173',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:174',
   },
   {
     key: 'conversation.chat.turnTail',
@@ -358,7 +358,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.turnTail\', () => ctx.slots.register(\n      { name: \'conversation.chat.turnTail\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:198',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:199',
   },
   {
     key: 'conversation.composer',
@@ -537,7 +537,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.details.tool\', () => ctx.slots.register(\n      { name: \'conversation.details.tool\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:210',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:211',
   },
   {
     key: 'conversation.hero.agentPreset',
@@ -1025,7 +1025,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.message.images\', () => ctx.slots.register(\n      { name: \'conversation.message.images\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:186',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:187',
   },
   {
     key: 'conversation.session',
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index 7c6091b1e4..55761bf933 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -664,7 +664,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         throws: ['{@link ManualCompactionError} for expected busy, agent-cancellation, changed-span, summarization/shrink, commit-stage, or persistence failures; an aborted request preserves its exact abort reason. Failed attempts remain visible in the log.'],
       },
       {
-        signature: 'abstract compactRegion( start: number, end: number, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
+        signature: 'abstract compactRegion( start: SessionSeq, end: SessionSeq, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
         description: 'Forcibly compact a range of surface nodes into a single summary node. `start` and `end` name an inclusive span by surface position, not numeric seq order; replacements can make visible seqs non-monotonic. Both edges must be balanced so assistant tool calls remain paired with their results. A model- backed implementation forwards cancellation and rejects active, missing, reversed, or unbalanced ranges. The target session is `agent.session`. Its replacement user message must use compactCheckpointSource with the transaction\'s `CompactionId`. Use toolPairingBalancedBefore and toolPairingBalancedAfter for the edge checks.',
         parameters: [{ name: 'start', description: 'first surface seq, inclusive.' }, { name: 'end', description: 'last surface seq, inclusive.' }, { name: 'agent', description: 'context whose session is mutated and whose routing options guide summarization.' }, { name: 'signal', description: 'optional cancellation; model-backed implementations must forward it.' }],
         returns: 'the appended event seqs, summary, replaced range, and token accounting.',
@@ -1341,7 +1341,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         returns: 'the live Agent or the stable Session-domain failure.',
       },
       {
-        signature: 'inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionHeader; events: readonly SessionEvent[] }>',
+        signature: 'inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionInspection>',
         description: 'Inspect one attached or persisted Session without activating its Agent.',
         parameters: [{ name: 'sessionId', description: 'durable Session identity.' }, { name: 'signal', description: 'optional caller cancellation for persistence reads.' }],
         returns: 'the current attached state or persisted header and event prefix.',
@@ -1482,9 +1482,9 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         throws: ['when this backend does not expose per-session raw artifacts.'],
       },
       {
-        signature: 'abstract create(meta: SessionHeader): Promise<void>',
+        signature: 'abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>',
         description: 'Register a new session\'s metadata. A backend MAY defer the physical write until the first append (lazy materialization), in which case a created-but-never-appended session is absent from list — abandoned sessions leave nothing behind.',
-        parameters: [{ name: 'meta', description: 'the immutable header (id, version, cwd, lineage) to record.' }],
+        parameters: [{ name: 'meta', description: 'the immutable header (id, version, cwd, lineage) to record.' }, { name: 'inheritedEventCount', description: 'exact fork-inherited prefix length. Required for a seeded header and omitted only for an unseeded header.' }],
       },
       {
         signature: 'ensureMaterialized(_session: Session): Promise<void>',
@@ -1493,7 +1493,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
-        description: 'Durably persist a batch of events. Honors the append-only and contiguous- seq contracts: the first event\'s `seq` MUST equal the stored next-seq (after `load` has durably closed any interrupted turn). Rejects non-JSON- serializable `event.data` with an error naming the offending event type.',
+        description: 'Durably persist a batch of events. Honors the append-only and contiguous- seq contracts: the first event\'s `seq` MUST equal the stored next-seq (after `load` has durably closed any interrupted turn). Rejects non-JSON- serializable `event.data` with an error naming the offending event type. A seeded session\'s first materializing batch must reach its complete inherited prefix.',
         parameters: [{ name: 'id', description: 'the session the batch belongs to.' }, { name: 'events', description: 'the contiguous batch to persist, in seq order.' }],
       },
       {
@@ -1521,10 +1521,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         returns: 'a disposable immutable observation.',
       },
       {
-        signature: 'abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
+        signature: 'abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>',
         description: 'Read the stored events from `fromSeq` onward — the read-from-seq primitive for read models that resume from a watermark (e.g. a persisted projection cache folding only the tail past its checkpoint). Unlike inspect, it is a detached physical suffix read: no preparation cache, torn-tail truncation, synthetic closers, or coordinator-state publication. Only events from the valid contiguous stored prefix are returned, so a torn fragment never reaches the caller. `fromSeq` at or beyond the stored prefix returns an empty event list (never an error). A backend whose medium can seek by seq may read only the suffix; sequential media such as JSONL still parse the whole artifact and skip forward. The primitive bounds what is returned and refolded, not every backend\'s physical read.',
-        parameters: [{ name: 'id', description: 'the persisted session to read.' }, { name: 'fromSeq', description: 'first event seq to include; a non-negative safe integer.' }, { name: 'signal', description: 'optional cancellation for queued and backend read work.' }],
-        returns: 'the header and the stored events with `seq >= fromSeq`.',
+        parameters: [{ name: 'id', description: 'the persisted session to read.' }, { name: 'fromSeq', description: 'first event offset to include.' }, { name: 'signal', description: 'optional cancellation for queued and backend read work.' }],
+        returns: 'storage metadata, the requested offset, and stored events with `seq >= fromSeq`.',
       },
       {
         signature: 'abstract list(signal?: AbortSignal): Promise<SessionHeader[]>',
@@ -1546,15 +1546,15 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     description: 'The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus three mandatory points — session creation, `turn/end`, and session disposal (the live-to-cold moment) — and serves the cached rows for a session header. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write.',
     methods: [
       {
-        signature: 'cachedSnapshot( meta: SessionHeader, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot | undefined',
+        signature: 'cachedSnapshot( meta: SessionHeader, inheritedEventCount: SessionLogOffset, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot | undefined',
         description: 'The zero-I/O listing read: whole values viewed straight from the stored rows (version-matching keys only), each cut carried with its watermark so a client value store can seed under its higher-seq-wins rule — as stale as the last durable checkpoint but never wrong, and never from an unrelated log (the caller\'s header is the identity witness). Fresher paths (the history tail baseline) supersede these values whenever a session is actually opened.',
-        parameters: [{ name: 'meta', description: 'the listed session\'s header (identity witness; no log read).' }, { name: 'keys', description: 'optional projection keys required by the caller\'s audience.' }],
+        parameters: [{ name: 'meta', description: 'the listed session\'s header (identity witness; no log read).' }, { name: 'inheritedEventCount', description: 'exact inherited prefix length that completes the checkpoint identity.' }, { name: 'keys', description: 'optional projection keys required by the caller\'s audience.' }],
         returns: 'the cut (`asOfSeq` = lowest served-row watermark), or `undefined` when no usable row exists for this lifecycle.',
       },
       {
-        signature: 'hydratePrepared( session: Session, meta: SessionHeader, events: readonly SessionEvent[], ): ProjectionSnapshot',
+        signature: 'hydratePrepared( session: Session, events: readonly SessionEvent[], ): ProjectionSnapshot',
         description: 'Hydrate projection cells for an already-prepared Session without another persistence read. The cache seeds matching rows; the supplied exact log advances every unit to the observation cut. No checkpoint is written because the logical observation may contain recovery events not yet durable.',
-        parameters: [{ name: 'session', description: 'exact unpublished Session retained by persistence.' }, { name: 'meta', description: 'observed lifecycle header.' }, { name: 'events', description: 'exact logical event prefix represented by the observation.' }],
+        parameters: [{ name: 'session', description: 'exact unpublished Session retained by persistence.' }, { name: 'events', description: 'exact logical event prefix represented by the observation.' }],
         returns: 'all projection values at the event cut.',
       },
       {
@@ -1564,9 +1564,9 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         returns: 'resolution after durability and event emission.',
       },
       {
-        signature: 'coldSnapshot(meta: SessionHeader, events: readonly SessionEvent[]): ProjectionSnapshot',
+        signature: 'coldSnapshot( meta: SessionHeader, inheritedEventCount: SessionLogOffset, events: readonly SessionEvent[], ): ProjectionSnapshot',
         description: 'Cold-read one session\'s projections from its complete log. Each unit is seeded from the identity-checked cached rows — the registry skips `apply` for the already-folded prefix (events at or below the row\'s `seq`) — and the refreshed checkpoint is written back (fail-soft, fire-and-forget), so the first cold read creates the cache row and later ones seed from it. The caller supplies the complete log in seq order: this service never consults the persistence layer.',
-        parameters: [{ name: 'meta', description: 'the stored session header (identity witness).' }, { name: 'events', description: 'the session\'s complete log, in seq order.' }],
+        parameters: [{ name: 'meta', description: 'the stored session header (identity witness).' }, { name: 'inheritedEventCount', description: 'exact inherited prefix length for projection initialization and identity.' }, { name: 'events', description: 'the session\'s complete log, in seq order.' }],
         returns: 'the projection cut at the log end.',
       },
     ],
@@ -1619,7 +1619,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         returns: 'one row per registered key.',
       },
       {
-        signature: 'restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined',
+        signature: 'restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined',
         description: 'The stored seq a restore tail read over `checkpoint` must start at: one event BELOW the lowest usable watermark (a row is usable when its `ver` matches the live unit\'s `stateVersion`; an absent or mismatched row pulls the floor to `0` — that key must refold the full log). The one-below anchor is load-bearing: the tail then proves how far the stored log still extends, so restore can detect a log that shrank below a row\'s watermark (crash-repair truncation) instead of serving the stale row as current — an empty tail read from the anchor yields an end below every watermark and the restore rejects for a full re-read.',
         parameters: [{ name: 'checkpoint', description: 'persisted rows for one session (possibly stale or empty).' }],
         returns: 'the seq to hand the persistence `readFrom`, or `undefined` when no unit is registered (no read needed — {@link restore} would serve empty values regardless).',
@@ -1631,13 +1631,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         returns: 'whole values per key with a usable row; empty when none.',
       },
       {
-        signature: 'restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number, header: SessionHeader, ): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }',
+        signature: 'restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, header: SessionHeader, inheritedEventCount: SessionLogOffset, ): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }',
         description: 'Cold read: fold every persisted unit over a stored log suffix, seeding each from its checkpoint row when usable — the one read recipe (cached state + forward tail replay + `view`) applied without a live `Session`. Call with the events returned by a persistence `readFrom(id, restoreFloor(checkpoint))` and that same floor as `baseSeq`; the floor\'s one-below anchor makes the supplied end honest, so a shrunk log is detected here. A row is usable iff its `ver` matches the live unit\'s `stateVersion`, it does not predate `baseSeq` (`seq >= baseSeq - 1`), and it does not claim events past the supplied end (`seq <= endSeq`); an unusable row is discarded and its key refolds from `init` — which is only sound over the full log, so a discarded row with `baseSeq > 0` throws (the caller re-reads from seq 0, e.g. after a crash-repair truncation shrank the log below a row\'s watermark).',
-        parameters: [{ name: 'checkpoint', description: 'persisted rows for one session (possibly stale or empty).' }, { name: 'events', description: 'the stored events with `seq >= baseSeq`, in seq order.' }, { name: 'baseSeq', description: 'the seq `events` starts at (its first event\'s seq when non-empty).' }, { name: 'header', description: 'immutable metadata for the Session being restored.' }],
+        parameters: [{ name: 'checkpoint', description: 'persisted rows for one session (possibly stale or empty).' }, { name: 'events', description: 'the stored events with `seq >= baseSeq`, in seq order.' }, { name: 'baseSeq', description: 'the seq `events` starts at (its first event\'s seq when non-empty).' }, { name: 'header', description: 'immutable metadata for the Session being restored.' }, { name: 'inheritedEventCount', description: 'exact fork-inherited prefix length supplied to unit initialization.' }],
         returns: 'the snapshot cut at the supplied log end (`asOfSeq` is the last supplied event\'s seq, `baseSeq - 1` for an empty tail) plus the refreshed checkpoint rows at that cut, ready for a durable write-back.',
       },
       {
-        signature: 'hydrate( session: Session, checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number, ): ProjectionSnapshot',
+        signature: 'hydrate( session: Session, checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, ): ProjectionSnapshot',
         description: 'Restore an exact cut and install its states on the supplied prepared Session. A later publication reuses these cells; ordinary live reads and event drive advance any constructor-owned suffix exactly once.',
         parameters: [{ name: 'session', description: 'exact prepared Session that owns the restored log prefix.' }, { name: 'checkpoint', description: 'persisted rows for this Session lifecycle.' }, { name: 'events', description: 'exact events at the observation cut.' }, { name: 'baseSeq', description: 'first supplied event sequence.' }],
         returns: 'all projection values at the supplied cut.',
@@ -1822,7 +1822,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         returns: 'a fresh array; mutating it does not affect the store.',
       },
       {
-        signature: 'fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session',
+        signature: 'fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session',
         description: 'Create a live child session from a stable prefix of a live source. `boundary` is an inclusive source event seq; omitted means the source\'s current last event. The selected slice may end with a between-turn event but must not end inside an open turn.',
         parameters: [{ name: 'source', description: 'Live source session object or id.' }, { name: 'boundary', description: 'Inclusive source event seq to fork through; omitted means the source\'s current last event, and omitted on an empty source forks an empty child.' }, { name: 'childSessionId', description: 'Optional child session id; omitted delegates to `SessionStore`\'s id policy.' }],
         returns: 'The created live child session.',
@@ -3614,9 +3614,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'Branded',
     declaration: 'export type Branded<B extends string> = string & {\n    readonly [BRAND]: B;\n};',
   },
+  {
+    name: 'BrandedNumber',
+    declaration: 'export type BrandedNumber<B extends string> = number & {\n    readonly [BRAND]: B;\n};',
+  },
   {
     name: 'ChunkRow',
-    declaration: 'export type ChunkRow = {\n    type: \'text-chunks\';\n    seq0: number;\n    time0: number;\n    data: TextRunData;\n} | {\n    type: \'reasoning-chunks\';\n    seq0: number;\n    time0: number;\n    data: TextRunData;\n} | {\n    type: \'tool-call-chunks\';\n    seq0: number;\n    time0: number;\n    data: ToolCallRunData;\n};',
+    declaration: 'export type ChunkRow = {\n    type: \'text-chunks\';\n    seq0: SessionSeqType;\n    time0: number;\n    data: TextRunData;\n} | {\n    type: \'reasoning-chunks\';\n    seq0: SessionSeqType;\n    time0: number;\n    data: TextRunData;\n} | {\n    type: \'tool-call-chunks\';\n    seq0: SessionSeqType;\n    time0: number;\n    data: ToolCallRunData;\n};',
   },
   {
     name: 'ChunkRowEvent',
@@ -3684,7 +3688,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CommandResult',
-    declaration: 'export type CommandResult = {\n    readonly kind: \'success\';\n    readonly text?: string;\n    readonly sourceEventSeq?: number;\n} | {\n    readonly kind: \'error\';\n    readonly text: string;\n};',
+    declaration: 'export type CommandResult = {\n    readonly kind: \'success\';\n    readonly text?: string;\n    readonly sourceEventSeq?: SessionSeq;\n} | {\n    readonly kind: \'error\';\n    readonly text: string;\n};',
   },
   {
     name: 'CompactionAgentContext',
@@ -3696,7 +3700,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CompactionResult',
-    declaration: 'export interface CompactionResult {\n    compactionId: CompactionId;\n    sourceCommandId?: CommandId;\n    startSeq: number;\n    summarySeq: number;\n    endSeq: number;\n    summary: ContentBlock[];\n    shadowedRange: {\n        start: number;\n        end: number;\n    };\n    shadowedSeqs: number[];\n    shadowedTokenCount: number;\n}',
+    declaration: 'export interface CompactionResult {\n    compactionId: CompactionId;\n    sourceCommandId?: CommandId;\n    startSeq: SessionSeq;\n    summarySeq: SessionSeq;\n    endSeq: SessionSeq;\n    summary: ContentBlock[];\n    shadowedRange: {\n        start: SessionSeq;\n        end: SessionSeq;\n    };\n    shadowedSeqs: SessionSeq[];\n    shadowedTokenCount: number;\n}',
   },
   {
     name: 'CompactionTrigger',
@@ -3820,7 +3824,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CreateAgentOptions',
-    declaration: 'export interface CreateAgentOptions {\n    readonly sessionId: SessionId;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n        readonly agentPreset?: string;\n    };\n    readonly seed?: readonly SessionEvent[];\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: AgentSetup;\n}',
+    declaration: 'export interface CreateAgentOptions {\n    readonly sessionId: SessionId;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly isSeeded?: boolean;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n        readonly agentPreset?: string;\n    };\n    readonly inheritedEventCount?: SessionLogOffset;\n    readonly seed?: readonly SessionEvent[];\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: AgentSetup;\n}',
   },
   {
     name: 'CreateGoalRequest',
@@ -3832,7 +3836,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CreateSessionOptions',
-    declaration: 'export interface CreateSessionOptions {\n    readonly seed?: readonly SessionEvent[];\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly createdAt?: number;\n        readonly seedLength?: number;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n        readonly agentPreset?: string;\n    };\n}',
+    declaration: 'export interface CreateSessionOptions {\n    readonly seed?: readonly SessionEvent[];\n    readonly inheritedEventCount?: SessionLogOffset;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly createdAt?: number;\n        readonly isSeeded?: boolean;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n        readonly agentPreset?: string;\n    };\n}',
   },
   {
     name: 'CreateTeamTaskRequest',
@@ -4510,6 +4514,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'OneShotSubagentDescriptorData',
     declaration: 'export interface OneShotSubagentDescriptorData extends SubagentDescriptorBase {\n    readonly mode: \'one-shot\';\n    readonly label?: string;\n}',
   },
+  {
+    name: 'OptionalSessionSeq',
+    declaration: 'export type OptionalSessionSeq = SessionSeq | null;',
+  },
   {
     name: 'PermissionSelect',
     declaration: 'export interface PermissionSelect {\n    options: PresetOption[];\n    currentValue: string;\n}',
@@ -4564,7 +4572,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ProjectionChangeListener',
-    declaration: 'export type ProjectionChangeListener = (session: Session, key: Extract<keyof SessionProjectionMap, string>, value: unknown, seq: number) => void;',
+    declaration: 'export type ProjectionChangeListener = (session: Session, key: Extract<keyof SessionProjectionMap, string>, value: unknown, seq: SessionSeq) => void;',
   },
   {
     name: 'ProjectionCheckpoint',
@@ -4572,15 +4580,15 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ProjectionCheckpointRow',
-    declaration: 'export interface ProjectionCheckpointRow {\n    ver: number;\n    seq: number;\n    val: unknown;\n}',
+    declaration: 'export interface ProjectionCheckpointRow {\n    ver: number;\n    seq: SessionSeqCursor;\n    val: unknown;\n}',
   },
   {
     name: 'ProjectionDefinition',
-    declaration: 'export interface ProjectionDefinition<K extends keyof SessionProjectionStateMap, S extends SessionProjectionStateMap[K] = SessionProjectionStateMap[K]> {\n    key: K;\n    stateSchema: ZodType<S>;\n    init(header: SessionHeader): NoInfer<S>;\n    apply(state: NoInfer<S>, event: SessionEvent): NoInfer<S>;\n    wire?: K extends keyof SessionProjectionMap ? {\n        viewSchema: ZodType<SessionProjectionMap[K]>;\n        view(state: NoInfer<S>): SessionProjectionMap[K];\n    } : never;\n    stateVersion: number;\n}',
+    declaration: 'export interface ProjectionDefinition<K extends keyof SessionProjectionStateMap, S extends SessionProjectionStateMap[K] = SessionProjectionStateMap[K]> {\n    key: K;\n    stateSchema: ZodType<S>;\n    init(header: SessionHeader, inheritedEventCount: SessionLogOffset): NoInfer<S>;\n    apply(state: NoInfer<S>, event: SessionEvent): NoInfer<S>;\n    wire?: K extends keyof SessionProjectionMap ? {\n        viewSchema: ZodType<SessionProjectionMap[K]>;\n        view(state: NoInfer<S>): SessionProjectionMap[K];\n    } : never;\n    stateVersion: number;\n}',
   },
   {
     name: 'ProjectionSnapshot',
-    declaration: 'export interface ProjectionSnapshot {\n    asOfSeq: number;\n    values: Partial<SessionProjectionMap>;\n}',
+    declaration: 'export interface ProjectionSnapshot {\n    asOfSeq: SessionSeqCursor;\n    values: Partial<SessionProjectionMap>;\n}',
   },
   {
     name: 'PromptAssembly',
@@ -4608,7 +4616,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'PrunedEntry',
-    declaration: 'export interface PrunedEntry {\n    readonly originalSeq: number;\n    readonly replacementSeq: number;\n    readonly callId: ToolCallId;\n    readonly charsBefore: number;\n    readonly charsAfter: number;\n}',
+    declaration: 'export interface PrunedEntry {\n    readonly originalSeq: SessionSeq;\n    readonly replacementSeq: SessionSeq;\n    readonly callId: ToolCallId;\n    readonly charsBefore: number;\n    readonly charsAfter: number;\n}',
   },
   {
     name: 'PruneResult',
@@ -4704,7 +4712,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'RestoredSessionOptions',
-    declaration: 'export interface RestoredSessionOptions {\n    readonly seed: SessionEvent[];\n    readonly meta: SessionHeader;\n    readonly seedSource: \'persistence\';\n}',
+    declaration: 'export interface RestoredSessionOptions {\n    readonly seed: SessionEvent[];\n    readonly meta: SessionHeader;\n    readonly inheritedEventCount: SessionLogOffset;\n    readonly seedSource: \'persistence\';\n}',
   },
   {
     name: 'ResumeAgentOptions',
@@ -4788,7 +4796,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'Session',
-    declaration: 'export class Session {\n    get surface(): SessionSurface;\n    readonly header: SessionHeader;\n    get id(): SessionId;\n    readonly firstLiveSeq: number;\n    static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;\n    static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;\n    eventAt(seq: number): SessionEvent | undefined;\n    snapshotEvents(fromSeq: number = 0, toSeqExclusive: number = this.log.length): readonly SessionEvent[];\n    get seq(): number;\n    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n        opts: SurfaceIntent\n    ] : [\n    ]): SessionEvent<T>;\n    requestHeader(): EpochHeader | undefined;\n    requestContext(): RequestContext | undefined;\n    deriveMessages(): Message[];\n    deriveEventMessage(event: SessionEvent): Message | null;\n}',
+    declaration: 'export class Session {\n    get surface(): SessionSurface;\n    readonly header: SessionHeader;\n    readonly inheritedEventCount: SessionLogOffset;\n    get id(): SessionId;\n    readonly firstLiveSeq: SessionLogOffset;\n    static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader, inheritedEventCount?: SessionLogOffset): Session;\n    static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader, inheritedEventCount: SessionLogOffset): Session;\n    eventAt(seq: SessionSeq): SessionEvent | undefined;\n    snapshotEvents(fromSeq: SessionLogOffset = SessionLogOffset(0), toSeqExclusive: SessionLogOffset = this.seq): readonly SessionEvent[];\n    ownEvents(): readonly SessionEvent[];\n    isOwnSeq(seq: SessionSeq): boolean;\n    get seq(): SessionLogOffset;\n    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n        opts: SurfaceIntent\n    ] : [\n    ]): SessionEvent<T>;\n    requestHeader(): EpochHeader | undefined;\n    requestContext(): RequestContext | undefined;\n    deriveMessages(): Message[];\n    deriveEventMessage(event: SessionEvent): Message | null;\n}',
   },
   {
     name: 'SessionAddress',
@@ -4836,7 +4844,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionEvent',
-    declaration: 'export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n    [K in SessionEventType]: {\n        type: K;\n        seq: number;\n        time: number;\n        data: SessionEventMap[K];\n        ignorable?: true;\n    } & (K extends SurfaceEventType ? {\n        sourceEventSeqs?: number[];\n        surfaceOp?: SurfaceOp;\n    } : object);\n}[T];',
+    declaration: 'export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n    [K in SessionEventType]: {\n        type: K;\n        seq: SessionSeq;\n        time: number;\n        data: SessionEventMap[K];\n        ignorable?: true;\n    } & (K extends SurfaceEventType ? {\n        sourceEventSeqs?: SessionSeq[];\n        surfaceOp?: SurfaceOp;\n    } : object);\n}[T];',
   },
   {
     name: 'SessionEventEntry',
@@ -4852,11 +4860,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionEventReadRequest',
-    declaration: 'export interface SessionEventReadRequest {\n    sessionId: SessionId;\n    seq: number;\n    before?: number;\n    after?: number;\n}',
+    declaration: 'export interface SessionEventReadRequest {\n    sessionId: SessionId;\n    seq: SessionSeq;\n    before?: number;\n    after?: number;\n}',
   },
   {
     name: 'SessionEventRecord',
-    declaration: 'export interface SessionEventRecord {\n    sessionId: SessionId;\n    seq: number;\n    type: SessionEventType;\n    time: number;\n    surface: SessionEventSurface;\n}',
+    declaration: 'export interface SessionEventRecord {\n    sessionId: SessionId;\n    seq: SessionSeq;\n    type: SessionEventType;\n    time: number;\n    surface: SessionEventSurface;\n}',
   },
   {
     name: 'SessionEventResultFilter',
@@ -4878,13 +4886,17 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionEventSearchRequest',
     declaration: 'export interface SessionEventSearchRequest {\n    sessionId: SessionId;\n    query: string;\n    filters?: readonly SessionEventMetadataFilter[];\n    limit?: number;\n    cursor?: SessionSearchCursor;\n}',
   },
+  {
+    name: 'SessionEventSuffix',
+    declaration: 'export interface SessionEventSuffix extends SessionStorageMetadata {\n    readonly fromSeq: SessionLogOffset;\n    readonly events: readonly SessionEvent[];\n}',
+  },
   {
     name: 'SessionEventSurface',
     declaration: 'export type SessionEventSurface = \'current\' | \'shadowed\' | \'log-only\';',
   },
   {
     name: 'SessionEventTrace',
-    declaration: 'export interface SessionEventTrace {\n    target: SessionEventRecord;\n    replacedBy?: number;\n    replacementChain: number[];\n    replacedEventSeqs: number[];\n    sourceEventSeqs: number[];\n    derivedEventSeqs: number[];\n}',
+    declaration: 'export interface SessionEventTrace {\n    target: SessionEventRecord;\n    replacedBy?: SessionSeq;\n    replacementChain: SessionSeq[];\n    replacedEventSeqs: SessionSeq[];\n    sourceEventSeqs: SessionSeq[];\n    derivedEventSeqs: SessionSeq[];\n}',
   },
   {
     name: 'SessionEventTraceObservation',
@@ -4892,7 +4904,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionEventTraceRequest',
-    declaration: 'export interface SessionEventTraceRequest {\n    sessionId: SessionId;\n    seq: number;\n}',
+    declaration: 'export interface SessionEventTraceRequest {\n    sessionId: SessionId;\n    seq: SessionSeq;\n}',
   },
   {
     name: 'SessionEventType',
@@ -4900,11 +4912,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionEventWindow',
-    declaration: 'export interface SessionEventWindow {\n    session: SessionHeader;\n    target: SessionEvent;\n    events: SessionEvent[];\n    startSeq: number;\n    endSeq: number;\n}',
+    declaration: 'export interface SessionEventWindow {\n    session: SessionHeader;\n    inheritedEventCount: SessionLogOffset;\n    target: SessionEvent;\n    events: SessionEvent[];\n    startSeq: SessionSeq;\n    endSeq: SessionSeq;\n}',
   },
   {
     name: 'SessionFollowFrame',
-    declaration: 'export type SessionFollowFrame = {\n    readonly type: \'snapshot\';\n    readonly header: SessionHeader;\n    readonly cursor: number;\n    readonly records: readonly SessionHistoryRecord[];\n    readonly hasMore: boolean;\n    readonly projections: SessionProjectionBaseline;\n} | SessionEventEntry;',
+    declaration: 'export type SessionFollowFrame = {\n    readonly type: \'snapshot\';\n    readonly header: SessionWireHeader;\n    readonly cursor: number;\n    readonly records: readonly SessionHistoryRecord[];\n    readonly hasMore: boolean;\n    readonly projections: SessionProjectionBaseline;\n} | SessionEventEntry;',
   },
   {
     name: 'SessionFollowRequest',
@@ -4924,7 +4936,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionHeader',
-    declaration: 'export interface SessionHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly seedLength?: number;\n    readonly origin?: \'subagent\';\n    readonly delegationDepth?: number;\n    readonly agentPreset?: string;\n}',
+    declaration: 'export interface SessionHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly isSeeded: boolean;\n    readonly origin?: \'subagent\';\n    readonly delegationDepth?: number;\n    readonly agentPreset?: string;\n}',
   },
   {
     name: 'SessionHistoryRecord',
@@ -4936,7 +4948,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionInspection',
-    declaration: 'export interface SessionInspection {\n    readonly meta: SessionHeader;\n    readonly events: readonly SessionEvent[];\n}',
+    declaration: 'export interface SessionInspection extends SessionStorageMetadata {\n    readonly events: readonly SessionEvent[];\n}',
   },
   {
     name: 'SessionJob',
@@ -4962,13 +4974,17 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionLocation',
     declaration: 'export interface SessionLocation {\n    readonly kind: string;\n    readonly path: string;\n}',
   },
+  {
+    name: 'SessionLogOffset',
+    declaration: 'export type SessionLogOffset = BrandedNumber<\'SessionLogOffset\'>;',
+  },
   {
     name: 'SessionLogSnapshot',
-    declaration: 'export interface SessionLogSnapshot {\n    session: SessionHeader;\n    events: SessionEvent[];\n}',
+    declaration: 'export interface SessionLogSnapshot {\n    session: SessionHeader;\n    inheritedEventCount: SessionLogOffset;\n    events: SessionEvent[];\n}',
   },
   {
     name: 'SessionObservation',
-    declaration: 'export interface SessionObservation extends Disposable {\n    readonly source: \'live\' | \'prepared\';\n    readonly header: SessionHeader;\n    readonly events: readonly SessionEvent[];\n    readonly cursor: number;\n    readonly revision?: SessionPersistenceRevision;\n    readonly projections?: ProjectionSnapshot;\n    retain(): SessionObservation;\n}',
+    declaration: 'export interface SessionObservation extends Disposable {\n    readonly source: \'live\' | \'prepared\';\n    readonly header: SessionHeader;\n    readonly events: readonly SessionEvent[];\n    readonly inheritedEventCount: SessionLogOffsetType;\n    readonly cursor: SessionSeqCursor;\n    readonly revision?: SessionPersistenceRevision;\n    readonly projections?: ProjectionSnapshot;\n    retain(): SessionObservation;\n}',
   },
   {
     name: 'SessionObservationOptions',
@@ -5048,7 +5064,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionRawArtifact',
-    declaration: 'export interface SessionRawArtifact {\n    readonly meta: SessionHeader;\n    readonly filename: string;\n    readonly content: string;\n}',
+    declaration: 'export interface SessionRawArtifact extends SessionStorageMetadata {\n    readonly filename: string;\n    readonly content: string;\n}',
   },
   {
     name: 'SessionRecord',
@@ -5118,21 +5134,33 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionSelectModelValue',
     declaration: 'export interface SessionSelectModelValue {\n    readonly selected: ModelSelection;\n}',
   },
+  {
+    name: 'SessionSeq',
+    declaration: 'export type SessionSeq = BrandedNumber<\'SessionSeq\'>;',
+  },
+  {
+    name: 'SessionSeqCursor',
+    declaration: 'export type SessionSeqCursor = SessionSeq | -1;',
+  },
   {
     name: 'SessionStartSource',
     declaration: 'export type SessionStartSource = \'startup\' | \'resume\' | \'clear\' | \'compact\';',
   },
+  {
+    name: 'SessionStorageMetadata',
+    declaration: 'export interface SessionStorageMetadata {\n    readonly meta: SessionHeader;\n    readonly inheritedEventCount: SessionLogOffset;\n}',
+  },
   {
     name: 'SessionSummary',
     declaration: 'export interface SessionSummary {\n    readonly sessionId: SessionId;\n    readonly updatedAt: number;\n    readonly running: boolean;\n    readonly blank: boolean;\n    readonly parentSessionId?: SessionId;\n    readonly origin?: \'subagent\';\n    readonly cwd?: string;\n    readonly projections?: SessionProjectionHints;\n}',
   },
   {
     name: 'SessionSurface',
-    declaration: 'export interface SessionSurface {\n    readonly nodes: readonly number[];\n    readonly replaceGeneration: number;\n}',
+    declaration: 'export interface SessionSurface {\n    readonly nodes: readonly SessionSeq[];\n    readonly replaceGeneration: number;\n}',
   },
   {
     name: 'SessionSurfaceSnapshot',
-    declaration: 'export interface SessionSurfaceSnapshot {\n    session: SessionHeader;\n    capturedThroughSeq: number | null;\n    events: SurfaceEvent[];\n}',
+    declaration: 'export interface SessionSurfaceSnapshot {\n    session: SessionHeader;\n    inheritedEventCount: SessionLogOffset;\n    capturedThroughSeq: OptionalSessionSeq;\n    events: SurfaceEvent[];\n}',
   },
   {
     name: 'SessionTelemetryRecord',
@@ -5152,7 +5180,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionTitleEventData',
-    declaration: 'export interface SessionTitleEventData {\n    readonly title: string;\n    readonly messageSeqs: number[];\n    readonly source: SessionTitleSource;\n}',
+    declaration: 'export interface SessionTitleEventData {\n    readonly title: string;\n    readonly messageSeqs: SessionSeq[];\n    readonly source: SessionTitleSource;\n}',
   },
   {
     name: 'SessionTitleModelProvenance',
@@ -5176,11 +5204,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionTitleProviderResult',
-    declaration: 'export interface SessionTitleProviderResult {\n    readonly title: string;\n    readonly messageSeqs: readonly number[];\n    readonly model?: SessionTitleModelProvenance;\n}',
+    declaration: 'export interface SessionTitleProviderResult {\n    readonly title: string;\n    readonly messageSeqs: readonly SessionSeq[];\n    readonly model?: SessionTitleModelProvenance;\n}',
   },
   {
     name: 'SessionTitleSnapshot',
-    declaration: 'export interface SessionTitleSnapshot extends SessionTitleEventData {\n    readonly eventSeq: number;\n    readonly updatedAt: number;\n}',
+    declaration: 'export interface SessionTitleSnapshot extends SessionTitleEventData {\n    readonly eventSeq: SessionSeq;\n    readonly updatedAt: number;\n}',
   },
   {
     name: 'SessionTitleSource',
@@ -5188,7 +5216,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionTitleUserMessage',
-    declaration: 'export interface SessionTitleUserMessage {\n    readonly seq: number;\n    readonly text: string;\n}',
+    declaration: 'export interface SessionTitleUserMessage {\n    readonly seq: SessionSeq;\n    readonly text: string;\n}',
   },
   {
     name: 'SessionUpdateQueueRequest',
@@ -5200,7 +5228,15 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionWireEvent',
-    declaration: 'export interface SessionWireEvent {\n    readonly type: string;\n    readonly seq: number;\n    readonly time: number;\n    readonly data: JsonValue;\n    readonly ignorable?: true;\n    readonly sourceEventSeqs?: number[];\n    readonly surfaceOp?: SurfaceOp;\n}',
+    declaration: 'export interface SessionWireEvent {\n    readonly type: string;\n    readonly seq: number;\n    readonly time: number;\n    readonly data: JsonValue;\n    readonly ignorable?: true;\n    readonly sourceEventSeqs?: number[];\n    readonly surfaceOp?: SessionWireSurfaceOp;\n}',
+  },
+  {
+    name: 'SessionWireHeader',
+    declaration: 'export interface SessionWireHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly seedLength?: number;\n    readonly origin?: \'subagent\';\n    readonly delegationDepth?: number;\n    readonly agentPreset?: string;\n}',
+  },
+  {
+    name: 'SessionWireSurfaceOp',
+    declaration: 'export type SessionWireSurfaceOp = \'append\' | {\n    readonly op: \'replace\';\n    readonly start: number;\n    readonly end: number;\n};',
   },
   {
     name: 'SettingsApplies',
@@ -5536,11 +5572,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SurfaceIntent',
-    declaration: 'export interface SurfaceIntent {\n    surfaceOp: SurfaceOp;\n    sourceEventSeqs?: number[];\n}',
+    declaration: 'export interface SurfaceIntent {\n    surfaceOp: SurfaceOp;\n    sourceEventSeqs?: SessionSeq[];\n}',
   },
   {
     name: 'SurfaceOp',
-    declaration: 'export type SurfaceOp = \'append\' | {\n    op: \'replace\';\n    start: number;\n    end: number;\n};',
+    declaration: 'export type SurfaceOp = \'append\' | {\n    op: \'replace\';\n    start: SessionSeq;\n    end: SessionSeq;\n};',
   },
   {
     name: 'SystemPrompt',
@@ -5680,7 +5716,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TokenMeasurement',
-    declaration: 'export interface TokenMeasurement {\n    readonly logRevision: number;\n    readonly baseline: TokenMeasurementBaseline;\n    readonly surfaceDeltaTokens: number;\n    readonly totalTokens: number;\n    readonly surfaceTokens: number;\n    readonly nodes: readonly TokenSurfaceNode[];\n}',
+    declaration: 'export interface TokenMeasurement {\n    readonly logRevision: SessionLogOffset;\n    readonly baseline: TokenMeasurementBaseline;\n    readonly surfaceDeltaTokens: number;\n    readonly totalTokens: number;\n    readonly surfaceTokens: number;\n    readonly nodes: readonly TokenSurfaceNode[];\n}',
   },
   {
     name: 'TokenMeasurementBaseline',
@@ -5688,7 +5724,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TokenSurfaceNode',
-    declaration: 'export interface TokenSurfaceNode {\n    readonly seq: number;\n    readonly tokens: number;\n    readonly heuristicTokens: number;\n}',
+    declaration: 'export interface TokenSurfaceNode {\n    readonly seq: SessionSeq;\n    readonly tokens: number;\n    readonly heuristicTokens: number;\n}',
   },
   {
     name: 'TokenUsage',
diff --git a/packages/feedback/message-feedback/src/index.ts b/packages/feedback/message-feedback/src/index.ts
index 65ffd0c279..e07a8b809c 100644
--- a/packages/feedback/message-feedback/src/index.ts
+++ b/packages/feedback/message-feedback/src/index.ts
@@ -7,6 +7,7 @@ import { Buffer } from 'node:buffer'
 import { randomUUID } from 'node:crypto'
 import { Context, Service } from '@deepseek-ai/cordis'
 import s from '@deepseek-ai/schemastery'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import { deriveEventMessage, isAppendSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence'
@@ -333,9 +334,15 @@ export class MessageFeedbackService extends TypertRemoteService {
           `message-feedback: no durability listener participated for live session '${inspection.meta.id}'`,
         )
       }
-      return await this.ctx.sessionPersistence.readFrom(inspection.meta.id, 0)
+      return await this.ctx.sessionPersistence.readFrom(
+        inspection.meta.id,
+        SessionLogOffset(0),
+      )
     }
-    return await this.ctx.sessionPersistence.readFrom(inspection.meta.id, 0)
+    return await this.ctx.sessionPersistence.readFrom(
+      inspection.meta.id,
+      SessionLogOffset(0),
+    )
   }
 
   /** Validate optional-note semantics and the configured complete UTF-8 byte bound. */
diff --git a/packages/feedback/message-feedback/tests/helpers.ts b/packages/feedback/message-feedback/tests/helpers.ts
index 748373856d..3ae1363506 100644
--- a/packages/feedback/message-feedback/tests/helpers.ts
+++ b/packages/feedback/message-feedback/tests/helpers.ts
@@ -8,11 +8,14 @@ import SessionStore, {
   SESSION_FORMAT_VERSION,
   Session,
   SessionId,
+  SessionLogOffset,
   type SessionEvent,
   type SessionHeader,
+  type SessionLogOffset as SessionLogOffsetType,
 } from '@deepseek-ai/dsh-session'
 import SessionPersistence, {
   SessionPersistenceRevision,
+  type SessionEventSuffix,
   type SessionInspection,
   type SessionLocation,
   type SessionPersistenceSnapshot,
@@ -101,6 +104,7 @@ export function messageFixture(
     version: SESSION_FORMAT_VERSION,
     id,
     createdAt: options.createdAt ?? 1_700_000_000_000,
+    isSeeded: false,
     ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
   }
   const session = Session.create(id, [], header)
@@ -126,7 +130,7 @@ class TestPersistence extends SessionPersistence {
   append(_id: SessionId, _events: readonly SessionEvent[]): Promise<void> { return Promise.resolve() }
 
   load(id: SessionId): Promise<SessionInspection> {
-    return this.readFrom(id, 0)
+    return this.readFrom(id, SessionLogOffset(0))
   }
 
   inspect(id: SessionId): Promise<SessionInspection> {
@@ -135,7 +139,13 @@ class TestPersistence extends SessionPersistence {
     const explicit = this.logical.get(id)
     if (explicit !== undefined) return Promise.resolve(explicit)
     const live = this.ctx.sessions.get(id)
-    if (live !== undefined) return Promise.resolve({ meta: live.header, events: live.snapshotEvents() })
+    if (live !== undefined) {
+      return Promise.resolve({
+        meta: live.header,
+        inheritedEventCount: live.inheritedEventCount,
+        events: live.snapshotEvents(),
+      })
+    }
     const stored = this.durable.get(id)
     return stored === undefined
       ? Promise.reject(new Error(`test persistence: session '${id}' not found`))
@@ -148,14 +158,19 @@ class TestPersistence extends SessionPersistence {
 
   async readFrom(
     id: SessionId,
-    fromSeq: number,
-  ): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    fromSeq: SessionLogOffsetType,
+  ): Promise<SessionEventSuffix> {
     this.readFromCalls += 1
     await this.onReadFrom?.()
     const stored = this.durable.get(id)
     return stored === undefined
       ? Promise.reject(new Error(`test persistence: session '${id}' not found`))
-      : { meta: stored.meta, events: stored.events.filter(event => event.seq >= fromSeq) }
+      : {
+        meta: stored.meta,
+        inheritedEventCount: stored.inheritedEventCount,
+        fromSeq,
+        events: stored.events.filter(event => event.seq >= fromSeq),
+      }
   }
 
   list(): Promise<SessionHeader[]> {
@@ -171,7 +186,11 @@ class TestPersistence extends SessionPersistence {
   }
 
   persist(session: Session): void {
-    this.durable.set(session.id, { meta: session.header, events: session.snapshotEvents() })
+    this.durable.set(session.id, {
+      meta: session.header,
+      inheritedEventCount: session.inheritedEventCount,
+      events: session.snapshotEvents(),
+    })
   }
 
   setDurable(inspection: SessionInspection): void {
diff --git a/packages/feedback/message-feedback/tests/loader-composition.spec.ts b/packages/feedback/message-feedback/tests/loader-composition.spec.ts
index b433532adc..a682dfd3d9 100644
--- a/packages/feedback/message-feedback/tests/loader-composition.spec.ts
+++ b/packages/feedback/message-feedback/tests/loader-composition.spec.ts
@@ -6,7 +6,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import Include from '@deepseek-ai/cordis-plugin-include'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import Storage from '@deepseek-ai/dsh-storage'
 import * as StorageDomain from '@deepseek-ai/dsh-storage-domain'
@@ -97,7 +97,7 @@ describe('message feedback through a real Loader composition', () => {
       ifVersion: null,
     })
     if (!put.ok) throw new Error(`expected put success, got ${put.error.code}`)
-    const durable = await first.sessionPersistence.readFrom(session.id, 0)
+    const durable = await first.sessionPersistence.readFrom(session.id, SessionLogOffset(0))
     expect(durable.events.some(event =>
       event.type === 'assistant/message'
       && event.data.message.id === fixture.assistantMessageIds[0])).toBe(true)
diff --git a/packages/feedback/message-feedback/tests/message-feedback.spec.ts b/packages/feedback/message-feedback/tests/message-feedback.spec.ts
index 82c49a93b7..92b65ce2d4 100644
--- a/packages/feedback/message-feedback/tests/message-feedback.spec.ts
+++ b/packages/feedback/message-feedback/tests/message-feedback.spec.ts
@@ -62,7 +62,11 @@ describe('MessageFeedbackService public contract', () => {
     })
 
     const fixture = messageFixture('corrupt-session')
-    persistence.setDurable({ meta: fixture.session.header, events: fixture.session.snapshotEvents() })
+    persistence.setDurable({
+      meta: fixture.session.header,
+      inheritedEventCount: fixture.session.inheritedEventCount,
+      events: fixture.session.snapshotEvents(),
+    })
     const corruption = new Error('stored log checksum mismatch')
     persistence.inspectFailure = corruption
     await expect(ctx.messageFeedback.list({ sessionId: fixture.session.id })).rejects.toBe(corruption)
@@ -518,9 +522,14 @@ describe('MessageFeedbackService durability ordering', () => {
     const fixture = messageFixture('cold-prefix')
     persistence.logical.set(fixture.session.id, {
       meta: fixture.session.header,
+      inheritedEventCount: fixture.session.inheritedEventCount,
       events: fixture.session.snapshotEvents(),
     })
-    persistence.setDurable({ meta: fixture.session.header, events: [] })
+    persistence.setDurable({
+      meta: fixture.session.header,
+      inheritedEventCount: fixture.session.inheritedEventCount,
+      events: [],
+    })
 
     await expect(ctx.messageFeedback.put({
       sessionId: fixture.session.id,
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index bb14264f6d..8f75a0b513 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -32,6 +32,7 @@ import { sessionCwd } from '../src/session-cwd.ts'
 import ApprovalService from '@deepseek-ai/dsh-user-approval'
 import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 
 const testToolSignal = new AbortController().signal
@@ -805,19 +806,45 @@ describe('sandbox escalation API (write/edit)', () => {
   }
 
   /** A fake agent whose session records appends (the approval audit trail), mid-turn, carrying the given events for the fold. */
-  function escalationAgent(events: Array<{ type: string; data?: Record<string, unknown> }> = []): object {
-    const log = [
-      { type: 'turn/start', data: { turn: 1 }, seq: 0 },
-      ...events.map((event, index) => ({ ...event, seq: index + 1 })),
+  function escalationAgent(records: Array<{ type: string; data?: Record<string, unknown> }> = []): object {
+    const id = SessionId('sess-fs-esc')
+    const events: Array<{
+      type: string
+      seq: ReturnType<typeof SessionSeq>
+      time: number
+      data: Record<string, unknown>
+    }> = [
+      { type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 } },
+      ...records.map((record, index) => ({
+        type: record.type,
+        seq: SessionSeq(index + 1),
+        time: index + 1,
+        data: record.data ?? {},
+      })),
     ]
     return {
-      id: 'agent-fs-esc',
+      id,
       session: {
-        header: { version: 0, id: 'sess-fs-esc', createdAt: 0, cwd: '/session-project' },
-        get seq() { return log.length },
-        eventAt: (seq: number) => log[seq],
-        snapshotEvents: () => log,
-        append: (type: string, data: Record<string, unknown>) => { log.push({ type, data, seq: log.length }) },
+        id,
+        header: { version: 0, id, createdAt: 0, cwd: '/session-project', isSeeded: false },
+        inheritedEventCount: SessionLogOffset(0),
+        firstLiveSeq: SessionLogOffset(0),
+        get seq() { return SessionLogOffset(events.length) },
+        eventAt: (seq: ReturnType<typeof SessionSeq>) => events[seq],
+        snapshotEvents: (
+          fromSeq = SessionLogOffset(0),
+          toSeqExclusive = SessionLogOffset(events.length),
+        ) => events.slice(fromSeq, toSeqExclusive),
+        append: (type: string, data: Record<string, unknown>) => {
+          const event = {
+            type,
+            seq: SessionSeq(events.length),
+            time: events.length,
+            data,
+          }
+          events.push(event)
+          return event
+        },
       },
     }
   }
@@ -858,13 +885,21 @@ describe('sandbox escalation API (write/edit)', () => {
   it('a plain write stamps the default mode with the calling session root', async () => {
     const { ctx, fs } = await setupConfining()
     await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent())
-    expect(fs.stamped).toEqual([{ mode: 'workspace-write', workspaceRoot: resolve('/session-project') }])
+    expect(fs.stamped).toEqual([{
+      mode: 'workspace-write',
+      workspaceRoot: resolve('/session-project'),
+      sessionId: SessionId('sess-fs-esc'),
+    }])
   })
 
   it('a standing session override folds onto the stamp', async () => {
     const { ctx, fs } = await setupConfining()
     await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent([{ type: 'sandbox/mode', data: { mode: 'read-only' } }]))
-    expect(fs.stamped).toEqual([{ mode: 'read-only', workspaceRoot: resolve('/session-project') }])
+    expect(fs.stamped).toEqual([{
+      mode: 'read-only',
+      workspaceRoot: resolve('/session-project'),
+      sessionId: SessionId('sess-fs-esc'),
+    }])
   })
 
   it('a denied write maps to the shared marker plus the escalation hint (isError)', async () => {
@@ -897,7 +932,11 @@ describe('sandbox escalation API (write/edit)', () => {
       agent: escalationAgent() as never,
       signal: new AbortController().signal,
     })
-    expect(fs.stamped).toEqual([{ mode: 'danger-full-access', workspaceRoot: resolve('/session-project') }])
+    expect(fs.stamped).toEqual([{
+      mode: 'danger-full-access',
+      workspaceRoot: resolve('/session-project'),
+      sessionId: SessionId('sess-fs-esc'),
+    }])
   })
 
   it('a rejected escalation fails closed with its own text and never mutates', async () => {
diff --git a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
index 5d1faafea3..0965db21d2 100644
--- a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
+++ b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
@@ -29,7 +29,7 @@ afterEach(async () => {
 function agent(ctx: Context, cwd: string): Agent {
   const id = SessionId(`str-replace-editor-owner-${callNumber}`)
   const scope = ctx.plugin(() => {})
-  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd })
+  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd, isSeeded: false })
   const value: Agent = {
     id,
     options: {},
diff --git a/packages/goal/goal/src/index.ts b/packages/goal/goal/src/index.ts
index 238e0c4ae5..77a8a2495e 100644
--- a/packages/goal/goal/src/index.ts
+++ b/packages/goal/goal/src/index.ts
@@ -11,7 +11,8 @@ import { z as zod } from 'zod'
 import type { ZodType } from 'zod'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionLogOffset } from '@deepseek-ai/dsh-session'
 import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol'
 import type {} from '@deepseek-ai/dsh-session-projection'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
@@ -182,7 +183,10 @@ export interface ResolvedConfig {
 /** Process-local activation state crossing the synchronous append boundary. */
 interface GoalRuntimeState {
   activation: GoalActivation
-  pendingActivation: { readonly seq: number; readonly activation: GoalActivation } | undefined
+  pendingActivation: {
+    readonly offset: SessionLogOffset
+    readonly activation: GoalActivation
+  } | undefined
 }
 
 /** Validated create input with every deployment default materialized. */
@@ -255,7 +259,8 @@ export class GoalService extends TypertRemoteService {
     ctx.on('session/event', (session, event) => {
       if (event.type !== 'goal/change') return
       const runtime = this.runtimeState(session)
-      runtime.activation = runtime.pendingActivation?.seq === event.seq
+      runtime.activation = runtime.pendingActivation !== undefined
+        && SessionSeq(runtime.pendingActivation.offset) === event.seq
         ? runtime.pendingActivation.activation
         : 'disarmed'
     })
@@ -579,11 +584,11 @@ export class GoalService extends TypertRemoteService {
   /** Commit one mutation into the goal log and live event stream. */
   private commit(agent: Agent, runtime: GoalRuntimeState, change: GoalChangeMeta, activation: GoalActivation): void {
     const ref = goalChangeRef(change)
-    runtime.pendingActivation = { seq: agent.session.seq, activation }
+    runtime.pendingActivation = { offset: agent.session.seq, activation }
     try {
       const event = agent.session.append('goal/change', change)
       /* v8 ignore next -- Session.append returns the event committed at the pre-append seq. */
-      if (runtime.pendingActivation.seq === event.seq) runtime.activation = activation
+      if (SessionSeq(runtime.pendingActivation.offset) === event.seq) runtime.activation = activation
     } finally {
       runtime.pendingActivation = undefined
     }
diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts
index 9bc98bee74..d72ac7c751 100644
--- a/packages/goal/goal/tests/goal.spec.ts
+++ b/packages/goal/goal/tests/goal.spec.ts
@@ -199,7 +199,8 @@ describe('GoalService creation and replay', () => {
       activation: 'disarmed',
     })
     expect(child.session.header.parentSession).toBe(parent.session.id)
-    expect(child.session.header.seedLength).toBe(parent.session.seq)
+    expect(child.session.header.isSeeded).toBe(true)
+    expect(child.session.inheritedEventCount).toBe(parent.session.seq)
   })
 
   it('disarms live activation on every session-start edge', async () => {
diff --git a/packages/goal/tool-goal/src/authority.ts b/packages/goal/tool-goal/src/authority.ts
index 29a820c8df..34d3108e5d 100644
--- a/packages/goal/tool-goal/src/authority.ts
+++ b/packages/goal/tool-goal/src/authority.ts
@@ -4,7 +4,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { GoalView } from '@deepseek-ai/dsh-goal'
 import { HarnessError } from '@deepseek-ai/dsh-llm'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { ToolRunContext } from '@deepseek-ai/dsh-tools'
 import type {} from '@deepseek-ai/dsh-session-projection'
 
@@ -12,7 +12,7 @@ import type {} from '@deepseek-ai/dsh-session-projection'
 export interface GoalToolExecution {
   readonly agent: Agent
   readonly events: readonly SessionEvent[]
-  readonly openTurnStartSeq: number
+  readonly openTurnStartSeq: SessionSeq
 }
 
 /** Hard authority granted to one state-changing call. */
diff --git a/packages/goal/tool-goal/tests/tool-goal.spec.ts b/packages/goal/tool-goal/tests/tool-goal.spec.ts
index ab544d1b9c..1839a9ecdf 100644
--- a/packages/goal/tool-goal/tests/tool-goal.spec.ts
+++ b/packages/goal/tool-goal/tests/tool-goal.spec.ts
@@ -8,7 +8,12 @@ import GoalService, { GoalId } from '@deepseek-ai/dsh-goal'
 import type { GoalRef } from '@deepseek-ai/dsh-goal'
 import { createUserMessage, ToolCallId } from '@deepseek-ai/dsh-llm'
 import type { MessageSource } from '@deepseek-ai/dsh-llm'
-import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
+import {
+  SESSION_FORMAT_VERSION,
+  Session,
+  SessionId,
+  SessionLogOffset,
+} from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime from '@deepseek-ai/dsh-tools'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
@@ -267,8 +272,8 @@ describe('goal tool execution authority', () => {
       id: forkId,
       createdAt: Date.now(),
       parentSession: root.session.id,
-      seedLength: root.session.seq,
-    })
+      isSeeded: true,
+    }, SessionLogOffset(root.session.seq))
     const fork = stubAgent(forkId, forkSession)
     ctx.agents.register(fork.agent)
     expect(ctx.goals.get(fork.agent)).toMatchObject({ id: created.id, activation: 'disarmed' })
diff --git a/packages/hooks/hook-protocol/tests/invariant.spec.ts b/packages/hooks/hook-protocol/tests/invariant.spec.ts
index bcfef7261e..449ce4c6ae 100644
--- a/packages/hooks/hook-protocol/tests/invariant.spec.ts
+++ b/packages/hooks/hook-protocol/tests/invariant.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import * as HookInvariant from '@deepseek-ai/dsh-hook-protocol/invariant'
 import InvariantRegistry from '@deepseek-ai/dsh-invariants'
 
@@ -62,14 +62,14 @@ describe('hook-protocol invariants', () => {
     const session = Session.create(SessionId('bare-hook-session'))
     expect(() => {
       ctx.emit('session/event', session, {
-        type: 'turn/start', seq: 0, time: 0,
+        type: 'turn/start', seq: SessionSeq(0), time: 0,
         data: { turn: 1 },
       })
       ctx.emit('session/event', session, {
-        type: 'hook/invoked', seq: 1, time: 1, data: invoked(),
+        type: 'hook/invoked', seq: SessionSeq(1), time: 1, data: invoked(),
       })
       ctx.emit('session/event', session, {
-        type: 'hook/result', seq: 2, time: 2, data: result(),
+        type: 'hook/result', seq: SessionSeq(2), time: 2, data: result(),
       })
     }).not.toThrow()
   })
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index b0b3a0dd45..b7cdeb0b4a 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -11,6 +11,7 @@ import type { EncodedImageAttachment } from '@deepseek-ai/dsh-attachment/types'
 import type { ImageBlock } from '@deepseek-ai/dsh-llm'
 import { NamedEntries, ScopedLayers } from '@deepseek-ai/dsh-scope'
 import type { ScopeKey, ScopeLayer } from '@deepseek-ai/dsh-scope'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionEventMap } from '@deepseek-ai/dsh-session'
 import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol'
 import { CommandId } from './brand.ts'
@@ -225,13 +226,15 @@ function normalizeResult(command: string, value: unknown): CommandResult {
       throw new TypeError(`command "${command}" success text must be a string when supplied`)
     }
     if (result.sourceEventSeq !== undefined
-      && (!Number.isSafeInteger(result.sourceEventSeq) || (result.sourceEventSeq as number) < 0)) {
+      && (!Number.isSafeInteger(result.sourceEventSeq)
+        || (result.sourceEventSeq as number) < 0
+        || Object.is(result.sourceEventSeq, -0))) {
       throw new TypeError(`command "${command}" success sourceEventSeq must be a non-negative safe integer when supplied`)
     }
     return Object.freeze({
       kind: 'success',
       ...result.text === undefined ? {} : { text: result.text },
-      ...result.sourceEventSeq === undefined ? {} : { sourceEventSeq: result.sourceEventSeq as number },
+      ...result.sourceEventSeq === undefined ? {} : { sourceEventSeq: SessionSeq(result.sourceEventSeq as number) },
     })
   }
   if (result.kind === 'error') {
diff --git a/packages/interaction/commands/src/types.ts b/packages/interaction/commands/src/types.ts
index 621a5971ba..0ca87c778d 100644
--- a/packages/interaction/commands/src/types.ts
+++ b/packages/interaction/commands/src/types.ts
@@ -7,6 +7,7 @@
  * @module @deepseek-ai/dsh-commands/types
  */
 
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { CommandId } from './brand.ts'
 
 /** Immutable metadata for a command's optional unstructured input. */
@@ -29,7 +30,7 @@ export type CommandResult =
     readonly kind: 'success'
     readonly text?: string
     /** Earlier authoritative domain event that owns a richer presentation. */
-    readonly sourceEventSeq?: number
+    readonly sourceEventSeq?: SessionSeq
   }
   | { readonly kind: 'error'; readonly text: string }
 
@@ -104,7 +105,7 @@ declare module '@deepseek-ai/dsh-session/types' {
       commandId: CommandId
       kind: 'success' | 'error'
       text?: string
-      sourceEventSeq?: number
+      sourceEventSeq?: import('@deepseek-ai/dsh-session/types').SessionSeq
     }
   }
 }
diff --git a/packages/interaction/commands/tests/commands.spec.ts b/packages/interaction/commands/tests/commands.spec.ts
index 655cdc5462..01a31e205c 100644
--- a/packages/interaction/commands/tests/commands.spec.ts
+++ b/packages/interaction/commands/tests/commands.spec.ts
@@ -448,6 +448,7 @@ describe('CommandRuntime', () => {
     [{}, /CommandResult/],
     [{ kind: 'success', text: 1 }, /success text/],
     [{ kind: 'success', sourceEventSeq: -1 }, /sourceEventSeq/],
+    [{ kind: 'success', sourceEventSeq: -0 }, /sourceEventSeq/],
     [{ kind: 'success', sourceEventSeq: 1.5 }, /sourceEventSeq/],
     [{ kind: 'success', sourceEventSeq: '1' }, /sourceEventSeq/],
     [{ kind: 'error', text: '' }, /error text/],
diff --git a/packages/interaction/commands/tests/invariant.spec.ts b/packages/interaction/commands/tests/invariant.spec.ts
index 68124082b4..f6dbd9c997 100644
--- a/packages/interaction/commands/tests/invariant.spec.ts
+++ b/packages/interaction/commands/tests/invariant.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import * as CommandInvariant from '@deepseek-ai/dsh-commands/invariant'
 import InvariantRegistry, { InvariantError } from '@deepseek-ai/dsh-invariants'
-import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionSeq, type Session } from '@deepseek-ai/dsh-session'
 import { CommandId } from '@deepseek-ai/dsh-commands'
 
 async function mount(installCompanion = true): Promise<{ ctx: Context; session: Session }> {
@@ -46,7 +46,7 @@ describe('command lifecycle invariants', () => {
       session.append('command/done', {
         commandId: CommandId('cmd-invalid'),
         kind: 'success',
-        sourceEventSeq,
+        sourceEventSeq: sourceEventSeq as never,
       })
     }).toThrow(expect.objectContaining<Partial<InvariantError>>({
       code: 'INVARIANT',
@@ -78,7 +78,7 @@ describe('command lifecycle invariants', () => {
     session.append('command/done', {
       commandId: CommandId('cmd-late'),
       kind: 'success',
-      sourceEventSeq: 0,
+      sourceEventSeq: SessionSeq(0),
     })
 
     await expect(ctx.plugin(CommandInvariant)).rejects.toMatchObject({
diff --git a/packages/interaction/permission-presets/tests/invariant.spec.ts b/packages/interaction/permission-presets/tests/invariant.spec.ts
index fd5c8aa9e9..2d821482f3 100644
--- a/packages/interaction/permission-presets/tests/invariant.spec.ts
+++ b/packages/interaction/permission-presets/tests/invariant.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context, Service } from '@deepseek-ai/cordis'
-import SessionStore, { type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionSeq, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
 import * as PermissionInvariant from '@deepseek-ai/dsh-permission-presets/invariant'
 import InvariantRegistry from '@deepseek-ai/dsh-invariants'
 
@@ -22,7 +22,7 @@ async function setup(): Promise<Context> {
 }
 
 function presetEvent(preset: string): SessionEvent {
-  return { type: 'permission/preset', seq: 0, time: 0, data: { preset } }
+  return { type: 'permission/preset', seq: SessionSeq(0), time: 0, data: { preset } }
 }
 
 describe('permission invariants', () => {
@@ -30,7 +30,7 @@ describe('permission invariants', () => {
     const ctx = await setup()
     expect(() => { ctx.emit('session/event', {} as Session, presetEvent('safe')) }).not.toThrow()
     expect(() => { ctx.emit('session/event', {} as Session, {
-      type: 'turn/end', seq: 0, time: 0, data: {},
+      type: 'turn/end', seq: SessionSeq(0), time: 0, data: {},
     } as SessionEvent) }).not.toThrow()
     expect(() => { ctx.emit('tools/change') }).not.toThrow()
   })
diff --git a/packages/interaction/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
index c59295d6e4..8e1a8d05d4 100644
--- a/packages/interaction/user-approval/src/index.ts
+++ b/packages/interaction/user-approval/src/index.ts
@@ -11,6 +11,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createUserMessage, type ToolCallId } from '@deepseek-ai/dsh-llm'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Session } from '@deepseek-ai/dsh-session'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 
 declare module '@deepseek-ai/cordis' {
@@ -75,7 +76,7 @@ const ASK_SENTENCE = 'Approval policy: ask. Operations that require approval may
  */
 function hasOpenTurn(session: Session): boolean {
   for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
-    const type = session.eventAt(seq)?.type
+    const type = session.eventAt(SessionSeq(seq))?.type
     if (type === 'turn/start') return true
     if (type === 'turn/end') return false
   }
@@ -242,7 +243,7 @@ export class ApprovalService extends Service {
    */
   overrideOf(session: Session): ApprovalPolicy | undefined {
     for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
-      const event = session.eventAt(seq)
+      const event = session.eventAt(SessionSeq(seq))
       if (event?.type === 'approval/policy') return event.data.policy
     }
     return undefined
diff --git a/packages/interaction/user-approval/tests/invariant.spec.ts b/packages/interaction/user-approval/tests/invariant.spec.ts
index 0fe77440e3..d5c845cc21 100644
--- a/packages/interaction/user-approval/tests/invariant.spec.ts
+++ b/packages/interaction/user-approval/tests/invariant.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import { ApprovalRequestId } from '@deepseek-ai/dsh-user-approval'
 import * as ApprovalInvariant from '@deepseek-ai/dsh-user-approval/invariant'
 import InvariantRegistry from '@deepseek-ai/dsh-invariants'
@@ -46,14 +46,14 @@ describe('approval invariants', () => {
     const session = Session.create(SessionId('bare-approval-session'))
     const id = ApprovalRequestId('bare-ask')
     const asked = {
-      type: 'approval/asked', seq: 0, time: 0, data: { id, toolName: 'bash' },
+      type: 'approval/asked', seq: SessionSeq(0), time: 0, data: { id, toolName: 'bash' },
     } as const
     const decided = {
-      type: 'approval/decided', seq: 1, time: 1, data: { id, outcome: 'rejected' as const },
+      type: 'approval/decided', seq: SessionSeq(1), time: 1, data: { id, outcome: 'rejected' as const },
     } as const
     expect(() => {
       ctx.emit('session/event', session, {
-        type: 'turn/start', seq: 0, time: 0,
+        type: 'turn/start', seq: SessionSeq(0), time: 0,
         data: { turn: 1 },
       })
       ctx.emit('session/event', session, asked)
diff --git a/packages/llm/token-meter/src/breakdown-projection.ts b/packages/llm/token-meter/src/breakdown-projection.ts
index ab67c0600c..bfd6f20aae 100644
--- a/packages/llm/token-meter/src/breakdown-projection.ts
+++ b/packages/llm/token-meter/src/breakdown-projection.ts
@@ -6,7 +6,7 @@
  */
 
 import { z } from 'zod'
-import { canonicalHeader } from '@deepseek-ai/dsh-session'
+import { canonicalHeader, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import { estimateSystemTokens, estimateToolsTokens } from './estimate.ts'
 import { foldSurfaceProjection } from './surface-projection.ts'
@@ -21,6 +21,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 
 /** Non-negative integer token count (the shared figure shape). */
 const tokenCount = z.number().int().nonnegative()
+const sessionSeq = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq)
 
 /** The context-breakdown state schema and source of its inferred type. */
 const contextBreakdownStateSchema = z.object({
@@ -28,8 +29,8 @@ const contextBreakdownStateSchema = z.object({
   toolsTokens: tokenCount,
   messageTokens: tokenCount,
   claim: z.object({
-    start: tokenCount,
-    end: tokenCount,
+    start: sessionSeq,
+    end: sessionSeq,
     tokens: tokenCount,
   }).optional(),
 }).strict()
diff --git a/packages/llm/token-meter/src/index.ts b/packages/llm/token-meter/src/index.ts
index d97d9d3fc2..5e045223e3 100644
--- a/packages/llm/token-meter/src/index.ts
+++ b/packages/llm/token-meter/src/index.ts
@@ -9,8 +9,14 @@ import z from '@deepseek-ai/schemastery'
 import { BlockAssembler } from '@deepseek-ai/dsh-llm'
 import type { LlmImageRequestPricing, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
 import { deepFreeze } from '@deepseek-ai/dsh-util-values'
-import type { EpochHeader, Session, SessionEvent } from '@deepseek-ai/dsh-session'
-import { canonicalHeader, headerEquals, isSurfaceEvent } from '@deepseek-ai/dsh-session'
+import type {
+  EpochHeader,
+  Session,
+  SessionEvent,
+  SessionLogOffset as SessionLogOffsetType,
+  SessionSeq as SessionSeqType,
+} from '@deepseek-ai/dsh-session'
+import { canonicalHeader, headerEquals, isSurfaceEvent, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 // Type-only: activates the `ctx.sessionProjections` Context declaration.
 import type {} from '@deepseek-ai/dsh-session-projection'
 import type {
@@ -48,7 +54,7 @@ interface MeasurementAnchor {
 }
 
 interface ReplayState {
-  consumedEvents: number
+  consumedEvents: SessionLogOffsetType
   header: EpochHeader | undefined
   surface: MeterSurfaceNode[]
   stepStart: { turn: number; step: number; nodes: readonly MeterSurfaceNode[] } | undefined
@@ -198,7 +204,7 @@ export class TokenMeter extends Service {
     let state = this.states.get(session)
     if (state === undefined) {
       state = {
-        consumedEvents: 0,
+        consumedEvents: SessionLogOffset(0),
         header: undefined,
         surface: [],
         stepStart: undefined,
@@ -209,9 +215,9 @@ export class TokenMeter extends Service {
 
     while (state.consumedEvents < session.seq) {
       // oxlint-disable-next-line typescript/no-non-null-assertion -- contiguous session seqs index the durable log
-      const event = session.eventAt(state.consumedEvents)!
+      const event = session.eventAt(SessionSeq(state.consumedEvents))!
       this._foldEvent(session, state, event)
-      state.consumedEvents += 1
+      state.consumedEvents = SessionLogOffset(state.consumedEvents + 1)
     }
     return state
   }
@@ -304,7 +310,7 @@ export class TokenMeter extends Service {
     if (sourceSeqs === undefined) return durableEventTokens
 
     const assembler = new BlockAssembler()
-    const seen = new Set<number>()
+    const seen = new Set<SessionSeqType>()
     for (const seq of sourceSeqs) {
       if (seq >= event.seq) {
         throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} is not earlier`)
diff --git a/packages/llm/token-meter/src/surface-fold.ts b/packages/llm/token-meter/src/surface-fold.ts
index 66824a2974..ae293a7f57 100644
--- a/packages/llm/token-meter/src/surface-fold.ts
+++ b/packages/llm/token-meter/src/surface-fold.ts
@@ -17,7 +17,7 @@
  */
 
 import { deriveEventMessage } from '@deepseek-ai/dsh-session'
-import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
+import type { SessionSeq, SurfaceEvent } from '@deepseek-ai/dsh-session'
 import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import { estimateMessage, estimateStructuralBlock } from './estimate.ts'
@@ -25,7 +25,7 @@ import { estimateMessage, estimateStructuralBlock } from './estimate.ts'
 /** One priced surface node with the image occurrences route pricing replaces. */
 export interface MeterSurfaceNode {
   /** Durable sequence number of the surface event. */
-  readonly seq: number
+  readonly seq: SessionSeq
   /** Fixed-heuristic price of the node's exact message. */
   readonly heuristicTokens: number
   /** Fixed-heuristic price with every image occurrence's structural price removed. */
@@ -61,7 +61,7 @@ function collectImages(blocks: readonly ContentBlock[], images: ImageAttachmentR
 }
 
 /** Build one priced node from a surface event's derived message. */
-function analyzeNode(seq: number, message: Message | null): MeterSurfaceNode {
+function analyzeNode(seq: SessionSeq, message: Message | null): MeterSurfaceNode {
   if (message === null) return { seq, heuristicTokens: 0, imageFreeTokens: 0, images: [] }
   const heuristicTokens = estimateMessage(message)
   const images: ImageAttachmentRef[] = []
diff --git a/packages/llm/token-meter/src/surface-projection.ts b/packages/llm/token-meter/src/surface-projection.ts
index 0dcc232a8c..84d5759376 100644
--- a/packages/llm/token-meter/src/surface-projection.ts
+++ b/packages/llm/token-meter/src/surface-projection.ts
@@ -17,7 +17,7 @@
  * @module @deepseek-ai/dsh-token-meter/surface-projection
  */
 
-import { deriveEventMessage, isSurfaceEvent } from '@deepseek-ai/dsh-session'
+import { deriveEventMessage, isSurfaceEvent, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 // Type-only: the `compaction/*` SessionEventMap merges (shadow-price events).
 import type {} from '@deepseek-ai/dsh-compaction'
@@ -30,9 +30,9 @@ import { estimateMessage } from './estimate.ts'
  */
 export interface ShadowPriceClaim {
   /** Declared inclusive first surface-node seq of the priced range. */
-  start: number
+  start: SessionSeq
   /** Declared inclusive last surface-node seq of the priced range. */
-  end: number
+  end: SessionSeq
   /** Heuristic tokens of the priced range under the fixed estimator. */
   tokens: number
 }
@@ -71,7 +71,11 @@ export function foldSurfaceProjection(
     const { shadowedRange, shadowedTokenCount } = event.data
     return {
       deltaTokens: 0,
-      claim: { start: shadowedRange.start, end: shadowedRange.end, tokens: shadowedTokenCount },
+      claim: {
+        start: SessionSeq(shadowedRange.start),
+        end: SessionSeq(shadowedRange.end),
+        tokens: shadowedTokenCount,
+      },
     }
   }
   if (!isSurfaceEvent(event)) return { deltaTokens: 0, claim: undefined }
diff --git a/packages/llm/token-meter/src/types.ts b/packages/llm/token-meter/src/types.ts
index e6ccc8b071..487e031385 100644
--- a/packages/llm/token-meter/src/types.ts
+++ b/packages/llm/token-meter/src/types.ts
@@ -5,6 +5,7 @@
  */
 
 import type { TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session/types'
 
 export type { ContextBreakdownProjection, ContextPressureProjection, TokenUsageProjection } from './projection.ts'
 
@@ -20,7 +21,7 @@ export type TokenMeasurementBaseline =
 /** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
 export interface TokenMeasurement {
   /** Number of durable events consumed; equal to the next unread event seq. */
-  readonly logRevision: number
+  readonly logRevision: SessionLogOffset
   /** Provider or heuristic anchor used for this measurement. */
   readonly baseline: TokenMeasurementBaseline
   /** Signed repricing of current surface content relative to the baseline anchor. */
@@ -36,7 +37,7 @@ export interface TokenMeasurement {
 /** One token-priced node in the current ordered session surface. */
 export interface TokenSurfaceNode {
   /** Durable sequence number of the surface event. */
-  readonly seq: number
+  readonly seq: SessionSeq
   /**
    * Request-pressure tokens for the exact message projected by this node under
    * the measured route: image occurrences carry the route's declared visual
diff --git a/packages/llm/token-meter/src/usage-projection.ts b/packages/llm/token-meter/src/usage-projection.ts
index 50f336c61c..b98b48c3e1 100644
--- a/packages/llm/token-meter/src/usage-projection.ts
+++ b/packages/llm/token-meter/src/usage-projection.ts
@@ -5,6 +5,7 @@
 import { z } from 'zod'
 import type { TokenUsage } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-llm-retry/types'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import type { ContextPressureProjection, TokenUsageProjection } from './projection.ts'
@@ -99,8 +100,8 @@ const contextPressureStateSchema = z.object({
   surfaceTokens: z.number().int().nonnegative(),
   sampledSurfaceTokens: z.number().int().nonnegative().optional(),
   claim: z.object({
-    start: z.number().int().nonnegative(),
-    end: z.number().int().nonnegative(),
+    start: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
+    end: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
     tokens: z.number().int().nonnegative(),
   }).optional(),
 }).strict()
diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
index 6ab566d085..3f36926f57 100644
--- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
+++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
@@ -5,8 +5,8 @@ import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionSeq } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionSeq as SessionSeqType } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeter from '@deepseek-ai/dsh-token-meter'
 import type { ContextBreakdownProjection } from '@deepseek-ai/dsh-token-meter/client'
@@ -42,7 +42,7 @@ const projected = (ctx: Context, session: Session): ContextBreakdownProjection =
   return value
 }
 
-function appendUser(session: Session, text: string): number {
+function appendUser(session: Session, text: string): SessionSeqType {
   return session.append('user/message', createUserMessage({
     content: [{ type: 'text', text }],
     source: { kind: 'user' },
@@ -54,7 +54,7 @@ function appendUser(session: Session, text: string): number {
  * replaced span from the measurement service's own nodes and log the
  * shadow-price event directly before the replace.
  */
-function appendSummaryMeter(ctx: Context, session: Session, start: number, end: number): void {
+function appendSummaryMeter(ctx: Context, session: Session, start: SessionSeqType, end: SessionSeqType): void {
   const nodes = ctx.tokenMeter.measure(session).nodes
   const startIdx = nodes.findIndex(node => node.seq === start)
   const endIdx = nodes.findIndex(node => node.seq === end)
@@ -184,44 +184,51 @@ describe('contextBreakdown session projection', () => {
 
   it('folds a replacement without a claim at zero and fails on a mismatched claim', () => {
     const definition = contextBreakdownProjectionDefinition
-    const replace = (start: number, end: number): SessionEvent => ({
+    const replace = (start: SessionSeq, end: SessionSeq): SessionEvent => ({
       type: 'user/message',
-      seq: 9,
+      seq: SessionSeq(9),
       time: 0,
       data: createUserMessage({ content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }),
       surfaceOp: { op: 'replace', start, end },
       sourceEventSeqs: [start, end],
     } as unknown as SessionEvent)
-    const append = (seq: number): SessionEvent => ({
+    const append = (seq: SessionSeq): SessionEvent => ({
       type: 'user/message',
       seq,
       time: 0,
       data: createUserMessage({ content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }),
       surfaceOp: 'append',
     } as unknown as SessionEvent)
-    const meter = (start: number, end: number, seq: number): SessionEvent => ({
+    const meter = (start: SessionSeq, end: SessionSeq, seq: SessionSeq): SessionEvent => ({
       type: 'compaction/prune',
       seq,
       time: 0,
-      data: { shadowedRange: { start, end }, shadowedSeqs: [start, end], shadowedTokenCount: 5 },
+      data: {
+        shadowedRange: { start, end },
+        shadowedSeqs: [start, end],
+        shadowedTokenCount: 5,
+      },
     } as unknown as SessionEvent)
     let state = definition.init()
-    state = definition.apply(state, append(1))
-    state = definition.apply(state, append(3))
+    state = definition.apply(state, append(SessionSeq(1)))
+    state = definition.apply(state, append(SessionSeq(3)))
     // No metering event: the replacement contributes zero instead of throwing.
-    expect(definition.wire.view(definition.apply(state, replace(1, 3))).messageTokens)
+    expect(definition.wire.view(definition.apply(state, replace(SessionSeq(1), SessionSeq(3)))).messageTokens)
       .toBe(definition.wire.view(state).messageTokens)
     // An adjacent claim for another range contradicts the replacement.
-    const mismatched = definition.apply(state, meter(1, 1, 8))
-    expect(() => definition.apply(mismatched, replace(1, 3))).toThrow('no adjacent shadow price')
+    const mismatched = definition.apply(state, meter(SessionSeq(1), SessionSeq(1), SessionSeq(8)))
+    expect(() => definition.apply(mismatched, replace(SessionSeq(1), SessionSeq(3))))
+      .toThrow('no adjacent shadow price')
     // A claim expires after one intervening event, so replacement delta is zero.
-    let expired = definition.apply(state, meter(1, 3, 8))
-    expired = definition.apply(expired, { type: 'session/end-seed', seq: 9, time: 0, data: {} })
-    expect(definition.wire.view(definition.apply(expired, replace(1, 3))).messageTokens)
+    let expired = definition.apply(state, meter(SessionSeq(1), SessionSeq(3), SessionSeq(8)))
+    expired = definition.apply(expired, {
+      type: 'session/end-seed', seq: SessionSeq(9), time: 0, data: {},
+    })
+    expect(definition.wire.view(definition.apply(expired, replace(SessionSeq(1), SessionSeq(3)))).messageTokens)
       .toBe(definition.wire.view(state).messageTokens)
     // The armed claim prices exactly the next event's matching replacement.
-    const armed = definition.apply(state, meter(1, 3, 8))
-    expect(definition.wire.view(definition.apply(armed, replace(1, 3))).messageTokens)
+    const armed = definition.apply(state, meter(SessionSeq(1), SessionSeq(3), SessionSeq(8)))
+    expect(definition.wire.view(definition.apply(armed, replace(SessionSeq(1), SessionSeq(3)))).messageTokens)
       .toBe(definition.wire.view(state).messageTokens - 5 + estimateMessage(
         createUserMessage({ content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }),
       ))
diff --git a/packages/llm/token-meter/tests/token-meter.spec.ts b/packages/llm/token-meter/tests/token-meter.spec.ts
index 198a660992..615a12c9dd 100644
--- a/packages/llm/token-meter/tests/token-meter.spec.ts
+++ b/packages/llm/token-meter/tests/token-meter.spec.ts
@@ -2,8 +2,8 @@ import { describe, expect, expectTypeOf, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { createUserMessage, ToolCallId, createMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId, canonicalHeader } from '@deepseek-ai/dsh-session'
-import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq, canonicalHeader } from '@deepseek-ai/dsh-session'
+import type { EpochHeader, SessionEvent, SessionSeq as SessionSeqType } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeter from '@deepseek-ai/dsh-token-meter'
 import type { TokenMeasurement, TokenMeterConfig } from '@deepseek-ai/dsh-token-meter'
@@ -54,7 +54,7 @@ function appendSuccessfulCall(
   session.append('step/start', { turn, step })
   appendHeader(session, value)
 
-  const sources: number[] = []
+  const sources: SessionSeqType[] = []
   if (provenance === 'exact') {
     const chunks = [
       { type: 'block-start' as const, index: 0, blockType: 'text' as const },
@@ -185,8 +185,8 @@ describe('TokenMeter pricing', () => {
     expect(Object.isFrozen(snapshot.nodes[0])).toBe(true)
     expectSurfaceTotal(snapshot)
     expect(() => {
-      ;(snapshot.nodes as Array<{ seq: number; tokens: number; heuristicTokens: number }>)
-        .push({ seq: 99, tokens: 1, heuristicTokens: 1 })
+      ;(snapshot.nodes as Array<{ seq: SessionSeqType; tokens: number; heuristicTokens: number }>)
+        .push({ seq: SessionSeq(99), tokens: 1, heuristicTokens: 1 })
     }).toThrow(TypeError)
     expect(() => {
       ;(snapshot.nodes[0] as { seq: number; tokens: number }).tokens = 1
@@ -539,7 +539,7 @@ describe('malformed replay and listener lifecycle', () => {
   it('rejects invalid assistant source-event references', () => {
     const cases: Array<{
       name: string
-      appendSource(session: Session): number[]
+      appendSource(session: Session): SessionSeqType[]
       pattern: RegExp
     }> = [
       {
@@ -597,7 +597,7 @@ describe('malformed replay and listener lifecycle', () => {
     }).seq
     appendUnchecked(duplicate, {
       type: 'assistant/message',
-      seq: duplicate.seq,
+      seq: SessionSeq(duplicate.seq),
       time: 0,
       data: {
         turn: 1,
@@ -622,7 +622,7 @@ describe('malformed replay and listener lifecycle', () => {
     appendHeader(future, header('deepseek-v4-flash'))
     appendUnchecked(future, {
       type: 'assistant/message',
-      seq: future.seq,
+      seq: SessionSeq(future.seq),
       time: 0,
       data: {
         turn: 1,
@@ -638,7 +638,7 @@ describe('malformed replay and listener lifecycle', () => {
         usage: { inputTokens: 1, outputTokens: 0 },
       },
       surfaceOp: 'append',
-      sourceEventSeqs: [99],
+      sourceEventSeqs: [SessionSeq(99)],
     })
     expect(() => meter().measure(future)).toThrow(/is not earlier/)
   })
@@ -678,13 +678,13 @@ describe('malformed replay and listener lifecycle', () => {
     }), { surfaceOp: 'append' }).seq
     appendUnchecked(session, {
       type: 'user/message',
-      seq: session.seq,
+      seq: SessionSeq(session.seq),
       time: 0,
       data: createUserMessage({
         content: [{ type: 'text', text: 'bad' }],
         source: { kind: 'user' },
       }),
-      surfaceOp: { op: 'replace', start: 99, end: 99 },
+      surfaceOp: { op: 'replace', start: SessionSeq(99), end: SessionSeq(99) },
       sourceEventSeqs: [head],
     })
     expectRepeatedFailure(meter(), session, /invalid current range/)
@@ -703,7 +703,7 @@ describe('malformed replay and listener lifecycle', () => {
     activeMeter = ctx.tokenMeter
     const session = ctx.sessions.create(SessionId('listener-order'), { seed: [{
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
     }] })
diff --git a/packages/llm/token-meter/tests/token-usage-projection.spec.ts b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
index f9ce9015e3..3ffee99021 100644
--- a/packages/llm/token-meter/tests/token-usage-projection.spec.ts
+++ b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
@@ -3,7 +3,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { TokenUsage } from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
-import type { Session } from '@deepseek-ai/dsh-session'
+import type { Session, SessionSeq } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeter from '@deepseek-ai/dsh-token-meter'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
@@ -38,7 +38,7 @@ function usageChunk(
   usage: TokenUsage,
   turn: number,
   step: number,
-): number {
+): SessionSeq {
   return session.append('assistant/chunk', {
     turn,
     step,
@@ -51,7 +51,7 @@ function finalUsage(
   usage: TokenUsage,
   turn: number,
   step: number,
-  sourceSeqs: number[],
+  sourceSeqs: SessionSeq[],
 ): void {
   session.append('assistant/message', {
     turn,
@@ -77,7 +77,7 @@ const projected = (ctx: Context, session: Session): TokenUsageProjection => {
  * replaced span from the measurement service's own nodes and log the
  * shadow-price event directly before the replace.
  */
-function appendSummaryMeter(ctx: Context, session: Session, start: number, end: number): void {
+function appendSummaryMeter(ctx: Context, session: Session, start: SessionSeq, end: SessionSeq): void {
   const nodes = ctx.tokenMeter.measure(session).nodes
   const startIdx = nodes.findIndex(node => node.seq === start)
   const endIdx = nodes.findIndex(node => node.seq === end)
@@ -319,7 +319,7 @@ function recordContext(session: Session, model: string, contextWindow?: number):
 }
 
 /** Append one model-visible user turn and return its surface seq. */
-function appendUser(session: Session, text: string): number {
+function appendUser(session: Session, text: string): SessionSeq {
   return session.append('user/message', createUserMessage({
     content: [{ type: 'text', text }],
     source: { kind: 'user' },
@@ -333,7 +333,7 @@ function appendAssistant(
   usage: TokenUsage,
   turn: number,
   step: number,
-): number {
+): SessionSeq {
   return session.append('assistant/message', {
     turn,
     step,
diff --git a/packages/plan/plan-mode/tests/invariant.spec.ts b/packages/plan/plan-mode/tests/invariant.spec.ts
index 9f7ed2233f..d44cadc67a 100644
--- a/packages/plan/plan-mode/tests/invariant.spec.ts
+++ b/packages/plan/plan-mode/tests/invariant.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session'
 import * as PlanModeInvariant from '@deepseek-ai/dsh-plan-mode/invariant'
 import InvariantRegistry from '@deepseek-ai/dsh-invariants'
 
@@ -13,12 +13,12 @@ async function setup(): Promise<Context> {
 }
 
 function event(active: unknown): SessionEvent {
-  return { type: 'plan/mode', seq: 0, time: 0, data: { active } } as SessionEvent
+  return { type: 'plan/mode', seq: SessionSeq(0), time: 0, data: { active } } as SessionEvent
 }
 
 function emitTurnStart(ctx: Context, session: Session): void {
   ctx.emit('session/event', session, {
-    type: 'turn/start', seq: 0, time: 0,
+    type: 'turn/start', seq: SessionSeq(0), time: 0,
     data: { turn: 1 },
   })
 }
@@ -31,7 +31,7 @@ describe('plan-mode stream invariants', () => {
     expect(() => { ctx.emit('session/event', session, event(true)) }).not.toThrow()
     expect(() => { ctx.emit('session/event', session, event(false)) }).not.toThrow()
     ctx.emit('session/event', session, {
-      type: 'turn/end', seq: 3, time: 3, data: { turn: 1, reason: { kind: 'completed' } },
+      type: 'turn/end', seq: SessionSeq(3), time: 3, data: { turn: 1, reason: { kind: 'completed' } },
     })
   })
 
@@ -55,7 +55,7 @@ describe('plan-mode stream invariants', () => {
     expect(() => {
       ctx.emit('tools/change')
       ctx.emit('session/event', session, {
-        type: 'turn/start', seq: 0, time: 0, data: { turn: 1 },
+        type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 },
       })
     }).not.toThrow()
   })
diff --git a/packages/preset/agent-presets/tests/session.spec.ts b/packages/preset/agent-presets/tests/session.spec.ts
index 6b6da3d540..255fe0cfa8 100644
--- a/packages/preset/agent-presets/tests/session.spec.ts
+++ b/packages/preset/agent-presets/tests/session.spec.ts
@@ -1,7 +1,7 @@
 /** The Session projection that records which preset a Session runs. */
 
 import { describe, expect, it } from 'vitest'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import { agentPresetProjectionDefinition } from '../src/session.ts'
 
@@ -11,13 +11,14 @@ function header(agentPreset?: string): SessionHeader {
     version: 0,
     id: SessionId('s'),
     createdAt: 1,
+    isSeeded: false,
     delegationDepth: 0,
     ...agentPreset === undefined ? {} : { agentPreset },
   }
 }
 
 /** One logged selection, as `agentPreset.select` appends it. */
-function selected(agentPreset: string, seq: number): SessionEvent {
+function selected(agentPreset: string, seq: SessionSeq): SessionEvent {
   return { type: 'agent-preset/selected', seq, time: seq, data: { agentPreset } }
 }
 
@@ -32,11 +33,11 @@ describe('agent preset selection projection', () => {
     let state = definition.init(header('standard'))
     expect(state).toBe('standard')
 
-    state = definition.apply(state, selected('minimal', 0))
+    state = definition.apply(state, selected('minimal', SessionSeq(0)))
     state = definition.apply(state, {
-      type: 'turn/end', seq: 1, time: 1, data: { turn: 1, reason: { kind: 'completed' } },
+      type: 'turn/end', seq: SessionSeq(1), time: 1, data: { turn: 1, reason: { kind: 'completed' } },
     })
-    state = definition.apply(state, selected('cordis', 2))
+    state = definition.apply(state, selected('cordis', SessionSeq(2)))
 
     expect(definition.wire.view(state)).toBe('cordis')
     expect(definition.stateSchema.parse(state)).toBe('cordis')
diff --git a/packages/sandbox/sandbox-policy/tests/policy.spec.ts b/packages/sandbox/sandbox-policy/tests/policy.spec.ts
index a680373163..7ba166354b 100644
--- a/packages/sandbox/sandbox-policy/tests/policy.spec.ts
+++ b/packages/sandbox/sandbox-policy/tests/policy.spec.ts
@@ -28,6 +28,7 @@ function session(id: string, cwd?: string): Session {
     version: 0,
     id: sessionId,
     createdAt: 0,
+    isSeeded: false,
     ...cwd === undefined ? {} : { cwd },
   })
 }
diff --git a/packages/schedule/AGENTS.md b/packages/schedule/AGENTS.md
index 23561f9705..aea5557cd6 100644
--- a/packages/schedule/AGENTS.md
+++ b/packages/schedule/AGENTS.md
@@ -3,7 +3,7 @@
 These rules supplement the repository and package instructions for `packages/schedule/*`.
 
 - The owning Session's versioned `schedule/change` stream is the only durable Schedule state. Folds validate every durable JSON boundary and derive active records; timers, idle waiters, and tool values remain disposable projections.
-- A normal Session folds its complete log. A fork derives active Schedule state only from events at or after `SessionHeader.seedLength`; it never inherits an active parent reminder.
+- A normal Session folds its complete log. A fork derives active Schedule state only from events at or after the Session's exact `inheritedEventCount`; it never inherits an active parent reminder.
 - Every Schedule management operation that reads or decides from the fold first awaits `ctx.sessions.flush(session)`. Create and an actual delete await a second barrier after append; a failed barrier returns the stable uncertainty result instead of inferring durability from the live log.
 - Runtime owners attach only to future live root Agents while the plugin is loaded. They do not scan persisted Sessions, adopt already-published roots, wake cold Sessions, register global tools, or delete durable records during teardown.
 - Due handling rechecks the wall clock and exact live owner, claims the idle maintenance phase through the public Agent seam, constructs the complete escaped framing before `followup()`, appends dispatch only after synchronous enqueue returns, releases maintenance, and then awaits durability. A synchronous framing/enqueue failure appends no dispatch; a later model failure does not roll one back.
diff --git a/packages/schedule/schedule/README.i18n.yaml b/packages/schedule/schedule/README.i18n.yaml
index 406b4dceec..2722f1e2a3 100644
--- a/packages/schedule/schedule/README.i18n.yaml
+++ b/packages/schedule/schedule/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/schedule/schedule/README.md
-README.md: 69ee726bb25aaa8c2da0c53471089d2a255998c9
-README.zh.md: 60d57055ca4ab5e9fa18ae1996d31ccd3e704495
+README.md: 2b4c000e8bcbbe5fd8b9379db602c358dc5c192e
+README.zh.md: 8ab9e847aacda95620820a8a67a9760285a01b1c
diff --git a/packages/schedule/schedule/README.md b/packages/schedule/schedule/README.md
index 69ee726bb2..2b4c000e8b 100644
--- a/packages/schedule/schedule/README.md
+++ b/packages/schedule/schedule/README.md
@@ -98,11 +98,11 @@ The package rests on one separation and three commitments:
 
 ### Durable state and replay
 
-A normal Session folds its complete event stream. A fork folds only `session.snapshotEvents(session.header.seedLength ?? 0)`, so a child never inherits its parent's reminders. The Schedule projection derives that boundary from the immutable `SessionHeader` passed to `init(header)` and applies the same transition function to the same owned suffix. Every create record carries a stable Session-local `ScheduleId`, the trimmed prompt, and a four-digit-year RFC 3339 UTC `scheduledAt`; an `after` record also stores `afterSeconds`, an `at` record stores no copy of its submitted offset or local fields, and an `every` record stores `everySeconds` with `scheduledAt` as the earliest creation-anchor-aligned occurrence not yet dispatched. Delete and one-shot dispatch carry only the id; an `every` dispatch adds `acceptedAt`, and replay advances directly to the first anchor-aligned target after that decision time.
+A normal Session folds its complete event stream. A fork folds only `session.ownEvents()`, so a child never inherits its parent's reminders. The Schedule projection receives the Session's exact `inheritedEventCount` from the projection registry and applies the same transition function after that cut. Every create record carries a stable Session-local `ScheduleId`, the trimmed prompt, and a four-digit-year RFC 3339 UTC `scheduledAt`; an `after` record also stores `afterSeconds`, an `at` record stores no copy of its submitted offset or local fields, and an `every` record stores `everySeconds` with `scheduledAt` as the earliest creation-anchor-aligned occurrence not yet dispatched. Delete and one-shot dispatch carry only the id; an `every` dispatch adds `acceptedAt`, and replay advances directly to the first anchor-aligned target after that decision time.
 
 ### Client projection
 
-The optional `schedule` projection checkpoints `{ seedLength, active, seenIds }` as strict plain JSON and publishes only the complete `active` array. Its schema reuses the durable Schedule decoder, rejects duplicate or inconsistent ids, and propagates corrupt durable events through the existing Session read failure instead of publishing a partial catalog. Live lazy build, event-driven build, cold restore, history reads, and detached Subagent reads all use the immutable Session header and the same owned-suffix transition.
+The optional `schedule` projection checkpoints `{ inheritedEventCount, active, seenIds }` as strict plain JSON and publishes only the complete `active` array. Its schema reuses the durable Schedule decoder, rejects duplicate or inconsistent ids, and propagates corrupt durable events through the existing Session read failure instead of publishing a partial catalog. Live lazy build, event-driven build, cold restore, history reads, and detached Subagent reads all use the exact Session cut and the same owned-suffix transition.
 
 The projection carries durable records only. It does not persist or transmit scheduled-versus-overdue status, localized text, relative time, browser-local time, sorting state, popover state, runtime liveness, or delivery receipts. [`dsh-client-ui-schedule`](../../client/ui-schedule/README.md) derives catalog presentation from the complete array and the viewing browser's clock. [`dsh-client-ui-workspace`](../../client/ui-workspace/README.md) derives only whether the list value is a non-empty array, so ordinary and search rows may briefly omit or retain the alarm when the durable projection cache is missing or stale.
 
diff --git a/packages/schedule/schedule/README.zh.md b/packages/schedule/schedule/README.zh.md
index 60d57055ca..8ab9e847aa 100644
--- a/packages/schedule/schedule/README.zh.md
+++ b/packages/schedule/schedule/README.zh.md
@@ -98,11 +98,11 @@ Session projection 是可选能力。`ctx.sessionProjections` 存在时，插件
 
 ### 持久状态与回放
 
-普通会话折叠完整事件流。fork 只折叠 `session.snapshotEvents(session.header.seedLength ?? 0)`，因此子会话永远不会继承父会话的提醒。Schedule projection 从传给 `init(header)` 的不可变 `SessionHeader` 派生该边界，并对同一自有后缀应用同一个 transition 函数。每条 create 记录都携带稳定的会话本地 `ScheduleId`、已 trim 的提示词与四位年份 RFC 3339 UTC `scheduledAt`；`after` 记录还存储 `afterSeconds`，`at` 记录不保留所提交的偏移量或本地字段，`every` 记录存储 `everySeconds`，并把 `scheduledAt` 视为尚未 dispatch 的最早创建锚点对齐发生时点。delete 与一次性 dispatch 只携带 id；`every` dispatch 会附加 `acceptedAt`，回放直接推进到该决策时点之后的第一个锚点对齐目标。
+普通会话折叠完整事件流。fork 只折叠 `session.ownEvents()`，因此子会话永远不会继承父会话的提醒。Schedule projection 从投影注册表接收 Session 的精确 `inheritedEventCount`，并在该切点之后应用同一个 transition 函数。每条 create 记录都携带稳定的会话本地 `ScheduleId`、已 trim 的提示词与四位年份 RFC 3339 UTC `scheduledAt`；`after` 记录还存储 `afterSeconds`，`at` 记录不保留所提交的偏移量或本地字段，`every` 记录存储 `everySeconds`，并把 `scheduledAt` 视为尚未 dispatch 的最早创建锚点对齐发生时点。delete 与一次性 dispatch 只携带 id；`every` dispatch 会附加 `acceptedAt`，回放直接推进到该决策时点之后的第一个锚点对齐目标。
 
 ### 客户端 projection
 
-可选的 `schedule` projection 将 `{ seedLength, active, seenIds }` 作为严格的纯 JSON 检查点，并且只发布完整的 `active` 数组。其 schema 复用持久 Schedule decoder，拒绝重复或不一致的 id，并让损坏的持久事件通过既有 Session 读取失败传播，而不是发布部分目录。live 惰性构建、事件驱动构建、cold restore、history 读取与 detached Subagent 读取都使用不可变 Session header 与同一套自有后缀 transition。
+可选的 `schedule` projection 将 `{ inheritedEventCount, active, seenIds }` 作为严格的纯 JSON 检查点，并且只发布完整的 `active` 数组。其 schema 复用持久 Schedule decoder，拒绝重复或不一致的 id，并让损坏的持久事件通过既有 Session 读取失败传播，而不是发布部分目录。live 惰性构建、事件驱动构建、cold restore、history 读取与 detached Subagent 读取都使用精确 Session 切点与同一套自有后缀 transition。
 
 projection 只携带持久记录。它不持久化或传输 scheduled／overdue 状态、本地化文本、相对时间、浏览器本地时间、排序状态、popover 状态、runtime 存活或交付回执。[`dsh-client-ui-schedule`](../../client/ui-schedule/README.zh.md) 从完整数组与查看方浏览器时钟派生目录呈现。[`dsh-client-ui-workspace`](../../client/ui-workspace/README.zh.md) 只派生列表值是否为非空数组，因此持久 projection cache 缺失或陈旧时，普通行与搜索结果的闹钟可能短暂漏显或残留。
 
diff --git a/packages/schedule/schedule/src/domain.ts b/packages/schedule/schedule/src/domain.ts
index e4ffd8ef7f..a23340d446 100644
--- a/packages/schedule/schedule/src/domain.ts
+++ b/packages/schedule/schedule/src/domain.ts
@@ -3,7 +3,8 @@
  * @module @deepseek-ai/dsh-schedule
  */
 
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
 import type {
   AfterScheduleRecord,
   AtInput,
@@ -622,22 +623,24 @@ export function applyScheduleChanges(
 /**
  * Fold the package-owned stream after the durable fork seed boundary.
  * @param events - Complete ordered session log or candidate-extended log.
- * @param seedLength - Inherited prefix length excluded from child ownership.
+ * @param inheritedEventCount - Inherited prefix length excluded from child ownership.
  * @returns Active records and all previously used ids.
  */
 export function foldScheduleEvents(
   events: readonly SessionEvent[],
-  seedLength = 0,
+  inheritedEventCount: SessionLogOffsetType = SessionLogOffset(0),
 ): FoldedSchedules {
-  if (!Number.isSafeInteger(seedLength) || seedLength < 0 || seedLength > events.length) {
-    throw new ScheduleLogError('schedule seedLength must be within the supplied event log')
+  if (!Number.isSafeInteger(inheritedEventCount)
+    || inheritedEventCount < 0
+    || inheritedEventCount > events.length) {
+    throw new ScheduleLogError('schedule inheritedEventCount must be within the supplied event log')
   }
   const initial: FoldedSchedules = Object.freeze({
     active: Object.freeze([]),
     seenIds: Object.freeze([]),
   })
   const changes = function* (): Generator<ScheduleChange> {
-    for (const event of events.slice(seedLength)) {
+    for (const event of events.slice(inheritedEventCount)) {
       if (event.type === 'schedule/change') yield decodeScheduleChange(event.data)
     }
   }
diff --git a/packages/schedule/schedule/src/invariant.ts b/packages/schedule/schedule/src/invariant.ts
index 5af5245ade..248e7df710 100644
--- a/packages/schedule/schedule/src/invariant.ts
+++ b/packages/schedule/schedule/src/invariant.ts
@@ -16,9 +16,9 @@ export const name = 'tool-schedule-invariant'
 export const inject = ['invariants']
 
 /** Validate a complete exact-session stream under its fork suffix policy. */
-function validate(events: readonly SessionEvent[], seedLength: number, fail: InvariantFailure): void {
+function validate(events: readonly SessionEvent[], fail: InvariantFailure): void {
   try {
-    foldScheduleEvents(events, seedLength)
+    foldScheduleEvents(events)
   } catch (error: unknown) {
     /* v8 ignore next -- foldScheduleEvents normalizes every rejected stream to ScheduleLogError. */
     if (!(error instanceof ScheduleLogError)) throw error
@@ -30,16 +30,16 @@ function validate(events: readonly SessionEvent[], seedLength: number, fail: Inv
 /** Install replay and pre-append validation for the owned event stream. */
 const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
   for (const session of ctx.sessions.list()) {
-    validate(session.snapshotEvents(), session.header.seedLength ?? 0, fail)
+    validate(session.ownEvents(), fail)
   }
   ctx.on('session/created', (session) => {
-    validate(session.snapshotEvents(), session.header.seedLength ?? 0, fail)
+    validate(session.ownEvents(), fail)
   }, { global: true })
   ctx.on('internal/dispatch', (_mode, eventName, args) => {
     if (eventName !== 'session/event') return
     const [session, event] = args as [Session, SessionEvent]
     if (event.type !== 'schedule/change') return
-    validate([...session.snapshotEvents(), event], session.header.seedLength ?? 0, fail)
+    validate([...session.ownEvents(), event], fail)
   }, { global: true })
 }, { inject: ['sessions'] })
 /* jscpd:ignore-end */
diff --git a/packages/schedule/schedule/src/projection.ts b/packages/schedule/schedule/src/projection.ts
index 5703e50609..67116dda21 100644
--- a/packages/schedule/schedule/src/projection.ts
+++ b/packages/schedule/schedule/src/projection.ts
@@ -4,14 +4,16 @@
  */
 
 import { z } from 'zod'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import { applyScheduleChanges, decodeScheduleChange } from './domain.ts'
 import type { FoldedSchedules } from './domain.ts'
 import type { ScheduleChange, ScheduleId, ScheduleRecord } from './types.ts'
 
-/** Persisted projection state: the immutable fork boundary plus the complete Schedule fold. */
+/** Persisted projection state: the immutable inherited cut plus the complete Schedule fold. */
 export interface ScheduleProjectionState extends FoldedSchedules {
-  readonly seedLength: number
+  readonly inheritedEventCount: SessionLogOffsetType
 }
 
 const scheduleId = z.unknown().transform((value, context): ScheduleId => {
@@ -43,7 +45,7 @@ const scheduleRecord = z.unknown().transform((value, context): ScheduleRecord =>
 const scheduleRecords = z.array(scheduleRecord) as unknown as z.ZodType<readonly ScheduleRecord[]>
 
 const scheduleProjectionStateSchema = z.object({
-  seedLength: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  inheritedEventCount: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionLogOffset),
   active: scheduleRecords,
   seenIds: z.array(scheduleId),
 }).strict().superRefine((state, context) => {
@@ -67,11 +69,11 @@ const scheduleProjectionStateSchema = z.object({
 export const scheduleProjectionDefinition = {
   key: 'schedule',
   stateSchema: scheduleProjectionStateSchema,
-  init: header => ({ seedLength: header.seedLength ?? 0, active: [], seenIds: [] }),
+  init: (_header, inheritedEventCount) => ({ inheritedEventCount, active: [], seenIds: [] }),
   apply: (state, event) => {
-    if (event.seq < state.seedLength || event.type !== 'schedule/change') return state
+    if (event.seq < state.inheritedEventCount || event.type !== 'schedule/change') return state
     return {
-      seedLength: state.seedLength,
+      inheritedEventCount: state.inheritedEventCount,
       ...applyScheduleChanges(state, [decodeScheduleChange(event.data)]),
     }
   },
@@ -79,7 +81,7 @@ export const scheduleProjectionDefinition = {
     viewSchema: scheduleRecords,
     view: state => state.active,
   },
-  stateVersion: 1,
+  stateVersion: 2,
 } satisfies ProjectionDefinition<'schedule', ScheduleProjectionState>
 
 declare module '@deepseek-ai/dsh-session-projection/types' {
diff --git a/packages/schedule/schedule/src/runtime.ts b/packages/schedule/schedule/src/runtime.ts
index b7f45848c5..5b141f5728 100644
--- a/packages/schedule/schedule/src/runtime.ts
+++ b/packages/schedule/schedule/src/runtime.ts
@@ -205,10 +205,7 @@ export class ScheduleRuntime {
   /** Fold the current exact runtime suffix and contain a corrupt durable stream. */
   private readFolded(): FoldedSchedules | undefined {
     try {
-      return foldScheduleEvents(
-        this.agent.session.snapshotEvents(),
-        this.agent.session.header.seedLength ?? 0,
-      )
+      return foldScheduleEvents(this.agent.session.ownEvents())
     } catch (error: unknown) {
       this.faulted = true
       const detail = error instanceof ScheduleLogError ? error.message : renderThrown(error)
diff --git a/packages/schedule/schedule/src/tools.ts b/packages/schedule/schedule/src/tools.ts
index 616d8650fb..c4ac651634 100644
--- a/packages/schedule/schedule/src/tools.ts
+++ b/packages/schedule/schedule/src/tools.ts
@@ -221,7 +221,7 @@ function inputError(error: ScheduleInputError): ScheduleToolError {
 /** Fold only after a successful preflight, mapping corruption to a stable value. */
 function foldForTool(agent: Agent): ReturnType<typeof foldScheduleEvents> | ScheduleToolError {
   try {
-    return foldScheduleEvents(agent.session.snapshotEvents(), agent.session.header.seedLength ?? 0)
+    return foldScheduleEvents(agent.session.ownEvents())
   } catch (error: unknown) {
     return error instanceof ScheduleLogError ? corruptLogError() : internalError()
   }
diff --git a/packages/schedule/schedule/tests/domain.spec.ts b/packages/schedule/schedule/tests/domain.spec.ts
index f07b0823f2..650c38af37 100644
--- a/packages/schedule/schedule/tests/domain.spec.ts
+++ b/packages/schedule/schedule/tests/domain.spec.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import {
   ScheduleId,
@@ -137,13 +138,13 @@ describe('version-1 Schedule decoding and folding', () => {
   it('folds only the fork-owned suffix and validates its boundary', () => {
     const parentCreate = scheduleEvent(createData('parent'), 0)
     const childCreate = scheduleEvent(createData('child'), 1)
-    expect(foldScheduleEvents([parentCreate, childCreate], 1)).toEqual({
+    expect(foldScheduleEvents([parentCreate, childCreate], SessionLogOffset(1))).toEqual({
       active: [expect.objectContaining({ id: 'child' })],
       seenIds: ['child'],
     })
-    expect(() => foldScheduleEvents([], -1)).toThrow(/seedLength/)
-    expect(() => foldScheduleEvents([], 1)).toThrow(/seedLength/)
-    expect(() => foldScheduleEvents([], 0.5)).toThrow(/seedLength/)
+    expect(() => foldScheduleEvents([], -1 as never)).toThrow(/inheritedEventCount/)
+    expect(() => foldScheduleEvents([], SessionLogOffset(1))).toThrow(/inheritedEventCount/)
+    expect(() => foldScheduleEvents([], 0.5 as never)).toThrow(/inheritedEventCount/)
   })
 
   it('allocates a readable id without reusing ended or colliding ids', () => {
diff --git a/packages/schedule/schedule/tests/invariant.spec.ts b/packages/schedule/schedule/tests/invariant.spec.ts
index 0896a8b6f9..f595bfa081 100644
--- a/packages/schedule/schedule/tests/invariant.spec.ts
+++ b/packages/schedule/schedule/tests/invariant.spec.ts
@@ -1,13 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import InvariantRegistry, { InvariantError } from '@deepseek-ai/dsh-invariants'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import * as scheduleInvariant from '../src/invariant.ts'
 import { ScheduleId } from '../src/domain.ts'
 import type { ScheduleChange } from '../src/types.ts'
 
-function event(data: unknown, seq: number): SessionEvent {
+function event(data: unknown, seq: SessionSeq): SessionEvent {
   return { type: 'schedule/change', seq, time: 1, data } as SessionEvent
 }
 
@@ -91,7 +91,7 @@ describe('Schedule package invariant', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(InvariantRegistry)
     ctx.sessions.create(SessionId('schedule-invalid-seed'), {
-      seed: [event({ version: 9, operation: 'delete', id: 'schedule-1' }, 0)],
+      seed: [event({ version: 9, operation: 'delete', id: 'schedule-1' }, SessionSeq(0))],
     })
     await expect(ctx.plugin(scheduleInvariant).then(() => undefined)).rejects.toThrow(InvariantError)
     await ctx.fiber.dispose()
@@ -101,7 +101,7 @@ describe('Schedule package invariant', () => {
     const { ctx } = await harness()
     const id = SessionId('schedule-invalid-future-seed')
     expect(() => ctx.sessions.create(id, {
-      seed: [event({ version: 9, operation: 'delete', id: 'schedule-1' }, 0)],
+      seed: [event({ version: 9, operation: 'delete', id: 'schedule-1' }, SessionSeq(0))],
     })).toThrow(InvariantError)
     expect(ctx.sessions.get(id)).toBeUndefined()
     await ctx.fiber.dispose()
@@ -112,8 +112,9 @@ describe('Schedule package invariant', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(InvariantRegistry)
     const child = ctx.sessions.create(SessionId('schedule-fork'), {
-      seed: [event({ version: 9, operation: 'delete', id: 'parent' }, 0)],
-      meta: { parentSession: SessionId('parent'), seedLength: 1 },
+      seed: [event({ version: 9, operation: 'delete', id: 'parent' }, SessionSeq(0))],
+      inheritedEventCount: SessionLogOffset(1),
+      meta: { parentSession: SessionId('parent'), isSeeded: true },
     })
     const fiber = await ctx.plugin(scheduleInvariant)
     child.append('schedule/change', create('child'))
diff --git a/packages/schedule/schedule/tests/jsonl-restart.spec.ts b/packages/schedule/schedule/tests/jsonl-restart.spec.ts
index 879b16d0ad..ea67d764c1 100644
--- a/packages/schedule/schedule/tests/jsonl-restart.spec.ts
+++ b/packages/schedule/schedule/tests/jsonl-restart.spec.ts
@@ -108,7 +108,7 @@ describe('Schedule production JSONL restart', () => {
     await handle.agent.whenIdle()
     await expect(restarted.sessions.flush(handle.agent.session)).resolves.toBe(true)
     const dispatchedStored = await restarted.sessionPersistence.inspect(sessionId)
-    expect(foldScheduleEvents(dispatchedStored.events, dispatchedStored.meta.seedLength ?? 0).active)
+    expect(foldScheduleEvents(dispatchedStored.events, dispatchedStored.inheritedEventCount).active)
       .toEqual([])
     const dispatches = dispatchedStored.events.filter(event =>
       event.type === 'schedule/change' && event.data.operation === 'dispatch')
diff --git a/packages/schedule/schedule/tests/projection.spec.ts b/packages/schedule/schedule/tests/projection.spec.ts
index 73e0965f3c..a6221e323b 100644
--- a/packages/schedule/schedule/tests/projection.spec.ts
+++ b/packages/schedule/schedule/tests/projection.spec.ts
@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import { apply as applySchedule } from '../src/index.ts'
@@ -13,6 +13,7 @@ const RESTORE_HEADER: SessionHeader = {
   version: 0,
   id: SessionId('schedule-projection'),
   createdAt: 0,
+  isSeeded: false,
 }
 
 afterEach(async () => {
@@ -48,32 +49,32 @@ function everyRecord(id: string): ScheduleRecord {
   }
 }
 
-function change(data: unknown, seq: number): SessionEvent {
+function change(data: unknown, seq: SessionSeq): SessionEvent {
   return { type: 'schedule/change', seq, time: seq, data } as SessionEvent
 }
 
-function created(record: ScheduleRecord, seq: number): SessionEvent {
+function created(record: ScheduleRecord, seq: SessionSeq): SessionEvent {
   return change({ version: 1, operation: 'create', schedule: record }, seq)
 }
 
 describe('Schedule Session projection', () => {
   it('matches an empty replay, preserves creation order, and applies every terminal transition', () => {
-    let projected: ScheduleProjectionState = scheduleProjectionDefinition.init(RESTORE_HEADER)
-    expect(projected).toEqual({ seedLength: 0, active: [], seenIds: [] })
+    let projected: ScheduleProjectionState = scheduleProjectionDefinition.init(RESTORE_HEADER, SessionLogOffset(0))
+    expect(projected).toEqual({ inheritedEventCount: 0, active: [], seenIds: [] })
     expect(scheduleProjectionDefinition.wire.view(projected)).toEqual(foldScheduleEvents([]).active)
 
     const events: SessionEvent[] = [
-      created(afterRecord('after'), 0),
-      created(atRecord('at'), 1),
-      created(everyRecord('every'), 2),
-      change({ version: 1, operation: 'delete', id: 'at' }, 3),
-      change({ version: 1, operation: 'dispatch', id: 'after' }, 4),
+      created(afterRecord('after'), SessionSeq(0)),
+      created(atRecord('at'), SessionSeq(1)),
+      created(everyRecord('every'), SessionSeq(2)),
+      change({ version: 1, operation: 'delete', id: 'at' }, SessionSeq(3)),
+      change({ version: 1, operation: 'dispatch', id: 'after' }, SessionSeq(4)),
       change({
         version: 1,
         operation: 'dispatch',
         id: 'every',
         acceptedAt: '2026-08-25T14:02:00.000Z',
-      }, 5),
+      }, SessionSeq(5)),
     ]
     for (const event of events.slice(0, 3)) {
       projected = scheduleProjectionDefinition.apply(projected, event)
@@ -83,33 +84,36 @@ describe('Schedule Session projection', () => {
       projected = scheduleProjectionDefinition.apply(projected, event)
     }
 
-    expect(projected).toEqual({ seedLength: 0, ...foldScheduleEvents(events) })
+    expect(projected).toEqual({ inheritedEventCount: 0, ...foldScheduleEvents(events) })
     expect(projected.active).toEqual([{ ...everyRecord('every'), scheduledAt: '2026-08-25T14:05:00.000Z' }])
   })
 
   it('shares strict transitions with full replay and excludes the inherited fork prefix', () => {
     const events: SessionEvent[] = [
-      created(afterRecord('parent'), 0),
-      created(atRecord('child-at'), 1),
-      created(everyRecord('child-every'), 2),
+      created(afterRecord('parent'), SessionSeq(0)),
+      created(atRecord('child-at'), SessionSeq(1)),
+      created(everyRecord('child-every'), SessionSeq(2)),
       change({
         version: 1,
         operation: 'dispatch',
         id: 'child-every',
         acceptedAt: '2026-08-25T14:02:00.000Z',
-      }, 3),
+      }, SessionSeq(3)),
     ]
-    let projected: ScheduleProjectionState = scheduleProjectionDefinition.init({
-      ...RESTORE_HEADER,
-      seedLength: 1,
-    })
+    let projected: ScheduleProjectionState = scheduleProjectionDefinition.init(
+      { ...RESTORE_HEADER, isSeeded: true },
+      SessionLogOffset(1),
+    )
     for (const event of events) projected = scheduleProjectionDefinition.apply(projected, event)
     const beforeUnrelated = projected
-    const unrelated = { type: 'turn/start', seq: 4, time: 4, data: { turn: 1 } } as SessionEvent
+    const unrelated = { type: 'turn/start', seq: SessionSeq(4), time: 4, data: { turn: 1 } } as SessionEvent
     projected = scheduleProjectionDefinition.apply(projected, unrelated)
 
     expect(projected).toBe(beforeUnrelated)
-    expect(projected).toEqual({ seedLength: 1, ...foldScheduleEvents([...events, unrelated], 1) })
+    expect(projected).toEqual({
+      inheritedEventCount: 1,
+      ...foldScheduleEvents([...events, unrelated], SessionLogOffset(1)),
+    })
     expect(scheduleProjectionDefinition.wire.view(projected)).toEqual(projected.active)
     expect(projected.active.map(record => record.id)).toEqual(['child-at', 'child-every'])
   })
@@ -120,26 +124,30 @@ describe('Schedule Session projection', () => {
     await ctx.plugin(SessionProjectionRegistry)
     ctx.sessionProjections.register(scheduleProjectionDefinition)
 
-    const first = created(afterRecord('one'), 0)
-    const second = created(atRecord('two'), 1)
-    const initial = ctx.sessionProjections.restore({}, [first, second], 0, RESTORE_HEADER)
+    const first = created(afterRecord('one'), SessionSeq(0))
+    const second = created(atRecord('two'), SessionSeq(1))
+    const initial = ctx.sessionProjections.restore(
+      {}, [first, second], SessionLogOffset(0), RESTORE_HEADER, SessionLogOffset(0),
+    )
     expect(initial.snapshot.values.schedule?.map(record => record.id)).toEqual(['one', 'two'])
 
-    const removed = change({ version: 1, operation: 'delete', id: 'one' }, 2)
+    const removed = change({ version: 1, operation: 'delete', id: 'one' }, SessionSeq(2))
     const resumed = ctx.sessionProjections.restore(
       initial.checkpoint,
       [second, removed],
-      1,
+      SessionLogOffset(1),
       RESTORE_HEADER,
+      SessionLogOffset(0),
     )
     expect(resumed.snapshot.values.schedule?.map(record => record.id)).toEqual(['two'])
-    expect(resumed.checkpoint.schedule).toMatchObject({ ver: 1, seq: 2 })
+    expect(resumed.checkpoint.schedule).toMatchObject({ ver: 2, seq: 2 })
 
     expect(() => ctx.sessionProjections.restore(
       {},
-      [change({ version: 1, operation: 'delete', id: 'missing' }, 0)],
-      0,
+      [change({ version: 1, operation: 'delete', id: 'missing' }, SessionSeq(0))],
+      SessionLogOffset(0),
       RESTORE_HEADER,
+      SessionLogOffset(0),
     )).toThrow(ScheduleLogError)
   })
 
@@ -148,25 +156,25 @@ describe('Schedule Session projection', () => {
     contexts.push(ctx)
     await ctx.plugin(SessionProjectionRegistry)
     ctx.sessionProjections.register(scheduleProjectionDefinition)
-    const row = (val: unknown) => ({ schedule: { ver: 1, seq: 0, val } })
+    const row = (val: unknown) => ({ schedule: { ver: 2, seq: SessionSeq(0), val } })
 
     expect(ctx.sessionProjections.viewCheckpoint(row({
-      seedLength: 0,
+      inheritedEventCount: 0,
       active: [{ ...afterRecord('bad-time'), scheduledAt: 'not-an-instant' }],
       seenIds: ['bad-time'],
     }))).toEqual({})
     expect(ctx.sessionProjections.viewCheckpoint(row({
-      seedLength: 0,
+      inheritedEventCount: 0,
       active: [afterRecord('missing')],
       seenIds: [],
     }))).toEqual({})
     expect(ctx.sessionProjections.viewCheckpoint(row({
-      seedLength: 0,
+      inheritedEventCount: 0,
       active: [afterRecord('duplicate'), afterRecord('duplicate')],
       seenIds: ['duplicate', 'duplicate'],
     }))).toEqual({})
     expect(ctx.sessionProjections.viewCheckpoint(row({
-      seedLength: 0,
+      inheritedEventCount: 0,
       active: [],
       seenIds: [' bad-id'],
     }))).toEqual({})
diff --git a/packages/session-query/session-log-export/tests/archive.host.spec.ts b/packages/session-query/session-log-export/tests/archive.host.spec.ts
index c41846039a..66ebe197c0 100644
--- a/packages/session-query/session-log-export/tests/archive.host.spec.ts
+++ b/packages/session-query/session-log-export/tests/archive.host.spec.ts
@@ -10,6 +10,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { unzipSync, strFromU8 } from 'fflate'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionLineageNode } from '@deepseek-ai/dsh-session-query'
 import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
@@ -25,6 +26,7 @@ function header(id: string, parentSession?: SessionId): SessionHeader {
     id: sid(id),
     createdAt: 1000,
     cwd: '/proj',
+    isSeeded: false,
     ...parentSession === undefined ? {} : { parentSession },
     delegationDepth: parentSession === undefined ? 0 : 1,
   }
@@ -33,6 +35,7 @@ function header(id: string, parentSession?: SessionId): SessionHeader {
 function artifact(id: string, parentSession?: SessionId, content?: string): SessionRawArtifact {
   return {
     meta: header(id, parentSession),
+    inheritedEventCount: SessionLogOffset(0),
     filename: 'session.jsonl',
     content: content ?? `{"type":"session","version":0,"id":"${id}","createdAt":1000}\n{"type":"turn/start","seq":0,"time":2000,"data":{"turn":1}}\n`,
   }
diff --git a/packages/session-query/session-log-export/tests/route.host.spec.ts b/packages/session-query/session-log-export/tests/route.host.spec.ts
index 44d4b6c476..19d07bb9de 100644
--- a/packages/session-query/session-log-export/tests/route.host.spec.ts
+++ b/packages/session-query/session-log-export/tests/route.host.spec.ts
@@ -1,6 +1,7 @@
 import { Context } from '@deepseek-ai/cordis'
 import { HostConnectionService } from '@deepseek-ai/dsh-client-connection'
 import type { BrowserAuth } from '@deepseek-ai/dsh-client-connection/src/browser-auth.ts'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
 import { strFromU8, unzipSync } from 'fflate'
@@ -20,12 +21,21 @@ function artifact(id: string): SessionRawArtifact {
     id: sid(id),
     createdAt: 1,
     cwd: '/workspace',
+    isSeeded: false,
     delegationDepth: 0,
   }
   return {
     meta: header,
+    inheritedEventCount: SessionLogOffset(0),
     filename: 'session.jsonl',
-    content: `${JSON.stringify({ type: 'session', ...header })}\n`,
+    content: `${JSON.stringify({
+      type: 'session',
+      version: header.version,
+      id: header.id,
+      createdAt: header.createdAt,
+      cwd: header.cwd,
+      delegationDepth: header.delegationDepth,
+    })}\n`,
   }
 }
 
@@ -64,7 +74,9 @@ describe('Session log export Fetch route', () => {
     expect(response.status).toBe(200)
     expect(response.headers.get('content-type')).toBe('application/zip')
     const files = unzipSync(new Uint8Array(await response.arrayBuffer()))
-    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toContain('"id":"session-1"')
+    const exported = strFromU8(files['session.jsonl'] as Uint8Array)
+    expect(exported).toContain('"id":"session-1"')
+    expect(exported).not.toContain('isSeeded')
 
     const head = await shared.fetch(new Request(
       `http://host${SESSION_LOG_EXPORT_PATH}?sessionId=session-1`, { method: 'HEAD' },
diff --git a/packages/session-query/session-query-sqlite/README.i18n.yaml b/packages/session-query/session-query-sqlite/README.i18n.yaml
index 084c4a9abf..23e7b38fac 100644
--- a/packages/session-query/session-query-sqlite/README.i18n.yaml
+++ b/packages/session-query/session-query-sqlite/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/session-query/session-query-sqlite/README.md
-README.md: cac104a9b624e9709b47329e766f6bd97a85f4c6
-README.zh.md: cdbc10c53b701384af4b20311813670df87244b8
+README.md: 1db3999186beebc10a6a3c6874122fa65f2787a3
+README.zh.md: f6ef419293ab0df3a3edfd171cc60bc62ee4bcb0
diff --git a/packages/session-query/session-query-sqlite/README.md b/packages/session-query/session-query-sqlite/README.md
index cac104a9b6..1db3999186 100644
--- a/packages/session-query/session-query-sqlite/README.md
+++ b/packages/session-query/session-query-sqlite/README.md
@@ -101,7 +101,7 @@ The design history lives in the [SQLite FTS5 session search note](../../../.agen
 
 ### Index lifecycle
 
-Persisted FTS rows live in a dedicated derived database and survive restarts; live sessions use connection-local TEMP tables that shadow the durable base for the same session and reveal it again when the live owner detaches. Each search runs one serialized observation: list persistence snapshots, compare per-session revisions with the indexed rows, inspect only new or changed logs, extract semantic documents, and commit the reconciliation in one transaction before running the query. Repeated queries and unchanged reopens inspect nothing; switching stores or observing new, changed, deleted, or externally repaired sources reconciles on the next stable observation. Source or transaction failure commits nothing and the next search retries.
+Persisted FTS rows live in a dedicated derived database and survive restarts; live sessions use connection-local TEMP tables that shadow the durable base for the same session and reveal it again when the live owner detaches. Both tables retain the exact inherited cut in numeric `seed_length`; reconstructed headers expose only `isSeeded`, while the cut participates in live fingerprints and persisted source revisions. Each search runs one serialized observation: list persistence snapshots, compare per-session revisions with the indexed rows, inspect only new or changed logs, extract semantic documents, and commit the reconciliation in one transaction before running the query. Repeated queries and unchanged reopens inspect nothing; switching stores or observing new, changed, deleted, or externally repaired sources reconciles on the next stable observation. Source or transaction failure commits nothing and the next search retries.
 
 ### Schema ownership
 
diff --git a/packages/session-query/session-query-sqlite/README.zh.md b/packages/session-query/session-query-sqlite/README.zh.md
index cdbc10c53b..f6ef419293 100644
--- a/packages/session-query/session-query-sqlite/README.zh.md
+++ b/packages/session-query/session-query-sqlite/README.zh.md
@@ -101,7 +101,7 @@ kind: "package-reference"
 
 ### 索引生命周期
 
-持久化 FTS 行存放在专用派生数据库中并跨重启保留；实时会话使用连接本地 TEMP 表，遮蔽同一会话的持久化基库，并在实时所有者脱离后再次显示基库。每次搜索执行一次串行化观察：列出持久化快照、把逐会话修订与已索引行比较、只检查新增或已更改日志、提取语义文档，并在运行查询前于一个事务中提交对账。重复查询与不变的重新打开不会检查任何内容；切换存储或观察到新增、已更改、已删除或经外部修复的来源时，会在下次稳定观察时对账。来源或事务失败不提交任何内容，下一次搜索重试。
+持久化 FTS 行存放在专用派生数据库中并跨重启保留；实时会话使用连接本地 TEMP 表，遮蔽同一会话的持久化基库，并在实时所有者脱离后再次显示基库。两类表都在数字 `seed_length` 中保留精确继承切点；重建的 header 只公开 `isSeeded`，而切点参与实时 fingerprint 与持久来源修订。每次搜索执行一次串行化观察：列出持久化快照、把逐会话修订与已索引行比较、只检查新增或已更改日志、提取语义文档，并在运行查询前于一个事务中提交对账。重复查询与不变的重新打开不会检查任何内容；切换存储或观察到新增、已更改、已删除或经外部修复的来源时，会在下次稳定观察时对账。来源或事务失败不提交任何内容，下一次搜索重试。
 
 ### Schema 归属
 
diff --git a/packages/session-query/session-query-sqlite/src/index.ts b/packages/session-query/session-query-sqlite/src/index.ts
index f7e4ce043d..4722557a65 100644
--- a/packages/session-query/session-query-sqlite/src/index.ts
+++ b/packages/session-query/session-query-sqlite/src/index.ts
@@ -8,7 +8,14 @@ import { createHash, randomUUID } from 'node:crypto'
 import type { DatabaseSync } from 'node:sqlite'
 import { Context, Service, type Fiber } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
-import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionHeader,
+  SessionId,
+  SessionLogOffset,
+} from '@deepseek-ai/dsh-session'
 import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
 import type {
   SessionPersistenceRevision,
@@ -126,6 +133,7 @@ interface ResolvedConfig {
 
 interface ObservedSession {
   header: SessionHeader
+  inheritedEventCount: SessionLogOffset
   documents: SessionEventSearchDocument[]
   fingerprint: string
 }
@@ -508,7 +516,11 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
             const loaded = await persistence.inspect(entry.header.id, signal)
             assertNotAborted(signal)
             assertSessionHeadersCompatible(entry.header, loaded.meta)
-            entry.loaded = observeSession(loaded.meta, loaded.events)
+            entry.loaded = observeSession(
+              loaded.meta,
+              loaded.inheritedEventCount,
+              loaded.events,
+            )
           }
           assertNotAborted(signal)
           const afterSnapshots = await persistence.listSnapshots(signal)
@@ -577,7 +589,7 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
         (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, agent_preset, revision, generation)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
-      ...headerBindings(entry.header),
+      ...headerBindings(entry.header, entry.inheritedEventCount),
       revision,
       generation,
     )
@@ -607,7 +619,7 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
         (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, agent_preset, fingerprint, persisted, generation)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
-      ...headerBindings(entry.header),
+      ...headerBindings(entry.header, entry.inheritedEventCount),
       entry.fingerprint,
       persisted ? 1 : 0,
       generation,
@@ -741,7 +753,7 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
   private _eventHit(row: SearchRow): SessionEventSearchHit {
     return {
       sessionId: row.session_id as SessionId,
-      seq: row.seq,
+      seq: SessionSeq(row.seq),
       type: row.type as SessionEventSearchHit['type'],
       time: row.time,
       surface: row.surface as SessionEventSearchHit['surface'],
@@ -766,14 +778,17 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
  * @param header - the session header being written.
  * @returns one bound value per header column.
  */
-function headerBindings(header: SessionHeader): (string | number | null)[] {
+function headerBindings(
+  header: SessionHeader,
+  inheritedEventCount: SessionLogOffset,
+): (string | number | null)[] {
   return [
     header.id,
     header.version,
     header.createdAt,
     header.cwd ?? null,
     header.parentSession ?? null,
-    header.seedLength ?? null,
+    header.isSeeded ? inheritedEventCount : null,
     header.delegationDepth ?? null,
     header.agentPreset ?? null,
   ]
@@ -854,17 +869,22 @@ function selectedDocumentsParams(query: string, persistenceVisible: boolean): Ar
 }
 
 function observeLive(session: Session): ObservedSession {
-  return observeSession(session.header, session.snapshotEvents())
+  return observeSession(session.header, session.inheritedEventCount, session.snapshotEvents())
 }
 
-function observeSession(header: SessionHeader, events: readonly SessionEvent[]): ObservedSession {
+function observeSession(
+  header: SessionHeader,
+  inheritedEventCount: SessionLogOffset,
+  events: readonly SessionEvent[],
+): ObservedSession {
   const detachedHeader = structuredClone(header)
   const detachedEvents = events.map(event => structuredClone(event))
   return {
     header: detachedHeader,
+    inheritedEventCount,
     documents: buildSessionEventSearchDocuments(detachedHeader.id, detachedEvents),
     fingerprint: createHash('sha256')
-      .update(JSON.stringify({ header: detachedHeader, events: detachedEvents }))
+      .update(JSON.stringify({ header: detachedHeader, inheritedEventCount, events: detachedEvents }))
       .digest('base64url'),
   }
 }
@@ -920,7 +940,7 @@ function sameHeader(a: SessionHeader, b: SessionHeader): boolean {
     && a.createdAt === b.createdAt
     && a.cwd === b.cwd
     && a.parentSession === b.parentSession
-    && a.seedLength === b.seedLength
+    && a.isSeeded === b.isSeeded
     && (a.delegationDepth ?? 0) === (b.delegationDepth ?? 0)
     && a.agentPreset === b.agentPreset
 }
@@ -932,7 +952,7 @@ function rowHeader(row: SessionHeaderRow): SessionHeader {
     createdAt: row.created_at,
     ...row.cwd === null ? {} : { cwd: row.cwd },
     ...row.parent_session === null ? {} : { parentSession: row.parent_session as SessionId },
-    ...row.seed_length === null ? {} : { seedLength: row.seed_length },
+    isSeeded: row.seed_length !== null,
     ...row.delegation_depth === null ? {} : { delegationDepth: row.delegation_depth },
     ...row.agent_preset === null ? {} : { agentPreset: row.agent_preset },
   }
diff --git a/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts b/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts
index 5306221d0a..29d37915fb 100644
--- a/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts
+++ b/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts
@@ -8,7 +8,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SqliteSessionQueryEngine, * as queryModule from '@deepseek-ai/dsh-session-query-sqlite'
@@ -48,10 +48,15 @@ describe('dsh-session-query-sqlite real Loader path', () => {
     const query = await ctx.plugin(unwrapped, { path: searchPath })
 
     const id = SessionId('loader-path')
-    await ctx.sessionPersistence.create({ version: SESSION_FORMAT_VERSION, id, createdAt: 10 })
+    await ctx.sessionPersistence.create({
+      version: SESSION_FORMAT_VERSION,
+      id,
+      createdAt: 10,
+      isSeeded: false,
+    })
     await ctx.sessionPersistence.append(id, [{
       type: 'user/message',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 10,
       data: createUserMessage({
         content: [{ type: 'text', text: 'real Loader needle' }], source: { kind: 'user' },
diff --git a/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts b/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts
index 248151580d..e09d74ba12 100644
--- a/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts
+++ b/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts
@@ -5,11 +5,16 @@ import { DatabaseSync } from 'node:sqlite'
 import { chmod, mkdtemp, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, {
+  SESSION_FORMAT_VERSION,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+} from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
 import SessionPersistence, { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
-import type { SessionPersistenceSnapshot } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionEventSuffix, SessionInspection, SessionPersistenceSnapshot } from '@deepseek-ai/dsh-session-persistence'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SqliteSessionQueryEngine, {
   SESSION_QUERY_SQLITE_SCHEMA_VERSION,
@@ -38,13 +43,13 @@ async function temporaryPath(name = 'search.db'): Promise<string> {
 }
 
 function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}): SessionHeader {
-  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, ...extra }
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, isSeeded: false, ...extra }
 }
 
-function messageEvents(text: string, time = 1): SessionEvent[] {
+function messageEvents(text: string, time = 1): SessionEvent<'user/message'>[] {
   return [{
     type: 'user/message',
-    seq: 0,
+    seq: SessionSeq(0),
     time,
     data: createUserMessage({
       content: [{ type: 'text', text }], source: { kind: 'user' },
@@ -70,7 +75,11 @@ function replaceCursorOffset(
 class TestPersistence extends SessionPersistence {
   override readonly supportsRawArtifacts = false
 
-  static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
+  static entries = new Map<SessionIdType, {
+    meta: SessionHeader
+    inheritedEventCount?: SessionLogOffset
+    events: SessionEvent[]
+  }>()
   static revisions = new Map<SessionIdType, number>()
   static nextRevision = 0
   static loads = new Map<SessionIdType, number>()
@@ -96,7 +105,11 @@ class TestPersistence extends SessionPersistence {
     return Promise.reject(new Error('not used'))
   }
 
-  static reset(entries: readonly { meta: SessionHeader; events: SessionEvent[] }[] = []): void {
+  static reset(entries: readonly {
+    meta: SessionHeader
+    inheritedEventCount?: SessionLogOffset
+    events: SessionEvent[]
+  }[] = []): void {
     this.entries = new Map()
     this.revisions = new Map()
     this.loads = new Map()
@@ -113,13 +126,21 @@ class TestPersistence extends SessionPersistence {
     this.failure = undefined
   }
 
-  static set(entry: { meta: SessionHeader; events: SessionEvent[] }): void {
+  static set(entry: {
+    meta: SessionHeader
+    inheritedEventCount?: SessionLogOffset
+    events: SessionEvent[]
+  }): void {
     this.entries.set(entry.meta.id, structuredClone(entry))
     this.revisions.set(entry.meta.id, ++this.nextRevision)
   }
 
-  create(meta: SessionHeader): Promise<void> {
-    TestPersistence.set({ meta, events: [] })
+  create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void> {
+    TestPersistence.set({
+      meta,
+      ...inheritedEventCount === undefined ? {} : { inheritedEventCount },
+      events: [],
+    })
     return Promise.resolve()
   }
 
@@ -131,7 +152,7 @@ class TestPersistence extends SessionPersistence {
     return Promise.resolve()
   }
 
-  async load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  async load(id: SessionIdType): Promise<SessionInspection> {
     TestPersistence.loads.set(id, (TestPersistence.loads.get(id) ?? 0) + 1)
     if (TestPersistence.failure !== undefined) throw TestPersistence.failure
     const entry = TestPersistence.entries.get(id)
@@ -142,10 +163,13 @@ class TestPersistence extends SessionPersistence {
       effect(entry)
       TestPersistence.revisions.set(id, ++TestPersistence.nextRevision)
     }
-    return structuredClone(entry)
+    return {
+      ...structuredClone(entry),
+      inheritedEventCount: entry.inheritedEventCount ?? SessionLogOffset(0),
+    }
   }
 
-  async inspect(id: SessionIdType, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  async inspect(id: SessionIdType, signal?: AbortSignal): Promise<SessionInspection> {
     TestPersistence.inspections.set(id, (TestPersistence.inspections.get(id) ?? 0) + 1)
     TestPersistence.inspectSignals.push(signal)
     if (TestPersistence.failure !== undefined) throw TestPersistence.failure
@@ -153,12 +177,19 @@ class TestPersistence extends SessionPersistence {
     if (entry === undefined) throw new Error('missing test session')
     await TestPersistence.inspectEffect?.(entry, signal)
     TestPersistence.inspectEffect = undefined
-    return structuredClone(entry)
+    return {
+      ...structuredClone(entry),
+      inheritedEventCount: entry.inheritedEventCount ?? SessionLogOffset(0),
+    }
   }
 
-  async readFrom(id: SessionIdType, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  async readFrom(
+    id: SessionIdType,
+    fromSeq: SessionLogOffset,
+    signal?: AbortSignal,
+  ): Promise<SessionEventSuffix> {
     const whole = await this.inspect(id, signal)
-    return { meta: whole.meta, events: whole.events.filter(event => event.seq >= fromSeq) }
+    return { ...whole, fromSeq, events: whole.events.filter(event => event.seq >= fromSeq) }
   }
 
   async list(): Promise<SessionHeader[]> {
@@ -322,10 +353,12 @@ describe('SQLite session search', () => {
   it('searches two-character Unicode61 tokens in live-only sessions', async () => {
     const ctx = await liveContext({ path: ':memory:', snippetChars: 20 })
     const session = ctx.sessions.create(SessionId('live'), {
+      seed: messageEvents('inherited context'),
+      inheritedEventCount: SessionLogOffset(1),
       // agentPreset rides along: the index rebuilds the header a caller reads,
       // and a session listed under the wrong composition is a lie about what it
       // ran. The full-header comparison below is what pins every column.
-      meta: { cwd: '/work', createdAt: 10, seedLength: 1, delegationDepth: 2, agentPreset: 'minimal' },
+      meta: { cwd: '/work', createdAt: 10, isSeeded: true, delegationDepth: 2, agentPreset: 'minimal' },
     })
     session.append(
       'user/message',
@@ -337,11 +370,44 @@ describe('SQLite session search', () => {
 
     await expect(ctx.sessionQuery.searchEvents({ sessionId: session.id, query: 'AI' }))
       .resolves.toMatchObject({
-        session: { ...session.header, seedLength: 1 },
-        items: [{ sessionId: session.id, seq: 0, snippet: 'An AI helper' }],
+        session: session.header,
+        items: [{ sessionId: session.id, seq: 2, snippet: 'An AI helper' }],
       })
     await expect(ctx.sessionQuery.searchSessions({ query: 'AI' }))
-      .resolves.toMatchObject({ items: [{ header: { ...session.header, seedLength: 1 }, live: true, persisted: false }] })
+      .resolves.toMatchObject({ items: [{ header: session.header, live: true, persisted: false }] })
+    const db = (ctx.sessionQuery as unknown as { _db: DatabaseSync })._db
+    expect(db.prepare('SELECT seed_length FROM temp.live_sessions WHERE id = ?').get(session.id))
+      .toEqual({ seed_length: 1 })
+  })
+
+  it('retains a persisted inherited cut and reindexes when that source identity changes', async () => {
+    const meta = header('persisted-seed-cut', 10, { isSeeded: true })
+    const events: SessionEvent[] = [
+      ...messageEvents('persisted cut needle'),
+      { ...messageEvents('second inherited event')[0]!, seq: SessionSeq(1) },
+    ]
+    TestPersistence.reset([{
+      meta,
+      inheritedEventCount: SessionLogOffset(1),
+      events,
+    }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    const db = (ctx.sessionQuery as unknown as { _db: DatabaseSync })._db
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .resolves.toMatchObject({ items: [{ header: { ...meta, isSeeded: true } }] })
+    expect(db.prepare('SELECT seed_length FROM persisted_sessions WHERE id = ?').get(meta.id))
+      .toEqual({ seed_length: 1 })
+
+    TestPersistence.set({
+      meta,
+      inheritedEventCount: SessionLogOffset(2),
+      events,
+    })
+    await ctx.sessionQuery.searchSessions({ query: 'needle' })
+    expect(db.prepare('SELECT seed_length FROM persisted_sessions WHERE id = ?').get(meta.id))
+      .toEqual({ seed_length: 2 })
   })
 
   it('excludes assistant reasoning while indexing visible answer text', async () => {
@@ -378,14 +444,14 @@ describe('SQLite session search', () => {
     const ctx = await liveContext({ path: ':memory:', defaultLimit: 10, maxLimit: 20 })
     const parent = SessionId('parent')
     const events: SessionEvent[] = [
-      { type: 'user/message', seq: 0, time: 10, data: createUserMessage({
+      { type: 'user/message', seq: SessionSeq(0), time: 10, data: createUserMessage({
         content: [{ type: 'text', text: 'needle original' }], source: { kind: 'user' },
       }), surfaceOp: 'append' },
-      { type: 'assistant/chunk', seq: 1, time: 11, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'needle raw' } } },
-      { type: 'user/message', seq: 2, time: 12, data: createUserMessage({
+      { type: 'assistant/chunk', seq: SessionSeq(1), time: 11, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'needle raw' } } },
+      { type: 'user/message', seq: SessionSeq(2), time: 12, data: createUserMessage({
         content: [{ type: 'text', text: 'needle summary' }], source: { kind: 'plugin', plugin: 'test' },
-      }), surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] },
-      { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'error', error: { message: 'needle failure', code: 'UNKNOWN' } } } },
+      }), surfaceOp: { op: 'replace', start: SessionSeq(0), end: SessionSeq(0) }, sourceEventSeqs: [SessionSeq(0)] },
+      { type: 'turn/end', seq: SessionSeq(3), time: 13, data: { turn: 1, reason: { kind: 'error', error: { message: 'needle failure', code: 'UNKNOWN' } } } },
     ]
     ctx.sessions.create(SessionId('a'), { seed: events, meta: { cwd: '/a', parentSession: parent, createdAt: 20 } })
     ctx.sessions.create(SessionId('b'), { seed: messageEvents('needle peer', 12), meta: { createdAt: 20 } })
@@ -542,8 +608,8 @@ describe('SQLite session search', () => {
     const target = ctx.sessions.create(SessionId('target'), {
       seed: [
         ...messageEvents('needle one', 10),
-        { ...messageEvents('needle two', 11)[0]!, seq: 1 },
-        { ...messageEvents('needle three', 12)[0]!, seq: 2 },
+        { ...messageEvents('needle two', 11)[0]!, seq: SessionSeq(1) },
+        { ...messageEvents('needle three', 12)[0]!, seq: SessionSeq(2) },
       ],
     })
     ctx.sessions.create(SessionId('other'), { seed: messageEvents('needle other', 10) })
@@ -885,7 +951,7 @@ describe('SQLite reconciliation and source lifecycle', () => {
     const durable = header('post-reconcile-unmount')
     TestPersistence.reset([{ meta: durable, events: [
       ...messageEvents('durable needle', 1),
-      { ...messageEvents('durable needle again', 2)[0]!, seq: 1 },
+      { ...messageEvents('durable needle again', 2)[0]!, seq: SessionSeq(1) },
     ] }])
     const ctx = await liveContext({ path: ':memory:', defaultLimit: 1, maxLimit: 2 })
     const persistence = await ctx.plugin(TestPersistence)
diff --git a/packages/session-query/session-query/README.i18n.yaml b/packages/session-query/session-query/README.i18n.yaml
index 46ba6f606f..c6092ee220 100644
--- a/packages/session-query/session-query/README.i18n.yaml
+++ b/packages/session-query/session-query/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/session-query/session-query/README.md
-README.md: e5729e95785df03ffa1d83ab99123f7fac681753
-README.zh.md: 52f0816256a641c9c94375c745c90dca8df24264
+README.md: 549ec7344d53a09e82568be4d1a21778367c38cc
+README.zh.md: d2161b9528306ead31d709c4d4f6fab20feec8fd
diff --git a/packages/session-query/session-query/README.md b/packages/session-query/session-query/README.md
index e5729e9578..549ec7344d 100644
--- a/packages/session-query/session-query/README.md
+++ b/packages/session-query/session-query/README.md
@@ -42,6 +42,8 @@ Use `ctx.sessionQuery` from application code when you need to read or search ses
 | `traceEvent(request)` | One event's positional replacements and cited source-event relationships |
 | `searchSessions(request)` / `searchEvents(request)` | Full-text search pages, implemented by the mounted backend |
 
+Body-free records expose only `SessionHeader.isSeeded`. Reads that return event bodies (`readSession`, `readSurface`, `readEvent`) and retained `SessionObservation` values also carry the exact `inheritedEventCount`, so callers can distinguish inherited and owned events without inferring a cut from the log.
+
 ### Filters
 
 `SessionResultFilter` narrows sessions by id, nullable cwd, created-at range, nullable parent, or source availability; `SessionEventResultFilter` narrows events by seq/time range, event type, surface, or literal text. Filter arrays are ANDed and list values within one clause are ORed; empty list values match nothing, ranges are inclusive, and malformed ranges or unknown closed-union values fail with `SESSION_QUERY_INVALID_FILTER`.
diff --git a/packages/session-query/session-query/README.zh.md b/packages/session-query/session-query/README.zh.md
index 52f0816256..d2161b9528 100644
--- a/packages/session-query/session-query/README.zh.md
+++ b/packages/session-query/session-query/README.zh.md
@@ -42,6 +42,8 @@ kind: "package-reference"
 | `traceEvent(request)` | 一个事件的位置替换与被引用源事件关系 |
 | `searchSessions(request)` / `searchEvents(request)` | 全文搜索分页结果，由挂载的后端实现 |
 
+不带正文的记录只公开 `SessionHeader.isSeeded`。返回事件正文的读取（`readSession`、`readSurface`、`readEvent`）与保留的 `SessionObservation` 值还携带精确 `inheritedEventCount`，因此调用方无需从日志推断切点即可区分继承事件与自有事件。
+
 ### 过滤器
 
 `SessionResultFilter` 按 id、可空 cwd、创建时间范围、可空父级或来源可用性缩小会话范围；`SessionEventResultFilter` 按 seq/时间范围、事件类型、表层或字面文本缩小事件范围。过滤器数组使用 AND 连接，同一子句内的列表值使用 OR；空列表值不匹配任何内容，范围包含端点，格式错误的范围或未知的封闭联合值以 `SESSION_QUERY_INVALID_FILTER` 失败。
diff --git a/packages/session-query/session-query/src/corpus.ts b/packages/session-query/session-query/src/corpus.ts
index 487b6a9702..a9746b1793 100644
--- a/packages/session-query/session-query/src/corpus.ts
+++ b/packages/session-query/session-query/src/corpus.ts
@@ -1,7 +1,13 @@
 /** Live/persisted logical-corpus resolution for session-query. */
 
 import type { Context, Fiber } from '@deepseek-ai/cordis'
-import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionHeader,
+  SessionId,
+  SessionLogOffset,
+} from '@deepseek-ai/dsh-session'
 import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
 import type { SessionRecord } from './types.ts'
 import { SessionQueryError } from './config.ts'
@@ -11,6 +17,8 @@ import { assertSessionHeadersCompatible } from './sources.ts'
 export interface LogicalSession {
   /** Cloned source header. */
   header: SessionHeader
+  /** Exact fork-inherited event count paired with {@link header}. */
+  inheritedEventCount: SessionLogOffset
   /** Cloned raw event log. */
   events: SessionEvent[]
 }
@@ -19,6 +27,8 @@ export interface LogicalSession {
 export interface LogicalSessionSource {
   /** Header selected with `events`; callers must clone retained output. */
   readonly header: SessionHeader
+  /** Exact fork-inherited event count paired with {@link header}. */
+  readonly inheritedEventCount: SessionLogOffset
   /** Raw events selected with `header`; valid only for the projection call. */
   readonly events: readonly SessionEvent[]
 }
@@ -109,6 +119,7 @@ export class SessionCorpus {
     assertSessionHeadersCompatible(loaded.meta, listed)
     const snapshot = {
       header: structuredClone(loaded.meta),
+      inheritedEventCount: loaded.inheritedEventCount,
       events: loaded.events.map(event => structuredClone(event)),
     }
     signal?.throwIfAborted()
@@ -185,6 +196,7 @@ export class SessionCorpus {
         assertSessionHeadersCompatible(loaded.meta, listed)
         resolved.set(sessionId, projectSource(sessionId, {
           header: loaded.meta,
+          inheritedEventCount: loaded.inheritedEventCount,
           events: loaded.events,
         }, project, signal))
       } catch (error: unknown) {
@@ -239,7 +251,11 @@ function projectSource<Value>(
 }
 
 function sourceLive(session: Session): LogicalSessionSource {
-  return { header: session.header, events: session.snapshotEvents() }
+  return {
+    header: session.header,
+    inheritedEventCount: session.inheritedEventCount,
+    events: session.snapshotEvents(),
+  }
 }
 
 function orderedResults<Value>(
@@ -292,6 +308,7 @@ async function inspectPersisted(
 function snapshotLive(session: Session): LogicalSession {
   return {
     header: structuredClone(session.header),
+    inheritedEventCount: session.inheritedEventCount,
     events: session.snapshotEvents().map(event => structuredClone(event)),
   }
 }
diff --git a/packages/session-query/session-query/src/documents.ts b/packages/session-query/session-query/src/documents.ts
index 7b22a2c26d..f51ae6b733 100644
--- a/packages/session-query/session-query/src/documents.ts
+++ b/packages/session-query/session-query/src/documents.ts
@@ -1,7 +1,7 @@
 /** Shared event metadata and semantic-document projection. */
 
 import { foldSurface } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEventRecord, SessionEventSearchDocument, SessionEventSurface } from './types.ts'
 import { SessionQueryError } from './config.ts'
 import { extractSessionEventText } from './extraction.ts'
@@ -53,7 +53,7 @@ export function buildSessionEventSearchDocuments(
   return documents
 }
 
-function classifySurface(events: readonly SessionEvent[]): Map<number, SessionEventSurface> {
+function classifySurface(events: readonly SessionEvent[]): Map<SessionSeq, SessionEventSurface> {
   let folded: ReturnType<typeof foldSurface>
   try {
     folded = foldSurface(events)
@@ -65,7 +65,7 @@ function classifySurface(events: readonly SessionEvent[]): Map<number, SessionEv
       { cause: error },
     )
   }
-  const result = new Map<number, SessionEventSurface>()
+  const result = new Map<SessionSeq, SessionEventSurface>()
   for (const seq of folded.nodes) result.set(seq, 'current')
   for (const replacement of folded.replacements) {
     for (const seq of replacement.shadowedSeqs) result.set(seq, 'shadowed')
diff --git a/packages/session-query/session-query/src/index.ts b/packages/session-query/session-query/src/index.ts
index 7be87e2750..8d533f66c9 100644
--- a/packages/session-query/session-query/src/index.ts
+++ b/packages/session-query/session-query/src/index.ts
@@ -5,7 +5,13 @@
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import { Session, snapshotSessionEvent, type SessionId } from '@deepseek-ai/dsh-session'
+import {
+  Session,
+  SessionSeq,
+  snapshotSessionEvent,
+  type SessionId,
+  type SessionSeq as SessionSeqType,
+} from '@deepseek-ai/dsh-session'
 import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
 import type { SessionTitleSnapshot } from '@deepseek-ai/dsh-session-title'
 import type {
@@ -164,9 +170,15 @@ export abstract class SessionQueryEngine extends Service {
    */
   async readSession(sessionId: SessionId): Promise<SessionLogSnapshot> {
     const loaded = await this._corpus.load(sessionId)
-    Session.create(sessionId, loaded.events, loaded.header)
+    Session.create(
+      sessionId,
+      loaded.events,
+      loaded.header,
+      loaded.inheritedEventCount,
+    )
     return {
       session: structuredClone(loaded.header),
+      inheritedEventCount: loaded.inheritedEventCount,
       events: loaded.events.map(snapshotSessionEvent),
     }
   }
@@ -285,6 +297,7 @@ export abstract class SessionQueryEngine extends Service {
     const loaded = await this._corpus.load(sessionId)
     return {
       session: structuredClone(loaded.header),
+      inheritedEventCount: loaded.inheritedEventCount,
       capturedThroughSeq: loaded.events.at(-1)?.seq ?? null,
       events: tracing.currentSurfaceEvents(sessionId, loaded.events),
     }
@@ -335,7 +348,7 @@ export abstract class SessionQueryEngine extends Service {
 
   private async _readEvent(
     sessionId: SessionId,
-    seq: number,
+    seq: SessionSeqType,
     before: number,
     after: number,
     signal?: AbortSignal,
@@ -349,8 +362,8 @@ export abstract class SessionQueryEngine extends Service {
         'SESSION_QUERY_EVENT_NOT_FOUND',
       )
     }
-    const startSeq = Math.max(0, seq - before)
-    const endSeq = Math.min(loaded.events.length - 1, seq + after)
+    const startSeq = SessionSeq(Math.max(0, seq - before))
+    const endSeq = SessionSeq(Math.min(loaded.events.length - 1, seq + after))
     const targetSnapshot = snapshotSessionEvent(target)
     const events = loaded.events.slice(startSeq, endSeq + 1)
       .map(event => event === target
@@ -358,6 +371,7 @@ export abstract class SessionQueryEngine extends Service {
         : snapshotSessionEvent(event))
     return {
       session: structuredClone(loaded.header),
+      inheritedEventCount: loaded.inheritedEventCount,
       target: targetSnapshot,
       events,
       startSeq,
diff --git a/packages/session-query/session-query/src/observation.ts b/packages/session-query/session-query/src/observation.ts
index 4d56007d63..f2aebc9503 100644
--- a/packages/session-query/session-query/src/observation.ts
+++ b/packages/session-query/session-query/src/observation.ts
@@ -1,7 +1,15 @@
 /** Shared live/prepared observations for Session page and lifecycle consumers. */
 
 import type { Context } from '@deepseek-ai/cordis'
-import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionHeader,
+  SessionId,
+  SessionLogOffset as SessionLogOffsetType,
+  SessionSeqCursor,
+} from '@deepseek-ai/dsh-session'
 import type {
   BorrowedSessionSource,
   SessionPersistenceRevision,
@@ -18,8 +26,10 @@ export interface SessionObservation extends Disposable {
   readonly header: SessionHeader
   /** Immutable contiguous events at {@link cursor}. */
   readonly events: readonly SessionEvent[]
+  /** Exact number of fork-inherited events in this Session lifecycle. */
+  readonly inheritedEventCount: SessionLogOffsetType
   /** Last observed event seq, or -1 for an empty log. */
-  readonly cursor: number
+  readonly cursor: SessionSeqCursor
   /** Durable source revision for a cold prepared observation. */
   readonly revision?: SessionPersistenceRevision
   /** Exact projection baseline at {@link cursor}, when the registry is mounted. */
@@ -123,6 +133,7 @@ export class SessionObservationReader {
             source: 'prepared',
             header: prepared.inspection.meta,
             events,
+            inheritedEventCount: prepared.inspection.inheritedEventCount,
             cursor: events.at(-1)?.seq ?? -1,
             revision: prepared.revision,
             ...projections === undefined ? {} : { projections },
@@ -161,6 +172,7 @@ export class SessionObservationReader {
         source: 'live',
         header: session.header,
         events,
+        inheritedEventCount: session.inheritedEventCount,
         cursor: events.at(-1)?.seq ?? -1,
         ...projections === undefined ? {} : { projections },
         retain: () => {
@@ -182,8 +194,8 @@ export class SessionObservationReader {
     const prepared = observation.preparedSession
     const cache = this.ctx.get('sessionProjectionCache')
     return cache === undefined
-      ? registry.hydrate(prepared, {}, events, 0)
-      : cache.hydratePrepared(prepared, observation.inspection.meta, events)
+      ? registry.hydrate(prepared, {}, events, SessionLogOffset(0))
+      : cache.hydratePrepared(prepared, events)
   }
 }
 
diff --git a/packages/session-query/session-query/src/sources.ts b/packages/session-query/session-query/src/sources.ts
index f1bb64275f..efcd83c349 100644
--- a/packages/session-query/session-query/src/sources.ts
+++ b/packages/session-query/session-query/src/sources.ts
@@ -15,7 +15,7 @@ export function assertSessionHeadersCompatible(a: SessionHeader, b: SessionHeade
     || a.createdAt !== b.createdAt
     || a.cwd !== b.cwd
     || a.parentSession !== b.parentSession
-    || a.seedLength !== b.seedLength
+    || a.isSeeded !== b.isSeeded
     || (a.delegationDepth ?? 0) !== (b.delegationDepth ?? 0)
   ) {
     throw new SessionQueryError(
diff --git a/packages/session-query/session-query/src/tracing.ts b/packages/session-query/session-query/src/tracing.ts
index 681e6ce59a..a7fd789b7b 100644
--- a/packages/session-query/session-query/src/tracing.ts
+++ b/packages/session-query/session-query/src/tracing.ts
@@ -1,7 +1,13 @@
 /** One-shot session-lineage and event-relationship tracing helpers. */
 
 import { foldSurface, isSurfaceEvent, snapshotSessionEvent } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionId, SurfaceEvent, SurfaceEventType } from '@deepseek-ai/dsh-session'
+import type {
+  SessionEvent,
+  SessionId,
+  SessionSeq,
+  SurfaceEvent,
+  SurfaceEventType,
+} from '@deepseek-ai/dsh-session'
 import { SessionQueryError } from './config.ts'
 import type {
   SessionEventRecord,
@@ -13,9 +19,9 @@ import type {
 
 interface EventLogAnalysis {
   records: SessionEventRecord[]
-  replacedBy: Map<number, number>
-  replacedEventSeqs: Map<number, number[]>
-  currentSeqs: number[]
+  replacedBy: Map<SessionSeq, SessionSeq>
+  replacedEventSeqs: Map<SessionSeq, SessionSeq[]>
+  currentSeqs: SessionSeq[]
 }
 
 /**
@@ -65,7 +71,7 @@ export function currentSurfaceEvents(
 export function traceEvent(
   sessionId: SessionId,
   events: readonly SessionEvent[],
-  seq: number,
+  seq: SessionSeq,
 ): SessionEventTrace {
   const target = events[seq]
   if (target === undefined || target.seq !== seq) {
@@ -77,14 +83,14 @@ export function traceEvent(
 
   const analysis = analyzeEventLog(sessionId, events)
 
-  const replacementChain: number[] = []
+  const replacementChain: SessionSeq[] = []
   let replacement = analysis.replacedBy.get(seq)
   while (replacement !== undefined) {
     replacementChain.push(replacement)
     replacement = analysis.replacedBy.get(replacement)
   }
 
-  const derivedEventSeqs: number[] = []
+  const derivedEventSeqs: SessionSeq[] = []
   for (const event of events) {
     if (event.seq <= seq) continue
     if (eventSources(event).includes(seq)) derivedEventSeqs.push(event.seq)
@@ -188,8 +194,8 @@ function analyzeEventLog(
     )
   }
   const current = new Set(folded.nodes)
-  const replacedBy = new Map<number, number>()
-  const replacedEventSeqs = new Map<number, number[]>()
+  const replacedBy = new Map<SessionSeq, SessionSeq>()
+  const replacedEventSeqs = new Map<SessionSeq, SessionSeq[]>()
   for (const replacement of folded.replacements) {
     const removed = replacement.shadowedSeqs
     replacedEventSeqs.set(replacement.seq, removed)
@@ -213,7 +219,7 @@ function analyzeEventLog(
   }
 }
 
-function eventSources(event: SessionEvent): readonly number[] {
+function eventSources(event: SessionEvent): readonly SessionSeq[] {
   return (event as SessionEvent<SurfaceEventType>).sourceEventSeqs ?? []
 }
 
diff --git a/packages/session-query/session-query/src/types.ts b/packages/session-query/session-query/src/types.ts
index c98b5a749e..01c196aa1f 100644
--- a/packages/session-query/session-query/src/types.ts
+++ b/packages/session-query/session-query/src/types.ts
@@ -10,6 +10,9 @@ import type {
   SessionEventType,
   SessionHeader,
   SessionId,
+  SessionLogOffset,
+  SessionSeq,
+  OptionalSessionSeq,
   SurfaceEvent,
 } from '@deepseek-ai/dsh-session'
 import type { SessionTitleSnapshot } from '@deepseek-ai/dsh-session-title'
@@ -34,8 +37,10 @@ export interface SessionRecord {
 export interface SessionSurfaceSnapshot {
   /** Cloned session header selected from the same corpus observation as `events`. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Highest raw-log seq included in the observation, or `null` for an empty log. */
-  capturedThroughSeq: number | null
+  capturedThroughSeq: OptionalSessionSeq
   /** Cloned current surface events in model-history order. */
   events: SurfaceEvent[]
 }
@@ -44,6 +49,8 @@ export interface SessionSurfaceSnapshot {
 export interface SessionLogSnapshot {
   /** Cloned session header selected from the same observation as `events`. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Cloned contiguous raw events after persistence repair and replay validation. */
   events: SessionEvent[]
 }
@@ -53,7 +60,7 @@ export interface SessionEventRecord {
   /** Session that owns the event. */
   sessionId: SessionId
   /** Monotonic event seq within the session. */
-  seq: number
+  seq: SessionSeq
   /** Discriminant of the session event. */
   type: SessionEventType
   /** Event timestamp in Unix epoch milliseconds. */
@@ -98,7 +105,7 @@ export interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
   /** Target event seq. */
-  seq: number
+  seq: SessionSeq
 }
 
 /** Direct surface replacements and relationships to cited source events for one event. */
@@ -106,15 +113,15 @@ export interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
   /** Immediate positional replacement event, when the target was shadowed. */
-  replacedBy?: number
+  replacedBy?: SessionSeq
   /** Positional replacers from the immediate replacement to the final replacement. */
-  replacementChain: number[]
+  replacementChain: SessionSeq[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
-  replacedEventSeqs: number[]
+  replacedEventSeqs: SessionSeq[]
   /** Earlier events cited directly as sources, in their recorded order. */
-  sourceEventSeqs: number[]
+  sourceEventSeqs: SessionSeq[]
   /** Later events that directly cite the target as a source, in log order. */
-  derivedEventSeqs: number[]
+  derivedEventSeqs: SessionSeq[]
 }
 
 /** Event relationships bound to the same session-header observation. */
@@ -128,7 +135,7 @@ export interface SessionEventReadRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
   /** Target event seq. */
-  seq: number
+  seq: SessionSeq
   /** Number of preceding raw events to include. */
   before?: number
   /** Number of following raw events to include. */
@@ -139,14 +146,16 @@ export interface SessionEventReadRequest {
 export interface SessionEventWindow {
   /** Cloned header for the live-preferred source read. */
   session: SessionHeader
+  /** Exact number of fork-inherited events in the observed log. */
+  inheritedEventCount: SessionLogOffset
   /** Full cloned target event. */
   target: SessionEvent
   /** Full cloned events from `startSeq` through `endSeq`. */
   events: SessionEvent[]
   /** First seq included in `events`. */
-  startSeq: number
+  startSeq: SessionSeq
   /** Last seq included in `events`. */
-  endSeq: number
+  endSeq: SessionSeq
 }
 
 /** Latest folded title bound to the same session-header observation. */
diff --git a/packages/session-query/session-query/tests/observation.spec.ts b/packages/session-query/session-query/tests/observation.spec.ts
index 7151714b67..ef2460e7a2 100644
--- a/packages/session-query/session-query/tests/observation.spec.ts
+++ b/packages/session-query/session-query/tests/observation.spec.ts
@@ -1,5 +1,5 @@
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionHeader } from '@deepseek-ai/dsh-session'
 import { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
 import type { BorrowedSessionSource } from '@deepseek-ai/dsh-session-persistence'
@@ -8,17 +8,21 @@ import { describe, expect, it, vi } from 'vitest'
 import { SessionObservationReader } from '../src/observation.ts'
 
 function header(id: string): SessionHeader {
-  return { version: 0, id: SessionId(id), createdAt: 1, cwd: '/workspace' }
+  return { version: 0, id: SessionId(id), createdAt: 1, cwd: '/workspace', isSeeded: false }
 }
 
 function preparedSource(
   meta: SessionHeader,
   dispose = vi.fn(),
 ): BorrowedSessionSource {
-  const preparedSession = Session.create(meta.id, [], meta)
+  const preparedSession = Session.create(meta.id, [], meta, SessionLogOffset(0))
   return {
     source: 'prepared',
-    inspection: { meta: preparedSession.header, events: preparedSession.snapshotEvents() },
+    inspection: {
+      meta: preparedSession.header,
+      inheritedEventCount: preparedSession.inheritedEventCount,
+      events: preparedSession.snapshotEvents(),
+    },
     revision: SessionPersistenceRevision(`fixture:${meta.id}`),
     preparedSession,
     [Symbol.dispose]: dispose,
@@ -76,7 +80,9 @@ describe('SessionObservationReader', () => {
     const prepared = preparedSource(meta)
     const borrowSession = vi.fn()
       .mockResolvedValueOnce({
-        source: 'live', inspection: { meta, events: [] }, [Symbol.dispose]: disposeLive,
+        source: 'live',
+        inspection: { meta, inheritedEventCount: SessionLogOffset(0), events: [] },
+        [Symbol.dispose]: disposeLive,
       } satisfies BorrowedSessionSource)
       .mockResolvedValueOnce(prepared)
     ctx.provide('sessionPersistence', { borrowSession } as never)
@@ -139,6 +145,25 @@ describe('SessionObservationReader', () => {
     await ctx.fiber.dispose()
   })
 
+  it('carries the exact inherited cut on a live observation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const inherited = [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    ] as const
+    const session = ctx.sessions.create(SessionId('seeded-observation'), {
+      seed: inherited,
+      inheritedEventCount: SessionLogOffset(inherited.length),
+      meta: { cwd: '/workspace', isSeeded: true },
+    })
+
+    using observed = await new SessionObservationReader(ctx).read(session.id, { projectionMode: 'none' })
+
+    expect(observed.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
+    await ctx.fiber.dispose()
+  })
+
   it('contains a non-Error persistence rejection', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/session-query/session-query/tests/search-helpers.spec.ts b/packages/session-query/session-query/tests/search-helpers.spec.ts
index 3cc4fe5321..0e528ec7f5 100644
--- a/packages/session-query/session-query/tests/search-helpers.spec.ts
+++ b/packages/session-query/session-query/tests/search-helpers.spec.ts
@@ -4,6 +4,7 @@ import { createUserMessage, ToolCallId , createMessage, createToolResultMessage
 import SessionStore, {
   SESSION_FORMAT_VERSION,
   SessionId,
+  SessionSeq,
 } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
@@ -23,7 +24,7 @@ import { TestSessionQueryEngine } from './test-service.ts'
 const id = SessionId('session')
 
 function header(value: string, extra: Partial<SessionHeader> = {}): SessionHeader {
-  return { version: SESSION_FORMAT_VERSION, id: SessionId(value), createdAt: 10, ...extra }
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(value), createdAt: 10, isSeeded: false, ...extra }
 }
 
 function expectCode(code: SessionQueryErrorCode): Error {
@@ -46,10 +47,10 @@ describe('session-query semantic extraction', () => {
       { type: 'future-content', payload: 'hidden' } as never,
     ]
     const events: SessionEvent[] = [
-      { type: 'user/message', seq: 0, time: 1, data: createUserMessage({
+      { type: 'user/message', seq: SessionSeq(0), time: 1, data: createUserMessage({
         content: messageContent, source: { kind: 'user' },
       }), surfaceOp: 'append' },
-      { type: 'assistant/message', seq: 1, time: 2, data: {
+      { type: 'assistant/message', seq: SessionSeq(1), time: 2, data: {
         turn: 1, step: 1,
         message: createMessage({
           role: 'assistant',
@@ -60,13 +61,13 @@ describe('session-query semantic extraction', () => {
           },
         }),
       }, surfaceOp: 'append' },
-      { type: 'user/message', seq: 2, time: 3, data: createUserMessage({
+      { type: 'user/message', seq: SessionSeq(2), time: 3, data: createUserMessage({
         content: messageContent, source: { kind: 'plugin', plugin: 'test' },
       }), surfaceOp: 'append' },
-      { type: 'tool/call', seq: 3, time: 5, data: { turn: 1, step: 1, callId, name: 'bash', arguments: '{"cmd":"pwd"}' } },
+      { type: 'tool/call', seq: SessionSeq(3), time: 5, data: { turn: 1, step: 1, callId, name: 'bash', arguments: '{"cmd":"pwd"}' } },
       {
         type: 'tool/result',
-        seq: 4,
+        seq: SessionSeq(4),
         time: 6,
         data: {
           turn: 1,
@@ -82,7 +83,7 @@ describe('session-query semantic extraction', () => {
       },
       {
         type: 'tool/result',
-        seq: 5,
+        seq: SessionSeq(5),
         time: 7,
         data: {
           turn: 1,
@@ -91,7 +92,7 @@ describe('session-query semantic extraction', () => {
         },
         surfaceOp: 'append',
       },
-      { type: 'todo/write', seq: 6, time: 8, data: { todos: [{ status: 'in_progress', content: 'ship search' }] } },
+      { type: 'todo/write', seq: SessionSeq(6), time: 8, data: { todos: [{ status: 'in_progress', content: 'ship search' }] } },
     ]
 
     for (const event of events.slice(0, 3)) {
@@ -99,7 +100,7 @@ describe('session-query semantic extraction', () => {
     }
     expect(extractSessionEventText({
       type: 'assistant/message',
-      seq: 9,
+      seq: SessionSeq(9),
       time: 10,
       data: {
         turn: 1,
@@ -130,15 +131,15 @@ describe('session-query semantic extraction', () => {
       [{ kind: 'future-status' } as never, ''],
     ]
     for (const [reason, text] of reasons) {
-      expect(extractSessionEventText({ type: 'turn/end', seq: 0, time: 1, data: { turn: 1, reason } })).toBe(text)
+      expect(extractSessionEventText({ type: 'turn/end', seq: SessionSeq(0), time: 1, data: { turn: 1, reason } })).toBe(text)
     }
     const structural: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
-      { type: 'step/end', seq: 2, time: 1, data: { turn: 1, step: 1 } },
-      { type: 'assistant/chunk', seq: 3, time: 1, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } },
-      { type: 'request/header', seq: 4, time: 1, data: { header: { config: { provider: 'test', model: 'test' } }, reason: 'initial' } },
-      { type: 'future/event', seq: 5, time: 1, data: { text: 'hidden' } } as never,
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'step/start', seq: SessionSeq(1), time: 1, data: { turn: 1, step: 1 } },
+      { type: 'step/end', seq: SessionSeq(2), time: 1, data: { turn: 1, step: 1 } },
+      { type: 'assistant/chunk', seq: SessionSeq(3), time: 1, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } },
+      { type: 'request/header', seq: SessionSeq(4), time: 1, data: { header: { config: { provider: 'test', model: 'test' } }, reason: 'initial' } },
+      { type: 'future/event', seq: SessionSeq(5), time: 1, data: { text: 'hidden' } } as never,
     ]
     expect(structural.map(extractSessionEventText)).toEqual(['', '', '', '', '', ''])
   })
@@ -146,11 +147,11 @@ describe('session-query semantic extraction', () => {
 
 describe('session-query document and filter helpers', () => {
   const events: SessionEvent[] = [
-    { type: 'user/message', seq: 0, time: 10, data: createUserMessage({
+    { type: 'user/message', seq: SessionSeq(0), time: 10, data: createUserMessage({
       content: [{ type: 'text', text: 'Hello\n(AI)+' }], source: { kind: 'user' },
     }), surfaceOp: 'append' },
-    { type: 'assistant/chunk', seq: 1, time: 11, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } },
-    { type: 'assistant/message', seq: 2, time: 12, data: {
+    { type: 'assistant/chunk', seq: SessionSeq(1), time: 11, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } },
+    { type: 'assistant/message', seq: SessionSeq(2), time: 12, data: {
       turn: 1, step: 1,
       message: createMessage({
         role: 'assistant',
@@ -160,8 +161,8 @@ describe('session-query document and filter helpers', () => {
           ...{ provider: 'mock', model: 'mock' },
         },
       }),
-    }, surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] },
-    { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'interrupted' } } },
+    }, surfaceOp: { op: 'replace', start: SessionSeq(0), end: SessionSeq(0) }, sourceEventSeqs: [SessionSeq(0)] },
+    { type: 'turn/end', seq: SessionSeq(3), time: 13, data: { turn: 1, reason: { kind: 'interrupted' } } },
   ]
 
   it('classifies every event and omits non-semantic documents', () => {
@@ -229,7 +230,7 @@ describe('session-query document and filter helpers', () => {
     ])).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
     const malformed: SessionEvent[] = [{
       type: 'assistant/message',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: {
         turn: 1, step: 1,
@@ -242,7 +243,7 @@ describe('session-query document and filter helpers', () => {
           },
         }),
       },
-      surfaceOp: { op: 'replace', start: 9, end: 9 },
+      surfaceOp: { op: 'replace', start: SessionSeq(9), end: SessionSeq(9) },
     }]
     expect(() => buildSessionEventRecords(id, malformed)).toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
   })
diff --git a/packages/session-query/session-query/tests/session-query.spec.ts b/packages/session-query/session-query/tests/session-query.spec.ts
index 77161b935f..f011df923d 100644
--- a/packages/session-query/session-query/tests/session-query.spec.ts
+++ b/packages/session-query/session-query/tests/session-query.spec.ts
@@ -1,10 +1,16 @@
 import { createUserMessage, createMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it, vi } from 'vitest'
 import { Context, type Fiber } from '@deepseek-ai/cordis'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, {
+  SESSION_FORMAT_VERSION,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+} from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
 import SessionPersistence, { SessionPersistenceCorruptionError, SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionEventSuffix, SessionInspection } from '@deepseek-ai/dsh-session-persistence'
 import SessionQueryEngine, {
   SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
   type SessionEventSurface,
@@ -16,13 +22,13 @@ import { TestSessionQueryEngine } from './test-service.ts'
 const TITLE_SERVICE_CONFIG = { fallbackMaxWords: 8, fallbackMaxBytes: 64, maxTitleBytes: 256 }
 
 function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}): SessionHeader {
-  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, ...extra }
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, isSeeded: false, ...extra }
 }
 
-function eventLog(text = 'hello'): SessionEvent[] {
+function eventLog(text = 'hello'): SessionEvent<'user/message'>[] {
   return [{
     type: 'user/message',
-    seq: 0,
+    seq: SessionSeq(0),
     time: 10,
     data: createUserMessage({
       content: [{ type: 'text', text }], source: { kind: 'user' },
@@ -42,7 +48,7 @@ class TestPersistence extends SessionPersistence {
   static inspectOverride: ((
     id: SessionIdType,
     signal?: AbortSignal,
-  ) => Promise<{ meta: SessionHeader; events: SessionEvent[] }>) | undefined
+  ) => Promise<SessionInspection>) | undefined
   static afterList: (() => void) | undefined
   static listCalls = 0
   static inspectCalls: SessionIdType[] = []
@@ -83,14 +89,14 @@ class TestPersistence extends SessionPersistence {
     return Promise.resolve()
   }
 
-  load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  load(id: SessionIdType): Promise<SessionInspection> {
     return this.inspect(id)
   }
 
   inspect(
     id: SessionIdType,
     signal?: AbortSignal,
-  ): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  ): Promise<SessionInspection> {
     TestPersistence.inspectCalls.push(id)
     TestPersistence.inspectSignals.push(signal)
     if (TestPersistence.inspectOverride !== undefined) {
@@ -99,15 +105,22 @@ class TestPersistence extends SessionPersistence {
     if (TestPersistence.inspectFailure !== undefined) return rejectUnknown(TestPersistence.inspectFailure)
     const entry = TestPersistence.entries.get(id)
     if (entry === undefined) return Promise.reject(new Error('missing test session'))
-    const result = structuredClone(entry)
+    const result: SessionInspection = {
+      ...structuredClone(entry),
+      inheritedEventCount: SessionLogOffset(0),
+    }
     TestPersistence.inspectEffect?.()
     TestPersistence.inspectEffect = undefined
     return Promise.resolve(result)
   }
 
-  async readFrom(id: SessionIdType, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  async readFrom(
+    id: SessionIdType,
+    fromSeq: SessionLogOffset,
+    signal?: AbortSignal,
+  ): Promise<SessionEventSuffix> {
     const whole = await this.inspect(id, signal)
-    return { meta: whole.meta, events: whole.events.filter(event => event.seq >= fromSeq) }
+    return { ...whole, fromSeq, events: whole.events.filter(event => event.seq >= fromSeq) }
   }
 
   list(signal?: AbortSignal): Promise<SessionHeader[]> {
@@ -176,12 +189,12 @@ const cancellableExactReads: readonly CancellableExactRead[] = [
   {
     name: 'traceEvent',
     inspects: true,
-    run: (ctx, sessionId, signal) => ctx.sessionQuery.traceEvent({ sessionId, seq: 0 }, signal),
+    run: (ctx, sessionId, signal) => ctx.sessionQuery.traceEvent({ sessionId, seq: SessionSeq(0) }, signal),
   },
   {
     name: 'readEvent',
     inspects: true,
-    run: (ctx, sessionId, signal) => ctx.sessionQuery.readEvent({ sessionId, seq: 0 }, signal),
+    run: (ctx, sessionId, signal) => ctx.sessionQuery.readEvent({ sessionId, seq: SessionSeq(0) }, signal),
   },
 ] as const
 
@@ -344,7 +357,10 @@ describe.each(cancellableExactReads)('$name cancellation', ({ inspects, run }) =
         started.resolve(undefined)
         await release.promise
         active = false
-        return structuredClone(entry)
+        return {
+          ...structuredClone(entry),
+          inheritedEventCount: SessionLogOffset(0),
+        }
       }
     } else {
       TestPersistence.listOverride = async () => {
@@ -432,7 +448,7 @@ describe('session-query exact reads', () => {
     const valid = header('valid-log', 2)
     const corrupt = header('corrupt-log', 1)
     const validEvents = eventLog('valid')
-    const corruptEvents = [{ ...eventLog('bad')[0]!, seq: 1 }]
+    const corruptEvents = [{ ...eventLog('bad')[0]!, seq: SessionSeq(1) }]
     TestPersistence.reset([
       { meta: valid, events: validEvents },
       { meta: corrupt, events: corruptEvents },
@@ -441,7 +457,11 @@ describe('session-query exact reads', () => {
     await ctx.plugin(TestPersistence)
 
     const snapshot = await ctx.sessionQuery.readSession(valid.id)
-    expect(snapshot).toEqual({ session: valid, events: validEvents })
+    expect(snapshot).toEqual({
+      session: valid,
+      inheritedEventCount: SessionLogOffset(0),
+      events: validEvents,
+    })
     Object.assign(snapshot.events[0]!, { time: 999 })
     expect(TestPersistence.entries.get(valid.id)?.events[0]?.time).toBe(10)
     await expect(ctx.sessionQuery.readSession(corrupt.id)).rejects.toThrow('seed event at index 0 has seq 1')
@@ -471,11 +491,11 @@ describe('session-query exact reads', () => {
         meta: persistedHeader,
         events: [{
           type: 'session/title',
-          seq: 0,
+          seq: SessionSeq(0),
           time: 20,
           data: {
             title: 'Persisted title',
-            messageSeqs: [4],
+            messageSeqs: [SessionSeq(4)],
             source: { kind: 'fallback' },
           },
         }],
@@ -484,11 +504,11 @@ describe('session-query exact reads', () => {
         meta: sharedHeader,
         events: [{
           type: 'session/title',
-          seq: 0,
+          seq: SessionSeq(0),
           time: 30,
           data: {
             title: 'Stale durable title',
-            messageSeqs: [1],
+            messageSeqs: [SessionSeq(1)],
             source: { kind: 'fallback' },
           },
         }],
@@ -499,7 +519,7 @@ describe('session-query exact reads', () => {
     const shared = ctx.sessions.create(sharedHeader.id, { meta: { createdAt: 3 } })
     shared.append('session/title', {
       title: 'Live title',
-      messageSeqs: [7],
+      messageSeqs: [SessionSeq(7)],
       source: {
         kind: 'provider',
         provider: SessionTitleProviderId('query-test'),
@@ -521,7 +541,7 @@ describe('session-query exact reads', () => {
     const second = header('batch-title-second', 2)
     const titleEvent = (title: string, time: number): SessionEvent => ({
       type: 'session/title',
-      seq: 0,
+      seq: SessionSeq(0),
       time,
       data: {
         title,
@@ -574,7 +594,10 @@ describe('session-query exact reads', () => {
       active -= 1
       const entry = TestPersistence.entries.get(id)
       if (entry === undefined) throw new Error('missing bounded test session')
-      return structuredClone(entry)
+      return {
+        ...structuredClone(entry),
+        inheritedEventCount: SessionLogOffset(0),
+      }
     }
 
     const results = await ctx.sessionQuery.readTitleSnapshots(entries.map(entry => entry.meta.id))
@@ -602,7 +625,7 @@ describe('session-query exact reads', () => {
         const marker = `full-log-marker:${id}`
         const titleEvent = {
           type: 'session/title',
-          seq: 1,
+          seq: SessionSeq(1),
           time: 20,
           data: {
             title: `Projected ${id}`,
@@ -615,6 +638,7 @@ describe('session-query exact reads', () => {
         } as unknown as SessionEvent
         resolve({
           meta: entries.find(entry => entry.meta.id === id)!.meta,
+          inheritedEventCount: SessionLogOffset(0),
           events: [...eventLog(marker), titleEvent],
         })
       })
@@ -745,7 +769,7 @@ describe('session-query exact reads', () => {
     const inspectFailure = new Error('one title inspect failed')
     const malformedTitle = {
       type: 'session/title',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 30,
       data: {
         title: 'malformed',
@@ -772,7 +796,10 @@ describe('session-query exact reads', () => {
           source: { kind: 'fallback' },
         })
       }
-      return Promise.resolve(structuredClone(entry))
+      return Promise.resolve({
+        ...structuredClone(entry),
+        inheritedEventCount: SessionLogOffset(0),
+      })
     }
 
     const results = await ctx.sessionQuery.readTitleSnapshots([
@@ -971,7 +998,10 @@ describe('session-query exact reads', () => {
       createUserMessage({
         content: [{ type: 'text', text: 'latest checkpoint' }], source: { kind: 'plugin', plugin: 'compact' },
       }),
-      { surfaceOp: { op: 'replace', start: 2, end: retained.seq }, sourceEventSeqs: [2, retained.seq] },
+      {
+        surfaceOp: { op: 'replace', start: SessionSeq(2), end: retained.seq },
+        sourceEventSeqs: [SessionSeq(2), retained.seq],
+      },
     )
     session.append(
       'assistant/message',
@@ -1002,7 +1032,7 @@ describe('session-query exact reads', () => {
     }).toThrow()
     Object.assign(snapshot.session, { cwd: '/mutated' })
 
-    const logged = session.eventAt(4)
+    const logged = session.eventAt(SessionSeq(4))
     expect(logged?.type === 'user/message' && logged.data.content).toHaveLength(1)
     expect(session.header.cwd).toBe('/work')
   })
@@ -1030,7 +1060,12 @@ describe('session-query exact reads', () => {
       )
     }
 
-    const result = await ctx.sessionQuery.readEvent({ sessionId: session.id, seq: 2, before: 1, after: 1 })
+    const result = await ctx.sessionQuery.readEvent({
+      sessionId: session.id,
+      seq: SessionSeq(2),
+      before: 1,
+      after: 1,
+    })
     expect([result.startSeq, result.endSeq, result.target.seq]).toEqual([1, 3, 2])
     expect(result.session).toEqual(session.header)
     Object.assign(result.session, { createdAt: -1 })
@@ -1039,15 +1074,15 @@ describe('session-query exact reads', () => {
       (result.events[0]!.data as { content: unknown[] }).content = []
     }).toThrow()
     expect(session.header.createdAt).not.toBe(-1)
-    const logged = session.eventAt(1)
+    const logged = session.eventAt(SessionSeq(1))
     expect(logged?.type === 'user/message' && logged.data.content).toHaveLength(1)
 
-    await expect(ctx.sessionQuery.readEvent({ sessionId: session.id, seq: 9 }))
+    await expect(ctx.sessionQuery.readEvent({ sessionId: session.id, seq: SessionSeq(9) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_EVENT_NOT_FOUND'))
     for (const request of [
-      { sessionId: session.id, seq: 0, before: -1 },
-      { sessionId: session.id, seq: 0, before: 2 },
-      { sessionId: session.id, seq: 0, after: 0.5 },
+      { sessionId: session.id, seq: SessionSeq(0), before: -1 },
+      { sessionId: session.id, seq: SessionSeq(0), before: 2 },
+      { sessionId: session.id, seq: SessionSeq(0), after: 0.5 },
     ]) {
       await expect(ctx.sessionQuery.readEvent(request)).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_WINDOW'))
     }
@@ -1074,13 +1109,13 @@ describe('session-query exact reads', () => {
 
     expect((await ctx.sessionQuery.listSessions()).map(record => [record.header.id, record.live, record.persisted]))
       .toEqual([[shared.id, true, true], [durable.id, false, true]])
-    const liveRead = await ctx.sessionQuery.readEvent({ sessionId: shared.id, seq: 1 })
+    const liveRead = await ctx.sessionQuery.readEvent({ sessionId: shared.id, seq: SessionSeq(1) })
     expect(liveRead.target.type === 'user/message' && liveRead.target.data.content[0])
       .toMatchObject({ text: 'live' })
     await expect(ctx.sessionQuery.readSurface(shared.id)).resolves.toMatchObject({
       events: [{ data: { content: [{ text: 'live' }] } }],
     })
-    await expect(ctx.sessionQuery.readEvent({ sessionId: durable.id, seq: 0 }))
+    await expect(ctx.sessionQuery.readEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .resolves.toMatchObject({ session: durable })
     await expect(ctx.sessionQuery.readSurface(durable.id)).resolves.toMatchObject({
       session: durable,
@@ -1116,9 +1151,9 @@ describe('session-query exact reads', () => {
     const signal = new AbortController().signal
 
     await expect(ctx.sessionQuery.listEvents(live.id)).resolves.toHaveLength(2)
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: live.id, seq: 1 }, signal))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: live.id, seq: SessionSeq(1) }, signal))
       .resolves.toMatchObject({ session: { id: live.id }, target: { seq: 1 } })
-    await expect(ctx.sessionQuery.readEvent({ sessionId: live.id, seq: 1 }, signal))
+    await expect(ctx.sessionQuery.readEvent({ sessionId: live.id, seq: SessionSeq(1) }, signal))
       .resolves.toMatchObject({ target: { seq: 1 } })
     expect(TestPersistence.listSignals).toEqual([])
     expect(TestPersistence.inspectSignals).toEqual([])
@@ -1175,7 +1210,7 @@ describe('session-query exact reads', () => {
       meta: persisted,
       events: [{
         type: 'user/message',
-        seq: 0,
+        seq: SessionSeq(0),
         time: 1,
         data: createUserMessage({
           content: [{ type: 'text', text: 'hidden' }], source: { kind: 'user' },
diff --git a/packages/session-query/session-query/tests/tracing.spec.ts b/packages/session-query/session-query/tests/tracing.spec.ts
index d90328bbca..e40af94f68 100644
--- a/packages/session-query/session-query/tests/tracing.spec.ts
+++ b/packages/session-query/session-query/tests/tracing.spec.ts
@@ -1,10 +1,16 @@
 import { createUserMessage, createMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, {
+  SESSION_FORMAT_VERSION,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+} from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { Session, SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
 import SessionPersistence from '@deepseek-ai/dsh-session-persistence'
+import type { SessionEventSuffix, SessionInspection } from '@deepseek-ai/dsh-session-persistence'
 import { type SessionQueryErrorCode } from '@deepseek-ai/dsh-session-query'
 import { TestSessionQueryEngine } from './test-service.ts'
 
@@ -16,10 +22,10 @@ function mutableHeader(value: SessionHeader): MutableSessionHeader {
 }
 
 function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}): SessionHeader {
-  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, ...extra }
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, isSeeded: false, ...extra }
 }
 
-function appendEvent(seq: number, sources?: number[]): SessionEvent {
+function appendEvent(seq: SessionSeq, sources?: number[]): SessionEvent {
   return {
     type: 'user/message',
     seq,
@@ -28,7 +34,7 @@ function appendEvent(seq: number, sources?: number[]): SessionEvent {
       content: [{ type: 'text', text: `event ${seq}` }], source: { kind: 'user' },
     }),
     surfaceOp: 'append',
-    ...sources === undefined ? {} : { sourceEventSeqs: sources },
+    ...sources === undefined ? {} : { sourceEventSeqs: sources.map(SessionSeq) },
   }
 }
 
@@ -71,21 +77,24 @@ class TracePersistence extends SessionPersistence {
     return Promise.resolve()
   }
 
-  load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  load(id: SessionIdType): Promise<SessionInspection> {
     return this.inspect(id)
   }
 
-  inspect(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  inspect(id: SessionIdType): Promise<SessionInspection> {
     TracePersistence.inspectCalls += 1
     if (TracePersistence.inspectFailure !== undefined) return Promise.reject(TracePersistence.inspectFailure)
     const entry = TracePersistence.entries.get(id)
     if (entry === undefined) return Promise.reject(new Error('missing test session'))
-    return Promise.resolve(structuredClone(entry))
+    return Promise.resolve({
+      ...structuredClone(entry),
+      inheritedEventCount: SessionLogOffset(0),
+    })
   }
 
-  async readFrom(id: SessionIdType, fromSeq: number): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  async readFrom(id: SessionIdType, fromSeq: SessionLogOffset): Promise<SessionEventSuffix> {
     const whole = await this.inspect(id)
-    return { meta: whole.meta, events: whole.events.filter(event => event.seq >= fromSeq) }
+    return { ...whole, fromSeq, events: whole.events.filter(event => event.seq >= fromSeq) }
   }
 
   list(): Promise<SessionHeader[]> {
@@ -126,7 +135,7 @@ function appendTraceEvents(session: Session): void {
     createUserMessage({
       content: [{ type: 'text', text: 'original' }], source: { kind: 'user' },
     }),
-    { surfaceOp: 'append', sourceEventSeqs: [2] },
+    { surfaceOp: 'append', sourceEventSeqs: [SessionSeq(2)] },
   )
   session.append(
     'assistant/message',
@@ -141,7 +150,10 @@ function appendTraceEvents(session: Session): void {
         },
       }),
     },
-    { surfaceOp: { op: 'replace', start: 3, end: 3 }, sourceEventSeqs: [3, 2] },
+    {
+      surfaceOp: { op: 'replace', start: SessionSeq(3), end: SessionSeq(3) },
+      sourceEventSeqs: [SessionSeq(3), SessionSeq(2)],
+    },
   )
   session.append(
     'user/message',
@@ -165,7 +177,10 @@ function appendTraceEvents(session: Session): void {
         },
       }),
     },
-    { surfaceOp: { op: 'replace', start: 4, end: 4 }, sourceEventSeqs: [2, 4] },
+    {
+      surfaceOp: { op: 'replace', start: SessionSeq(4), end: SessionSeq(4) },
+      sourceEventSeqs: [SessionSeq(2), SessionSeq(4)],
+    },
   )
 }
 
@@ -244,7 +259,7 @@ describe('session lineage tracing', () => {
 
   it('uses one cross-corpus observation and preserves persistence failure semantics', async () => {
     const durable = header('durable')
-    TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
+    TracePersistence.reset([{ meta: durable, events: [appendEvent(SessionSeq(0))] }])
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
@@ -288,7 +303,7 @@ describe('session event tracing', () => {
     const session = ctx.sessions.create(SessionId('trace'))
     appendTraceEvents(session)
 
-    const original = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 3 })
+    const original = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: SessionSeq(3) })
     expect(original.target).toMatchObject({
       sessionId: session.id,
       seq: 3,
@@ -302,7 +317,7 @@ describe('session event tracing', () => {
       sourceEventSeqs: [2],
       derivedEventSeqs: [4],
     })
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 4 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: SessionSeq(4) }))
       .resolves.toMatchObject({
         replacedBy: 8,
         replacementChain: [8],
@@ -310,14 +325,14 @@ describe('session event tracing', () => {
         sourceEventSeqs: [3, 2],
         derivedEventSeqs: [8],
       })
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 2 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: SessionSeq(2) }))
       .resolves.toMatchObject({
         target: { surface: 'log-only' },
         replacementChain: [],
         sourceEventSeqs: [],
         derivedEventSeqs: [3, 4, 8],
       })
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 8 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: SessionSeq(8) }))
       .resolves.toMatchObject({
         replacementChain: [],
         replacedEventSeqs: [4],
@@ -331,13 +346,13 @@ describe('session event tracing', () => {
     const session = ctx.sessions.create(SessionId('detached'))
     appendTraceEvents(session)
 
-    const first = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 4 })
+    const first = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: SessionSeq(4) })
     first.target.time = -1
-    first.replacementChain.push(99)
-    first.replacedEventSeqs.push(99)
-    first.sourceEventSeqs.push(99)
-    first.derivedEventSeqs.push(99)
-    const repeated = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 4 })
+    first.replacementChain.push(SessionSeq(99))
+    first.replacedEventSeqs.push(SessionSeq(99))
+    first.sourceEventSeqs.push(SessionSeq(99))
+    first.derivedEventSeqs.push(SessionSeq(99))
+    const repeated = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: SessionSeq(4) })
     expect(repeated.target.time).not.toBe(-1)
     expect(repeated.replacementChain).toEqual([8])
     expect(repeated.replacedEventSeqs).toEqual([3])
@@ -347,11 +362,11 @@ describe('session event tracing', () => {
 
   it('inspects persisted logs once, prefers live logs, and preserves failures and conflicts', async () => {
     const durable = header('shared', 1, { cwd: '/same' })
-    TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
+    TracePersistence.reset([{ meta: durable, events: [appendEvent(SessionSeq(0))] }])
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .resolves.toMatchObject({ target: { type: 'user/message', surface: 'current' } })
     expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1])
 
@@ -366,33 +381,33 @@ describe('session event tracing', () => {
     )
     TracePersistence.listFailure = new Error('list unavailable')
     TracePersistence.inspectFailure = new Error('inspect unavailable')
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 1 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(1) }))
       .resolves.toMatchObject({ target: { type: 'user/message' } })
     expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1])
 
-    TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
+    TracePersistence.reset([{ meta: durable, events: [appendEvent(SessionSeq(0))] }])
     const failedCtx = await queryContext()
     await failedCtx.plugin(TracePersistence)
     TracePersistence.listFailure = new Error('list unavailable')
-    await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
+    await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
     TracePersistence.listFailure = undefined
     TracePersistence.inspectFailure = new Error('inspect unavailable')
-    await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
+    await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
     TracePersistence.inspectFailure = undefined
     TracePersistence.afterList = () => {
       mutableHeader(TracePersistence.entries.get(durable.id)!.meta).cwd = '/changed'
     }
-    await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
+    await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
   })
 
   it('checks target existence before surface or source-event analysis', async () => {
     const bad = header('bad-target')
-    const malformed: SessionEvent[] = [appendEvent(0), {
+    const malformed: SessionEvent[] = [appendEvent(SessionSeq(0)), {
       type: 'assistant/message',
-      seq: 1,
+      seq: SessionSeq(1),
       time: 2,
       data: {
         turn: 1, step: 1,
@@ -405,16 +420,16 @@ describe('session event tracing', () => {
           },
         }),
       },
-      surfaceOp: { op: 'replace', start: 9, end: 9 },
+      surfaceOp: { op: 'replace', start: SessionSeq(9), end: SessionSeq(9) },
       sourceEventSeqs: [],
     }]
     TracePersistence.reset([{ meta: bad, events: malformed }])
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: bad.id, seq: 9 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: bad.id, seq: SessionSeq(9) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_EVENT_NOT_FOUND'))
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: bad.id, seq: 0 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: bad.id, seq: SessionSeq(0) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
   })
 
@@ -423,34 +438,34 @@ describe('session event tracing', () => {
       { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 }, sourceEventSeqs: [0] },
     ]],
     ['invalid source array', [
-      { ...appendEvent(0), sourceEventSeqs: 'invalid' },
+      { ...appendEvent(SessionSeq(0)), sourceEventSeqs: 'invalid' },
     ]],
     ['empty sources', [
-      appendEvent(0, []),
+      appendEvent(SessionSeq(0), []),
     ]],
     ['sparse sources', [
-      appendEvent(0, Array<number>(1)),
+      appendEvent(SessionSeq(0), Array<number>(1)),
     ]],
     ['duplicate sources', [
-      appendEvent(0),
-      appendEvent(1, [0, 0]),
+      appendEvent(SessionSeq(0)),
+      appendEvent(SessionSeq(1), [0, 0]),
     ]],
     ['missing earlier source', [
-      appendEvent(0),
-      appendEvent(1, [-1]),
+      appendEvent(SessionSeq(0)),
+      { ...appendEvent(SessionSeq(1)), sourceEventSeqs: [-1] } as unknown as SessionEvent,
     ]],
     ['future source', [
-      appendEvent(0, [1]),
-      appendEvent(1),
+      appendEvent(SessionSeq(0), [1]),
+      appendEvent(SessionSeq(1)),
     ]],
     ['replacement without sources', [
-      appendEvent(0),
-      { ...appendEvent(1), surfaceOp: { op: 'replace', start: 0, end: 0 } },
+      appendEvent(SessionSeq(0)),
+      { ...appendEvent(SessionSeq(1)), surfaceOp: { op: 'replace', start: 0, end: 0 } },
     ]],
     ['replacement missing a shadowed source', [
       { type: 'assistant/chunk', seq: 0, time: 1, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'draft' } } },
-      appendEvent(1),
-      { ...appendEvent(2, [0]), surfaceOp: { op: 'replace', start: 1, end: 1 } },
+      appendEvent(SessionSeq(1)),
+      { ...appendEvent(SessionSeq(2), [0]), surfaceOp: { op: 'replace', start: 1, end: 1 } },
     ]],
   ] as const)('rejects an invalid surface log: %s', async (_name, rawEvents) => {
     const durable = header('invalid-provenance')
@@ -459,7 +474,7 @@ describe('session event tracing', () => {
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
   })
 
@@ -476,13 +491,13 @@ describe('session event tracing', () => {
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
-    await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
+    await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
   })
 
   it('applies the same surface contract to listEvents', async () => {
     const durable = header('list-regression')
-    TracePersistence.reset([{ meta: durable, events: [appendEvent(0), appendEvent(1, [0, 0])] }])
+    TracePersistence.reset([{ meta: durable, events: [appendEvent(SessionSeq(0)), appendEvent(SessionSeq(1), [0, 0])] }])
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
diff --git a/packages/session-query/tool-session-query/src/operations.ts b/packages/session-query/tool-session-query/src/operations.ts
index 88107783cb..3d5fa17f31 100644
--- a/packages/session-query/tool-session-query/src/operations.ts
+++ b/packages/session-query/tool-session-query/src/operations.ts
@@ -6,6 +6,7 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { HarnessError } from '@deepseek-ai/dsh-llm'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import {
   SessionQueryError,
@@ -205,11 +206,12 @@ async function executeEventTrace(
   exec: ToolRunContext,
 ): Promise<string> {
   toolInput.assertNonNegativeSafeInteger('seq', args.seq)
+  const seq = SessionSeq(args.seq)
   const caller = workspaceAccess.callerOf(exec, ctx)
   const sessionId = workspaceAccess.targetId(args, caller)
   await workspaceAccess.authorizeTarget(ctx, caller, sessionId, exec.signal)
   const trace = await serviceBoundary.call(ctx, exec.signal, 'event trace', () =>
-    ctx.sessionQuery.traceEvent({ sessionId, seq: args.seq }, exec.signal))
+    ctx.sessionQuery.traceEvent({ sessionId, seq }, exec.signal))
   workspaceAccess.assertObservedTargetAuthorized(caller, sessionId, trace.session)
   const title = await workspaceAccess.readTitle(ctx, caller, sessionId, exec.signal)
   return presentation.formatEventTrace(sessionId, title, trace)
@@ -221,6 +223,7 @@ async function executeEventRead(
   exec: ToolRunContext,
 ): Promise<string> {
   toolInput.assertNonNegativeSafeInteger('seq', args.seq)
+  const seq = SessionSeq(args.seq)
   if (args.before !== undefined) toolInput.assertNonNegativeSafeInteger('before', args.before)
   if (args.after !== undefined) toolInput.assertNonNegativeSafeInteger('after', args.after)
   const caller = workspaceAccess.callerOf(exec, ctx)
@@ -229,7 +232,7 @@ async function executeEventRead(
   const window = await serviceBoundary.call(ctx, exec.signal, 'event read', () =>
     ctx.sessionQuery.readEvent({
       sessionId,
-      seq: args.seq,
+      seq,
       ...args.before === undefined ? {} : { before: args.before },
       ...args.after === undefined ? {} : { after: args.after },
     }, exec.signal))
diff --git a/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts b/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts
index 821b94c323..5e60ac5118 100644
--- a/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts
+++ b/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts
@@ -8,6 +8,7 @@ import { createUserMessage, ToolCallId  } from '@deepseek-ai/dsh-llm'
 import SessionStore, {
   SESSION_FORMAT_VERSION,
   SessionId,
+  SessionSeq,
   type Session,
 } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
@@ -57,10 +58,11 @@ describe('tool-session-query with the real SQLite provider', () => {
       id: persisted,
       createdAt: 1,
       cwd: '/work',
+      isSeeded: false,
     })
     await ctx.sessionPersistence.append(persisted, [{
       type: 'user/message',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 2,
       data: createUserMessage({
         content: [{ type: 'text', text: 'persisted integration needle' }],
@@ -129,11 +131,12 @@ describe('tool-session-query with the real SQLite provider', () => {
       id: persisted,
       createdAt: base,
       cwd: '/work',
+      isSeeded: false,
     })
     await ctx.sessionPersistence.append(persisted, [
       {
         type: 'user/message',
-        seq: 0,
+        seq: SessionSeq(0),
         time: base + 123,
         data: createUserMessage({
           content: [{ type: 'text', text: 'fractional integration needle' }],
@@ -143,7 +146,7 @@ describe('tool-session-query with the real SQLite provider', () => {
       },
       {
         type: 'user/message',
-        seq: 1,
+        seq: SessionSeq(1),
         time: base + 124,
         data: createUserMessage({
           content: [{ type: 'text', text: 'fractional integration needle' }],
@@ -153,7 +156,7 @@ describe('tool-session-query with the real SQLite provider', () => {
       },
       {
         type: 'user/message',
-        seq: 2,
+        seq: SessionSeq(2),
         time: -124,
         data: createUserMessage({
           content: [{ type: 'text', text: 'pre-epoch fractional needle' }],
@@ -163,7 +166,7 @@ describe('tool-session-query with the real SQLite provider', () => {
       },
       {
         type: 'user/message',
-        seq: 3,
+        seq: SessionSeq(3),
         time: -123,
         data: createUserMessage({
           content: [{ type: 'text', text: 'pre-epoch fractional needle' }],
diff --git a/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts b/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
index eaa4ce7cfe..f79c5a1b2e 100644
--- a/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
+++ b/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
@@ -7,6 +7,7 @@ import * as TimeoutPolicy from '@deepseek-ai/dsh-tool-call-timeout-policy'
 import SessionStore, {
   SESSION_FORMAT_VERSION,
   SessionId,
+  SessionSeq,
   type Session,
   type SessionEvent,
   type SessionHeader,
@@ -45,6 +46,7 @@ function header(id: string, cwd: string | undefined, createdAt = 1, parentSessio
     version: SESSION_FORMAT_VERSION,
     id: SessionId(id),
     createdAt,
+    isSeeded: false,
     ...cwd === undefined ? {} : { cwd },
     ...parentSession === undefined ? {} : { parentSession },
   }
@@ -94,7 +96,7 @@ function sessionHit(
     persisted: false,
     bestMatch: {
       sessionId: SessionId(id),
-      seq: 4,
+      seq: SessionSeq(4),
       type: 'assistant/message',
       time: 200,
       surface: 'current',
@@ -103,7 +105,7 @@ function sessionHit(
   }
 }
 
-function eventHit(sessionId: SessionIdValue, seq: number, text = 'needle excerpt'): SessionEventSearchHit {
+function eventHit(sessionId: SessionIdValue, seq: SessionSeq, text = 'needle excerpt'): SessionEventSearchHit {
   return {
     sessionId,
     seq,
@@ -182,7 +184,7 @@ class FakeQuery extends SessionQueryEngine {
             title: value,
             messageSeqs: [],
             source: { kind: 'fallback' },
-            eventSeq: 0,
+            eventSeq: SessionSeq(0),
             updatedAt: 1,
           },
         },
@@ -1154,7 +1156,7 @@ describe('workspace authority and lineage redaction', () => {
 
     FakeQuery.eventSearch = () => Promise.resolve({
       session: movedHeader,
-      items: [eventHit(target.id, 0, 'secret event hit')],
+      items: [eventHit(target.id, SessionSeq(0), 'secret event hit')],
     })
     const search = await mounted.call('session_event_search', {
       session_id: target.id,
@@ -1171,7 +1173,7 @@ describe('workspace authority and lineage redaction', () => {
     expect(errorCode(await mounted.call('session_trace', { session_id: target.id })))
       .toBe('SESSION_QUERY_TOOL_UNAUTHORIZED')
 
-    const eventTrace = await mounted.ctx.sessionQuery.traceEvent({ sessionId: target.id, seq: 0 })
+    const eventTrace = await mounted.ctx.sessionQuery.traceEvent({ sessionId: target.id, seq: SessionSeq(0) })
     vi.spyOn(mounted.ctx.sessionQuery, 'traceEvent').mockResolvedValueOnce({
       ...eventTrace,
       session: movedHeader,
@@ -1179,7 +1181,7 @@ describe('workspace authority and lineage redaction', () => {
     expect(errorCode(await mounted.call('session_event_trace', { session_id: target.id, seq: 0 })))
       .toBe('SESSION_QUERY_TOOL_UNAUTHORIZED')
 
-    const eventWindow = await mounted.ctx.sessionQuery.readEvent({ sessionId: target.id, seq: 0 })
+    const eventWindow = await mounted.ctx.sessionQuery.readEvent({ sessionId: target.id, seq: SessionSeq(0) })
     vi.spyOn(mounted.ctx.sessionQuery, 'readEvent').mockResolvedValueOnce({
       ...eventWindow,
       session: movedHeader,
@@ -1199,7 +1201,7 @@ describe('workspace authority and lineage redaction', () => {
           title: 'secret moved title',
           messageSeqs: [],
           source: { kind: 'fallback' },
-          eventSeq: 0,
+          eventSeq: SessionSeq(0),
           updatedAt: 1,
         },
       },
@@ -1583,7 +1585,7 @@ describe('search paging, prior-history bounds, titles, and cancellation', () =>
     const mounted = await mount()
     FakeQuery.eventSearch = request => Promise.resolve({
       session: header(request.sessionId, '/work'),
-      items: [eventHit(request.sessionId, 1)],
+      items: [eventHit(request.sessionId, SessionSeq(1))],
     })
     await mounted.call('session_event_search', {
       query: 'prior',
@@ -1628,12 +1630,12 @@ describe('search paging, prior-history bounds, titles, and cancellation', () =>
     FakeQuery.eventSearch = request => request.cursor === undefined
       ? Promise.resolve({
         session: header(other.id, '/work'),
-        items: [eventHit(other.id, 1)],
+        items: [eventHit(other.id, SessionSeq(1))],
         nextCursor: cursor,
       })
       : Promise.resolve({
         session: header(other.id, '/work'),
-        items: [eventHit(other.id, 2), eventHit(other.id, 3)],
+        items: [eventHit(other.id, SessionSeq(2)), eventHit(other.id, SessionSeq(3))],
       })
     const result = await mounted.call('session_event_search', {
       session_id: other.id,
@@ -2003,7 +2005,10 @@ describe('trace and exact read rendering', () => {
           },
         }),
       },
-      { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] },
+      {
+        surfaceOp: { op: 'replace', start: SessionSeq(0), end: SessionSeq(0) },
+        sourceEventSeqs: [SessionSeq(0)],
+      },
     )
     const result = await mounted.call('session_event_trace', { session_id: session.id, seq: 0 })
     expect(text(result)).toContain('Replacement chain: 1')
diff --git a/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts b/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
index 64b1c3cf3c..670d410ee3 100644
--- a/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
+++ b/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
@@ -4,8 +4,8 @@ import Loader from '@deepseek-ai/cordis-plugin-loader'
 import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import LlmRuntime, { ToolCallId, type GenerateOptions, LlmAdapter, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
-import SessionPersistence from '@deepseek-ai/dsh-session-persistence'
+import type { SessionEvent, SessionHeader, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import SessionPersistence, { type SessionEventSuffix, type SessionInspection } from '@deepseek-ai/dsh-session-persistence'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime, { TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
 import * as checkpointPolicy from '../src/index.ts'
@@ -18,16 +18,16 @@ class TestPersistence extends SessionPersistence {
   locate(_meta: SessionHeader): undefined { return undefined }
   create(_meta: SessionHeader): Promise<void> { return Promise.resolve() }
   append(_id: SessionId, _events: readonly SessionEvent[]): Promise<void> { return Promise.resolve() }
-  load(_id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  load(_id: SessionId): Promise<SessionInspection> {
     return Promise.reject(new Error('not used'))
   }
-  inspect(_id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  inspect(_id: SessionId): Promise<SessionInspection> {
     return Promise.reject(new Error('not used'))
   }
   borrowSession(_id: SessionId, _signal?: AbortSignal): ReturnType<SessionPersistence['borrowSession']> {
     return Promise.reject(new Error('not used'))
   }
-  readFrom(_id: SessionId, _fromSeq: number): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  readFrom(_id: SessionId, _fromSeq: SessionLogOffset): Promise<SessionEventSuffix> {
     return Promise.reject(new Error('not used'))
   }
   list(): Promise<SessionHeader[]> { return Promise.resolve([]) }
diff --git a/packages/session/session-log-deepseek/README.i18n.yaml b/packages/session/session-log-deepseek/README.i18n.yaml
index 444c646041..06cd142858 100644
--- a/packages/session/session-log-deepseek/README.i18n.yaml
+++ b/packages/session/session-log-deepseek/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/session/session-log-deepseek/README.md
-README.md: e76a4ba7d48deafb13f5dfcc1e7ea6532a4452d7
-README.zh.md: f2bf91418430fee960350fa0feb6053704dad543
+README.md: b08b2d3cde78e7a3cf7050e90ff57655ad70d409
+README.zh.md: 0ee216c6c69178695eb629b2a81faef73103b13d
diff --git a/packages/session/session-log-deepseek/README.md b/packages/session/session-log-deepseek/README.md
index e76a4ba7d4..b08b2d3cde 100644
--- a/packages/session/session-log-deepseek/README.md
+++ b/packages/session/session-log-deepseek/README.md
@@ -34,7 +34,7 @@ Shipped profiles mount the plugin so an overlay can enable it, but the default c
 <a id="request-field"></a>
 ## Request field
 
-For a request carrying a live `sessionId`, the plugin folds the greatest accepted watermark for that exact Session identity, snapshots `Session.events`, and sends the contiguous suffix after the watermark. A process-local fold scans each event once and consumes later appends incrementally; restart and HMR rebuild it from the durable log. The version-1 field contains the immutable `SessionHeader`, `afterSeq`, `throughSeq`, and every complete canonical `SessionEvent` in that range as a direct array element. Forked sessions ignore inherited parent watermarks because each watermark records the Session id sent on the accepted request.
+For a request carrying a live `sessionId`, the plugin folds the greatest accepted watermark for that exact Session identity, snapshots `Session.events`, and sends the contiguous suffix after the watermark. A process-local fold scans each event once and consumes later appends incrementally; restart and HMR rebuild it from the durable log. The version-1 field contains a v0-compatible raw session header (`seedLength` is present only for a seeded Session), numeric `afterSeq` and `throughSeq`, and every complete canonical event translated to raw-number envelope fields. Forked sessions ignore inherited parent watermarks because each watermark records the Session id sent on the accepted request.
 
 <a id="acceptance-and-retry"></a>
 ## Acceptance and retry
diff --git a/packages/session/session-log-deepseek/README.zh.md b/packages/session/session-log-deepseek/README.zh.md
index f2bf914184..0ee216c6c6 100644
--- a/packages/session/session-log-deepseek/README.zh.md
+++ b/packages/session/session-log-deepseek/README.zh.md
@@ -34,7 +34,7 @@ kind: "package-reference"
 <a id="request-field"></a>
 ## 请求字段
 
-对于携带存活 `sessionId` 的请求，插件会折叠该确切会话身份的最大已接受水位，对 `Session.events` 取快照，并发送水位之后的连续后缀。进程内 fold 会让每条事件只被扫描一次并增量消费后续追加；重启与 HMR 会从持久日志重建它。版本 1 字段包含不可变的 `SessionHeader`、`afterSeq`、`throughSeq`，以及作为数组直接元素的该范围内每个完整权威 `SessionEvent`。每个水位都会记录已接受请求发送的会话 id，因此 fork 会话会忽略从父会话继承的水位。
+对于携带存活 `sessionId` 的请求，插件会折叠该确切会话身份的最大已接受水位，对 `Session.events` 取快照，并发送水位之后的连续后缀。进程内 fold 会让每条事件只被扫描一次并增量消费后续追加；重启与 HMR 会从持久日志重建它。版本 1 字段包含兼容 v0 的原始会话 header（仅 seeded Session 携带 `seedLength`）、数值型 `afterSeq` 与 `throughSeq`，以及把完整权威事件翻译为原始数值 envelope 字段后的数组元素。每个水位都会记录已接受请求发送的会话 id，因此 fork 会话会忽略从父会话继承的水位。
 
 <a id="acceptance-and-retry"></a>
 ## 接受与重试
diff --git a/packages/session/session-log-deepseek/package.json b/packages/session/session-log-deepseek/package.json
index b557ba69f1..4746305509 100644
--- a/packages/session/session-log-deepseek/package.json
+++ b/packages/session/session-log-deepseek/package.json
@@ -38,6 +38,7 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-util-values": "workspace:^",
     "@deepseek-ai/schemastery": "workspace:^"
   },
   "peerDependencies": {
diff --git a/packages/session/session-log-deepseek/src/index.ts b/packages/session/session-log-deepseek/src/index.ts
index b56e0225a1..5fde932581 100644
--- a/packages/session/session-log-deepseek/src/index.ts
+++ b/packages/session/session-log-deepseek/src/index.ts
@@ -9,8 +9,21 @@ import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { brandString } from '@deepseek-ai/dsh-brand'
 import type {} from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
-import type { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type { DeepSeekSessionLogExtension } from './types.ts'
+import { isSurfaceEvent, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionId,
+  SessionLogOffset as SessionLogOffsetType,
+  SessionSeq as SessionSeqType,
+  SessionSeqCursor,
+} from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import type {
+  DeepSeekSessionLogExtension,
+  DeepSeekSessionLogWireEvent,
+  DeepSeekSessionLogWireHeader,
+} from './types.ts'
 
 export type * from './types.ts'
 
@@ -31,35 +44,77 @@ export const Config: z<Config> = z.object({
 })
 
 interface AcceptanceFold {
-  readonly scannedEvents: number
-  readonly throughSeq: number
+  readonly scannedEvents: SessionLogOffsetType
+  readonly throughSeq: SessionSeqCursor
 }
 
 const acceptanceFolds = new WeakMap<Session, AcceptanceFold>()
 
+/** Translate logical Session metadata back to the stable version-0 wire header. */
+function wireHeader(session: Session): DeepSeekSessionLogWireHeader {
+  const header = session.header
+  return {
+    version: header.version,
+    id: String(header.id),
+    createdAt: header.createdAt,
+    ...header.cwd === undefined ? {} : { cwd: header.cwd },
+    ...header.parentSession === undefined ? {} : { parentSession: String(header.parentSession) },
+    ...header.isSeeded ? { seedLength: Number(session.inheritedEventCount) } : {},
+    ...header.origin === undefined ? {} : { origin: header.origin },
+    ...header.delegationDepth === undefined ? {} : { delegationDepth: header.delegationDepth },
+    ...header.agentPreset === undefined ? {} : { agentPreset: header.agentPreset },
+  }
+}
+
+/** Translate compile-time sequence brands to raw numeric request fields. */
+function wireEvent(event: SessionEvent): DeepSeekSessionLogWireEvent {
+  const surfaceEvent = isSurfaceEvent(event) ? event : undefined
+  const surfaceOp = surfaceEvent?.surfaceOp
+  return {
+    type: event.type,
+    seq: Number(event.seq),
+    time: event.time,
+    data: event.data as JsonValue,
+    ...event.ignorable === undefined ? {} : { ignorable: event.ignorable },
+    ...surfaceEvent?.sourceEventSeqs === undefined
+      ? {}
+      : { sourceEventSeqs: surfaceEvent.sourceEventSeqs.map(Number) },
+    ...surfaceOp === undefined
+      ? {}
+      : surfaceOp === 'append'
+        ? { surfaceOp }
+        : { surfaceOp: { op: 'replace' as const, start: Number(surfaceOp.start), end: Number(surfaceOp.end) } },
+  }
+}
+
 /**
  * Highest confirmed sequence for this exact session identity.
  * @param session - canonical log whose matching acceptance events are folded.
  * @returns greatest accepted sequence, or `-1` before any accepted request.
  */
-export function acceptedThrough(session: Session): number {
+export function acceptedThrough(session: Session): SessionSeqCursor {
   const previous = acceptanceFolds.get(session)
   let throughSeq = previous?.throughSeq ?? -1
   const length = session.seq
-  const start = previous?.scannedEvents ?? 0
+  const start = previous?.scannedEvents ?? SessionLogOffset(0)
   for (let index = start; index < length; index++) {
-    const event = session.eventAt(index)
+    const event = session.eventAt(SessionSeq(index))
     if (event === undefined) {
       throw new Error(`session-log-deepseek: missing event ${String(index)} below captured length ${String(length)}`)
     }
     if (event.type !== 'session-log-deepseek/delivery-accepted') continue
+    let acceptedSeq: SessionSeqType
+    try {
+      acceptedSeq = SessionSeq(event.data.throughSeq)
+    } catch {
+      throw new Error(`session-log-deepseek: malformed acceptance watermark at seq ${event.seq}`)
+    }
     if (typeof event.data.sessionId !== 'string' || event.data.sessionId.length === 0
-      || !Number.isSafeInteger(event.data.throughSeq) || event.data.throughSeq < 0
-      || event.data.throughSeq >= event.seq) {
+      || acceptedSeq >= event.seq) {
       throw new Error(`session-log-deepseek: malformed acceptance watermark at seq ${event.seq}`)
     }
     if (event.data.sessionId !== session.id) continue
-    throughSeq = Math.max(throughSeq, event.data.throughSeq)
+    if (acceptedSeq > throughSeq) throughSeq = acceptedSeq
   }
   acceptanceFolds.set(session, { scannedEvents: length, throughSeq })
   return throughSeq
@@ -80,15 +135,16 @@ export function apply(ctx: Context, config: Config): void {
       if (session === undefined) return undefined
 
       const afterSeq = acceptedThrough(session)
-      const throughSeq = session.seq - 1
-      if (throughSeq < 0) return undefined
-      const suffix = session.snapshotEvents(afterSeq + 1)
+      const snapshot = session.snapshotEvents()
+      const throughSeq = snapshot.at(-1)?.seq
+      if (throughSeq === undefined) return undefined
+      const suffix = session.snapshotEvents(SessionLogOffset(afterSeq + 1))
       const value: DeepSeekSessionLogExtension = {
         version: 1,
-        session: session.header,
-        afterSeq,
-        throughSeq,
-        events: suffix,
+        session: wireHeader(session),
+        afterSeq: Number(afterSeq),
+        throughSeq: Number(throughSeq),
+        events: suffix.map(wireEvent),
       }
       return {
         value,
diff --git a/packages/session/session-log-deepseek/src/invariant.ts b/packages/session/session-log-deepseek/src/invariant.ts
index b7c2c848f9..66a309322b 100644
--- a/packages/session/session-log-deepseek/src/invariant.ts
+++ b/packages/session/session-log-deepseek/src/invariant.ts
@@ -1,6 +1,7 @@
 /** Package-owned invariants for DeepSeek session-log acceptance watermarks. */
 
 import type { Context } from '@deepseek-ai/cordis'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 import type {} from './types.ts'
@@ -16,12 +17,17 @@ export const inject = ['invariants']
 function validateDeliveryAccepted(session: Session, event: SessionEvent<'session-log-deepseek/delivery-accepted'>, fail: InvariantFailure): void {
   const { sessionId, throughSeq } = event.data
   const inherited = session.header.parentSession !== undefined
-    && session.header.seedLength !== undefined
-    && event.seq < session.header.seedLength
+    && !session.isOwnSeq(event.seq)
   if (sessionId !== session.id && !inherited) {
     fail('a non-inherited session-log-deepseek/delivery-accepted event must name its containing session')
   }
-  if (!Number.isSafeInteger(throughSeq) || throughSeq < 0 || throughSeq >= event.seq) {
+  let acceptedSeq: ReturnType<typeof SessionSeq>
+  try {
+    acceptedSeq = SessionSeq(throughSeq)
+  } catch {
+    fail(`session-log-deepseek/delivery-accepted throughSeq must identify an earlier event, got ${throughSeq} at seq ${event.seq}`)
+  }
+  if (acceptedSeq >= event.seq) {
     fail(`session-log-deepseek/delivery-accepted throughSeq must identify an earlier event, got ${throughSeq} at seq ${event.seq}`)
   }
 }
diff --git a/packages/session/session-log-deepseek/src/types.ts b/packages/session/session-log-deepseek/src/types.ts
index d3281bf327..3205880a44 100644
--- a/packages/session/session-log-deepseek/src/types.ts
+++ b/packages/session/session-log-deepseek/src/types.ts
@@ -1,17 +1,48 @@
 /** Wire types for lossless incremental DeepSeek session-log upload. */
 
-import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+
+/** Version-0 Session header fields serialized on the external request wire. */
+export interface DeepSeekSessionLogWireHeader {
+  readonly version: number
+  readonly id: string
+  readonly createdAt: number
+  readonly cwd?: string
+  readonly parentSession?: string
+  /** Exact inherited prefix length; absent for an unseeded Session. */
+  readonly seedLength?: number
+  readonly origin?: 'subagent'
+  readonly delegationDepth?: number
+  readonly agentPreset?: string
+}
+
+/** Raw-number surface mutation serialized on the external request wire. */
+export type DeepSeekSessionLogWireSurfaceOp =
+  | 'append'
+  | { readonly op: 'replace'; readonly start: number; readonly end: number }
+
+/** One complete canonical event translated to raw JSON primitives for upload. */
+export interface DeepSeekSessionLogWireEvent {
+  readonly type: SessionEvent['type']
+  readonly seq: number
+  readonly time: number
+  readonly data: JsonValue
+  readonly ignorable?: true
+  readonly sourceEventSeqs?: readonly number[]
+  readonly surfaceOp?: DeepSeekSessionLogWireSurfaceOp
+}
 
 /** Versioned incremental session-log field carried by an official DeepSeek request. */
 export interface DeepSeekSessionLogExtension {
   readonly version: 1
-  readonly session: SessionHeader
+  readonly session: DeepSeekSessionLogWireHeader
   /** Highest sequence durably recorded as accepted before this request, or `-1`. */
   readonly afterSeq: number
   /** Highest sequence represented by {@link events}. */
   readonly throughSeq: number
   /** Complete canonical event envelopes for every sequence from `afterSeq + 1` through `throughSeq`. */
-  readonly events: readonly SessionEvent[]
+  readonly events: readonly DeepSeekSessionLogWireEvent[]
 }
 
 declare module '@deepseek-ai/dsh-deepseek-llm-api-extensions/types' {
@@ -27,7 +58,7 @@ declare module '@deepseek-ai/dsh-session/types' {
       /** Session identity the accepted delivery carried; inherited fork markers retain the parent's id. */
       sessionId: import('@deepseek-ai/dsh-session/types').SessionId
       /** Last canonical event included in the accepted request. */
-      throughSeq: number
+      throughSeq: import('@deepseek-ai/dsh-session/types').SessionSeq
     }
   }
 }
diff --git a/packages/session/session-log-deepseek/tests/invariant.spec.ts b/packages/session/session-log-deepseek/tests/invariant.spec.ts
index f39c4aec45..e9f2f9d3d7 100644
--- a/packages/session/session-log-deepseek/tests/invariant.spec.ts
+++ b/packages/session/session-log-deepseek/tests/invariant.spec.ts
@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import InvariantRegistry, { InvariantError } from '@deepseek-ai/dsh-invariants'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import * as SessionLogInvariant from '../src/invariant.ts'
 import type {} from '../src/types.ts'
 
@@ -25,7 +25,7 @@ describe('DeepSeek session-log acceptance invariant', () => {
     const ctx = await setup()
     const session = ctx.sessions.create(SessionId('valid'))
     session.append('turn/start', { turn: 1 })
-    expect(() => session.append('session-log-deepseek/delivery-accepted', { sessionId: session.id, throughSeq: 0 }))
+    expect(() => session.append('session-log-deepseek/delivery-accepted', { sessionId: session.id, throughSeq: SessionSeq(0) }))
       .not.toThrow()
   })
 
@@ -35,7 +35,7 @@ describe('DeepSeek session-log acceptance invariant', () => {
     wrongId.append('turn/start', { turn: 1 })
     expect(() => wrongId.append('session-log-deepseek/delivery-accepted', {
       sessionId: SessionId('other'),
-      throughSeq: 0,
+      throughSeq: SessionSeq(0),
     })).toThrow(expect.objectContaining<Partial<InvariantError>>({
       code: 'INVARIANT',
       packageName: '@deepseek-ai/dsh-session-log-deepseek',
@@ -45,7 +45,14 @@ describe('DeepSeek session-log acceptance invariant', () => {
     wrongSeq.append('turn/start', { turn: 1 })
     expect(() => wrongSeq.append('session-log-deepseek/delivery-accepted', {
       sessionId: wrongSeq.id,
-      throughSeq: 1,
+      throughSeq: SessionSeq(1),
+    })).toThrow(expect.objectContaining<Partial<InvariantError>>({
+      code: 'INVARIANT',
+      packageName: '@deepseek-ai/dsh-session-log-deepseek',
+    }))
+    expect(() => wrongSeq.append('session-log-deepseek/delivery-accepted', {
+      sessionId: wrongSeq.id,
+      throughSeq: -1 as never,
     })).toThrow(expect.objectContaining<Partial<InvariantError>>({
       code: 'INVARIANT',
       packageName: '@deepseek-ai/dsh-session-log-deepseek',
@@ -59,8 +66,13 @@ describe('DeepSeek session-log acceptance invariant', () => {
     await ctx.plugin(InvariantRegistry, { enabled: true })
     const id = SessionId('late-invalid')
     ctx.sessions.create(id, { seed: [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'session-log-deepseek/delivery-accepted', seq: 1, time: 2, data: { sessionId: id, throughSeq: 1 } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      {
+        type: 'session-log-deepseek/delivery-accepted',
+        seq: SessionSeq(1),
+        time: 2,
+        data: { sessionId: id, throughSeq: SessionSeq(1) },
+      },
     ] })
 
     let failure: unknown
@@ -84,10 +96,16 @@ describe('DeepSeek session-log acceptance invariant', () => {
     const childId = SessionId('fork-child')
     ctx.sessions.create(childId, {
       seed: [
-        { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-        { type: 'session-log-deepseek/delivery-accepted', seq: 1, time: 2, data: { sessionId: parentId, throughSeq: 0 } },
+        { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+        {
+          type: 'session-log-deepseek/delivery-accepted',
+          seq: SessionSeq(1),
+          time: 2,
+          data: { sessionId: parentId, throughSeq: SessionSeq(0) },
+        },
       ],
-      meta: { parentSession: parentId, seedLength: 2 },
+      inheritedEventCount: SessionLogOffset(2),
+      meta: { parentSession: parentId, isSeeded: true },
     })
 
     await expect(ctx.plugin(SessionLogInvariant)).resolves.toBeDefined()
diff --git a/packages/session/session-log-deepseek/tests/upload.spec.ts b/packages/session/session-log-deepseek/tests/upload.spec.ts
index 38526420e0..a3663867f1 100644
--- a/packages/session/session-log-deepseek/tests/upload.spec.ts
+++ b/packages/session/session-log-deepseek/tests/upload.spec.ts
@@ -1,8 +1,11 @@
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, expectTypeOf, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { Session, SessionId, type CreateSessionOptions, type SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionLogOffset, SessionSeq, type CreateSessionOptions, type SessionEvent } from '@deepseek-ai/dsh-session'
 import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import * as SessionLogDeepSeek from '../src/index.ts'
+import type { DeepSeekSessionLogExtension } from '../src/types.ts'
 
 const contexts: Context[] = []
 const SIGNAL = new AbortController().signal
@@ -11,7 +14,11 @@ afterEach(async () => {
   await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
 })
 
-async function harness(id: string, seed?: readonly SessionEvent[], meta?: CreateSessionOptions['meta']): Promise<{
+async function harness(
+  id: string,
+  seed?: readonly SessionEvent[],
+  creation?: Omit<CreateSessionOptions, 'seed'>,
+): Promise<{
   ctx: Context
   session: Session
   disposeUpload: () => Promise<void>
@@ -24,7 +31,7 @@ async function harness(id: string, seed?: readonly SessionEvent[], meta?: Create
   await upload
   const options = seed === undefined
     ? undefined
-    : { seed, ...meta === undefined ? {} : { meta } }
+    : { seed, ...creation }
   const session = ctx.sessions.create(SessionId(id), options)
   return { ctx, session, disposeUpload: () => upload.dispose() }
 }
@@ -34,6 +41,15 @@ function body(text = 'x'.repeat(300)) {
 }
 
 describe('incremental DeepSeek session-log upload', () => {
+  it('publishes raw numeric sequence fields on its external wire DTO', () => {
+    expectTypeOf<DeepSeekSessionLogExtension['afterSeq']>().toEqualTypeOf<number>()
+    expectTypeOf<DeepSeekSessionLogExtension['throughSeq']>().toEqualTypeOf<number>()
+    expectTypeOf<DeepSeekSessionLogExtension['events'][number]['seq']>().toEqualTypeOf<number>()
+    expectTypeOf<DeepSeekSessionLogExtension['events'][number]['data']>().toEqualTypeOf<JsonValue>()
+    expectTypeOf<DeepSeekSessionLogExtension['session']['seedLength']>()
+      .toEqualTypeOf<number | undefined>()
+  })
+
   it('does not contribute the session log under its default configuration', async () => {
     const ctx = new Context()
     contexts.push(ctx)
@@ -85,7 +101,10 @@ describe('incremental DeepSeek session-log upload', () => {
     })
     expect(resumedPayload.fields.dsh_session_log?.afterSeq).toBe(0)
 
-    const fork = await harness('child', seed, { parentSession: first.session.id, seedLength: seed.length })
+    const fork = await harness('child', seed, {
+      inheritedEventCount: SessionLogOffset(seed.length),
+      meta: { parentSession: first.session.id, isSeeded: true },
+    })
     expect(SessionLogDeepSeek.acceptedThrough(fork.session)).toBe(-1)
     const forkPayload = await fork.ctx.deepseekLlmApiExtensions.prepare({ body: body(), signal: SIGNAL, sessionId: fork.session.id })
     expect(forkPayload.fields.dsh_session_log).toMatchObject({ afterSeq: -1, throughSeq: fork.session.seq - 1 })
@@ -106,8 +125,13 @@ describe('incremental DeepSeek session-log upload', () => {
   it('folds only events appended after the cached acceptance scan', () => {
     const id = SessionId('incremental-fold')
     const events: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'session-log-deepseek/delivery-accepted', seq: 1, time: 2, data: { sessionId: id, throughSeq: 0 } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      {
+        type: 'session-log-deepseek/delivery-accepted',
+        seq: SessionSeq(1),
+        time: 2,
+        data: { sessionId: id, throughSeq: SessionSeq(0) },
+      },
     ]
     let reads = 0
     const session = {
@@ -126,8 +150,13 @@ describe('incremental DeepSeek session-log upload', () => {
     expect(reads).toBe(0)
 
     events.push(
-      { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
-      { type: 'session-log-deepseek/delivery-accepted', seq: 3, time: 4, data: { sessionId: id, throughSeq: 2 } },
+      { type: 'step/start', seq: SessionSeq(2), time: 3, data: { turn: 1, step: 1 } },
+      {
+        type: 'session-log-deepseek/delivery-accepted',
+        seq: SessionSeq(3),
+        time: 4,
+        data: { sessionId: id, throughSeq: SessionSeq(2) },
+      },
     )
     expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(2)
     expect(reads).toBe(2)
@@ -170,15 +199,88 @@ describe('incremental DeepSeek session-log upload', () => {
     expect(prepared.fields.dsh_session_log?.events).toEqual(session.snapshotEvents())
   })
 
-  it('fails closed on a malformed persisted acceptance watermark', async () => {
-    const malformed = [{
-      type: 'session-log-deepseek/delivery-accepted',
+  it('translates logical brands and isSeeded into the raw v0 upload DTO', async () => {
+    const firstMessage = createUserMessage({
+      content: [{ type: 'text', text: 'first' }],
+      source: { kind: 'user' },
+    })
+    const replacementMessage = createUserMessage({
+      content: [{ type: 'text', text: 'replacement' }],
+      source: { kind: 'user' },
+    })
+    const seed = [
+      {
+        type: 'user/message',
+        seq: SessionSeq(0),
+        time: 1,
+        data: firstMessage,
+        ignorable: true,
+        surfaceOp: 'append',
+      },
+      {
+        type: 'user/message',
+        seq: SessionSeq(1),
+        time: 2,
+        data: replacementMessage,
+        sourceEventSeqs: [SessionSeq(0)],
+        surfaceOp: { op: 'replace', start: SessionSeq(0), end: SessionSeq(0) },
+      },
+    ] satisfies SessionEvent[]
+    const { ctx, session } = await harness('wire-child', seed, {
+      inheritedEventCount: SessionLogOffset(0),
+      meta: {
+        cwd: '/wire-workspace',
+        parentSession: SessionId('wire-parent'),
+        isSeeded: true,
+        origin: 'subagent',
+        delegationDepth: 1,
+        agentPreset: 'minimal',
+      },
+    })
+
+    const prepared = await ctx.deepseekLlmApiExtensions.prepare({
+      body: body(), signal: SIGNAL, sessionId: session.id,
+    })
+    const wire = JSON.parse(JSON.stringify(prepared.fields.dsh_session_log)) as Record<string, unknown>
+    expect(wire.session).toMatchObject({
+      version: 0,
+      id: 'wire-child',
+      parentSession: 'wire-parent',
+      cwd: '/wire-workspace',
+      seedLength: 0,
+      origin: 'subagent',
+      delegationDepth: 1,
+      agentPreset: 'minimal',
+    })
+    expect(wire.session).not.toHaveProperty('isSeeded')
+    expect(typeof wire.afterSeq).toBe('number')
+    expect(typeof wire.throughSeq).toBe('number')
+    expect(Array.isArray(wire.events)).toBe(true)
+    const events = Array.isArray(wire.events) ? wire.events : []
+    expect(events[0]).toMatchObject({
       seq: 0,
-      time: 1,
-      data: { sessionId: 'malformed', throughSeq: 0 },
-    }] as unknown as SessionEvent[]
-    const session = Session.create(SessionId('malformed'), malformed)
-    expect(() => SessionLogDeepSeek.acceptedThrough(session)).toThrow(/malformed acceptance watermark/)
+      ignorable: true,
+      surfaceOp: 'append',
+    })
+    expect(events[0]).not.toHaveProperty('sourceEventSeqs')
+    expect(events[1]).toMatchObject({
+      seq: 1,
+      sourceEventSeqs: [0],
+      surfaceOp: { op: 'replace', start: 0, end: 0 },
+    })
+  })
+
+  it('fails closed on a malformed persisted acceptance watermark', async () => {
+    for (const [id, throughSeq] of [['current', 0], ['negative', -1]] as const) {
+      const malformed = [{
+        type: 'session-log-deepseek/delivery-accepted',
+        seq: 0,
+        time: 1,
+        data: { sessionId: `malformed-${id}`, throughSeq },
+      }] as unknown as SessionEvent[]
+      const session = Session.create(SessionId(`malformed-${id}`), malformed)
+      expect(() => SessionLogDeepSeek.acceptedThrough(session)).toThrow(/malformed acceptance watermark/)
+    }
   })
 
   it('withdraws its request field when the contributing plugin reloads', async () => {
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index c2f2bba957..0a44d29f0c 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/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/session/session-persistence-jsonl/README.md
-README.md: 6d61130522a928cbbbfeef90cb6bd63e968c5b92
-README.zh.md: 90c91f49a8c2ff67336cd2eac4477a6823ab6d31
+README.md: d3dfaf8affb142979ede69d86bbf0b1587e8c39c
+README.zh.md: 15fc815523355674a1f325b604dd2655f56f7f58
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index 6d61130522..d3dfaf8aff 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -54,7 +54,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 ### On-disk layout
 
-Each session gets a session-owned directory under a readable project directory; the first logical line of the log is the immutable `SessionHeader`, followed by one storage record per logical event (or one packed chunk row per eligible run). Storage records use the lossless provenance representation described below:
+Each session gets a session-owned directory under a readable project directory; the first logical line is the private v0 physical header, followed by one storage record per logical event (or one packed chunk row per eligible run). Its optional numeric `seedLength` remains byte-compatible: absence decodes to `SessionHeader.isSeeded: false`, while zero or a positive value decodes to `isSeeded: true` plus the exact `inheritedEventCount`. Storage records use the lossless provenance representation described below:
 
 ```text
 <root>/
@@ -72,7 +72,7 @@ A session is materialized lazily: `create(meta)` writes nothing, and the first `
 
 ### Reading the logs
 
-`inspect(id)` returns an immutable balanced view without committing recovery. `readFrom(id, fromSeq)` returns stored events at or past a sequence number for watermark consumers; sequential media like JSONL parse the whole artifact and skip forward. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
+`inspect(id)` returns an immutable balanced view with its exact inherited cut without committing recovery. `readFrom(id, fromOffset)` accepts a `SessionLogOffset`, returns stored events at or past that offset, and retains the same cut beside the suffix; sequential media like JSONL parse the whole artifact and skip forward. Header-only listing exposes `isSeeded` without reading event bodies. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
 -----
 
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 90c91f49a8..15fc815523 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -54,7 +54,7 @@ kind: "package-reference"
 
 ### 磁盘布局
 
-每个会话在可读项目目录下获得一个会话自有目录；日志第一个逻辑行是不可变 `SessionHeader`，之后每个逻辑事件一条存储记录（或每个符合条件的连续段一条打包分片行）。存储记录使用下文所述的无损来源序列表示：
+每个会话在可读项目目录下获得一个会话自有目录；第一个逻辑行是私有 v0 物理 header，之后每个逻辑事件一条存储记录（或每个符合条件的连续段一条打包分片行）。其可选数字 `seedLength` 保持字节兼容：缺席解码为 `SessionHeader.isSeeded: false`，零或正值解码为 `isSeeded: true` 加精确 `inheritedEventCount`。存储记录使用下文所述的无损来源序列表示：
 
 ```text
 <root>/
@@ -72,7 +72,7 @@ kind: "package-reference"
 
 ### 读取日志
 
-`inspect(id)` 返回不可变的平衡视图，不提交恢复。`readFrom(id, fromSeq)` 为水位消费方返回该序列号及之后的已存储事件；JSONL 这类顺序介质解析整个产物并向前跳过。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
+`inspect(id)` 返回带精确继承切点的不可变平衡视图，不提交恢复。`readFrom(id, fromOffset)` 接受 `SessionLogOffset`，返回该偏移及之后的已存储事件，并在后缀旁保留同一切点；JSONL 这类顺序介质解析整个产物并向前跳过。仅 header 的列表读取不读事件正文即可公开 `isSeeded`。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
 -----
 
diff --git a/packages/session/session-persistence-jsonl/src/format.ts b/packages/session/session-persistence-jsonl/src/format.ts
index 9f1ca0d4f4..29431963ec 100644
--- a/packages/session/session-persistence-jsonl/src/format.ts
+++ b/packages/session/session-persistence-jsonl/src/format.ts
@@ -11,9 +11,20 @@
 import { join } from 'node:path'
 import {
   decodeSeqRanges, decodeStorageRecord, encodeSeqRanges, packChunkRuns, SESSION_FORMAT_VERSION,
+  SessionLogOffset,
 } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionHeader, SessionId, StorageRecord } from '@deepseek-ai/dsh-session'
-import { SessionFormatUnsupportedError, sessionFormatVersionRefusal } from '@deepseek-ai/dsh-session-persistence'
+import type {
+  SessionEvent,
+  SessionHeader,
+  SessionId,
+  SessionLogOffset as SessionLogOffsetType,
+  StorageRecord,
+} from '@deepseek-ai/dsh-session'
+import {
+  SessionFormatUnsupportedError,
+  sessionFormatVersionRefusal,
+  type SessionStorageMetadata,
+} from '@deepseek-ai/dsh-session-persistence'
 
 /** Physical encoding selected for JSONL session artifacts. */
 export type JsonlCompression = 'zstd' | 'none'
@@ -28,11 +39,11 @@ export function logSuffix(compression: JsonlCompression): '.jsonl.zstd' | '.json
 }
 
 /**
- * The first JSONL record of a session artifact: the immutable
- * {@link SessionHeader} tagged as a `session` record so a reader can tell it
- * apart from an event line.
+ * The private version-0 physical header stored as the first JSONL record.
+ * Its optional numeric `seedLength` translates to logical lineage metadata
+ * plus a separately carried exact inherited cut.
  */
-export interface HeaderLine {
+interface HeaderLine {
   type: 'session'
   version: number
   id: SessionId
@@ -48,9 +59,21 @@ export interface HeaderLine {
 /**
  * Build the header line object from a {@link SessionHeader}.
  * @param header - the immutable session metadata to serialize.
+ * @param inheritedEventCount - exact inherited prefix length; required for a
+ * seeded header and omitted only for an unseeded header.
  * @returns the `type: 'session'`-tagged line object, absent optional fields omitted (never null).
  */
-export function toHeaderLine(header: SessionHeader): HeaderLine {
+export function toHeaderLine(
+  header: SessionHeader,
+  inheritedEventCount?: SessionLogOffsetType,
+): HeaderLine {
+  if (header.isSeeded && inheritedEventCount === undefined) {
+    throw new Error('seeded session header requires an inherited event count')
+  }
+  const cut = SessionLogOffset(inheritedEventCount ?? 0)
+  if (!header.isSeeded && cut !== 0) {
+    throw new Error('unseeded session header inherited event count must be 0')
+  }
   return {
     type: 'session',
     version: header.version,
@@ -58,7 +81,7 @@ export function toHeaderLine(header: SessionHeader): HeaderLine {
     createdAt: header.createdAt,
     ...header.cwd !== undefined ? { cwd: header.cwd } : {},
     ...header.parentSession !== undefined ? { parentSession: header.parentSession } : {},
-    ...header.seedLength !== undefined ? { seedLength: header.seedLength } : {},
+    ...header.isSeeded ? { seedLength: cut } : {},
     ...header.origin !== undefined ? { origin: header.origin } : {},
     delegationDepth: header.delegationDepth ?? 0,
     ...header.agentPreset !== undefined ? { agentPreset: header.agentPreset } : {},
@@ -66,24 +89,27 @@ export function toHeaderLine(header: SessionHeader): HeaderLine {
 }
 
 /**
- * Parse a header line back into a {@link SessionHeader}.
+ * Translate one version-0 physical header into logical metadata and its cut.
  * @param line - the shape-checked first line of a log (see the `isHeaderLine` guard).
- * @returns the header, absent optional fields omitted.
+ * @returns logical Session metadata paired with the exact inherited prefix length.
  */
-export function fromHeaderLine(line: HeaderLine): SessionHeader {
+function fromHeaderLine(line: HeaderLine): SessionStorageMetadata {
   if (Object.hasOwn(line, 'sandboxMode') || Object.hasOwn(line, 'approvalPolicy')) {
     throw new Error('session header uses retired policy baseline fields')
   }
   return {
-    version: line.version,
-    id: line.id,
-    createdAt: line.createdAt,
-    ...line.cwd !== undefined ? { cwd: line.cwd } : {},
-    ...line.parentSession !== undefined ? { parentSession: line.parentSession } : {},
-    ...line.seedLength !== undefined ? { seedLength: line.seedLength } : {},
-    ...line.origin !== undefined ? { origin: line.origin } : {},
-    delegationDepth: line.delegationDepth,
-    ...line.agentPreset !== undefined ? { agentPreset: line.agentPreset } : {},
+    meta: {
+      version: line.version,
+      id: line.id,
+      createdAt: line.createdAt,
+      ...line.cwd !== undefined ? { cwd: line.cwd } : {},
+      ...line.parentSession !== undefined ? { parentSession: line.parentSession } : {},
+      isSeeded: line.seedLength !== undefined,
+      ...line.origin !== undefined ? { origin: line.origin } : {},
+      delegationDepth: line.delegationDepth,
+      ...line.agentPreset !== undefined ? { agentPreset: line.agentPreset } : {},
+    },
+    inheritedEventCount: SessionLogOffset(line.seedLength ?? 0),
   }
 }
 
@@ -102,6 +128,11 @@ function isHeaderLine(value: unknown): value is HeaderLine {
     && Number.isSafeInteger((value as { delegationDepth: number }).delegationDepth)
     && (value as { delegationDepth: number }).delegationDepth >= 0
     && !Object.is((value as { delegationDepth: number }).delegationDepth, -0)
+    && ((value as { seedLength?: unknown }).seedLength === undefined
+      || (typeof (value as { seedLength?: unknown }).seedLength === 'number'
+        && Number.isSafeInteger((value as { seedLength: number }).seedLength)
+        && (value as { seedLength: number }).seedLength >= 0
+        && !Object.is((value as { seedLength: number }).seedLength, -0)))
     && ((value as { origin?: unknown }).origin === undefined
       || (value as { origin?: unknown }).origin === 'subagent')
     && ((value as { agentPreset?: unknown }).agentPreset === undefined
@@ -231,7 +262,7 @@ export function eventLines(events: readonly SessionEvent[], packChunks: boolean)
  * stays verbatim.
  * @param record - one stored record (event or packed row).
  * @returns the record with its provenance in storage form (widened from the
- *   in-memory `number[]`; {@link expandProvenanceFromStorage} restores it).
+ *   in-memory `SessionSeq[]`; {@link expandProvenanceFromStorage} restores it).
  */
 function encodeProvenanceForStorage(record: StorageRecord): unknown {
   if (!('sourceEventSeqs' in record)) return record
@@ -239,7 +270,7 @@ function encodeProvenanceForStorage(record: StorageRecord): unknown {
 }
 
 /**
- * Expand a parsed line's storage-form provenance back to `number[]`.
+ * Expand a parsed line's storage-form provenance back to `SessionSeq[]`.
  * @param parsed - the JSON-parsed value of one stored line.
  * @returns the value with provenance expanded.
  * @throws when the record or its storage-form provenance is malformed.
@@ -258,6 +289,7 @@ function expandProvenanceFromStorage(parsed: unknown): unknown {
 
 interface SessionLogScan {
   meta: SessionHeader
+  inheritedEventCount: SessionLogOffsetType
   events: SessionEvent[]
   committedBytes: number
 }
@@ -279,7 +311,7 @@ function refuseForeignFormatVersion(parsed: unknown): void {
   )
 }
 
-function parseHeaderRecord(record: Buffer): SessionHeader {
+function parseHeaderRecord(record: Buffer): ReturnType<typeof fromHeaderLine> {
   if (record.length === 0 || record.at(-1) !== 0x0A || record.indexOf(0x0A) !== record.length - 1) {
     throw new Error('empty or header-less session log')
   }
@@ -304,6 +336,7 @@ function parseHeaderRecord(record: Buffer): SessionHeader {
  */
 export class SessionLogScanner {
   private readonly meta: SessionHeader
+  private readonly inheritedEventCount: SessionLogOffsetType
   private readonly events: SessionEvent[] = []
   private fragments: Buffer[] = []
   private fragmentBytes = 0
@@ -318,7 +351,9 @@ export class SessionLogScanner {
    * @param headerRecord - the complete first JSONL record, including its newline.
    */
   constructor(headerRecord: Buffer) {
-    this.meta = parseHeaderRecord(headerRecord)
+    const parsed = parseHeaderRecord(headerRecord)
+    this.meta = parsed.meta
+    this.inheritedEventCount = parsed.inheritedEventCount
     this.inputBytes = headerRecord.length
     this.committedBytes = headerRecord.length
   }
@@ -359,11 +394,15 @@ export class SessionLogScanner {
    * Snapshot progress before appending a recoverable torn-frame prefix.
    * @returns byte, committed-prefix, and expanded-event cursors.
    */
-  checkpoint(): { inputBytes: number; committedBytes: number; eventCount: number } {
+  checkpoint(): {
+    inputBytes: number
+    committedBytes: number
+    eventCount: SessionLogOffsetType
+  } {
     return {
       inputBytes: this.inputBytes,
       committedBytes: this.committedBytes,
-      eventCount: this.events.length,
+      eventCount: SessionLogOffset(this.events.length),
     }
   }
 
@@ -373,7 +412,12 @@ export class SessionLogScanner {
    */
   finish(): SessionLogScan {
     this.finished = true
-    return { meta: this.meta, events: this.events, committedBytes: this.committedBytes }
+    return {
+      meta: this.meta,
+      inheritedEventCount: this.inheritedEventCount,
+      events: this.events,
+      committedBytes: this.committedBytes,
+    }
   }
 
   /** Decode one complete event row and update the contiguous prefix. */
@@ -427,20 +471,28 @@ export function scanLog(buffer: Buffer): SessionLogScan {
 }
 
 /**
- * Parse just the header line of a log into a {@link SessionHeader}, or
- * `undefined` if it is missing/not a header. Used by `list()` to read session
- * metadata WITHOUT parsing the whole log: a session picker scales with the
- * number of sessions, not the total size of every conversation.
+ * Parse just the header line of a log into logical metadata plus its exact
+ * inherited cut, or `undefined` if it is missing/not a header.
  * @param firstLine - the first line of a log file (without its trailing newline).
- * @returns the parsed header, or `undefined` when the line is not a well-formed session header.
+ * @returns parsed storage metadata, or `undefined` for a malformed header.
  */
-export function parseHeaderMeta(firstLine: string): SessionHeader | undefined {
+export function parseHeader(firstLine: string): SessionStorageMetadata | undefined {
   let parsed: unknown
   try {
     parsed = JSON.parse(firstLine)
   } catch {
     return undefined
   }
+  refuseForeignFormatVersion(parsed)
   if (!isHeaderLine(parsed)) return undefined
   return fromHeaderLine(parsed)
 }
+
+/**
+ * Parse only the logical header fields needed by lightweight listing.
+ * @param firstLine - first JSONL line without its trailing newline.
+ * @returns the logical Session header, or `undefined` for a malformed line.
+ */
+export function parseHeaderMeta(firstLine: string): SessionHeader | undefined {
+  return parseHeader(firstLine)?.meta
+}
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 111af6dc08..8ccebf0be0 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -19,13 +19,21 @@ import {
   SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator, SessionFormatUnsupportedError,
   type BorrowedSessionSource,
   type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
-  type SessionInspection,
+  type SessionEventSuffix, type SessionInspection,
   type SessionPersistenceRevision as PersistenceRevision, type SessionRawArtifact,
+  type SessionStorageMetadata,
   type StoredPrefix,
 } from '@deepseek-ai/dsh-session-persistence'
-import type { Session, SessionEvent, SessionId, SessionHeader, SessionPreparation } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionId,
+  SessionHeader,
+  SessionLogOffset,
+  SessionPreparation,
+} from '@deepseek-ai/dsh-session'
 import {
-  encodeSegment, eventLines, logPath, logSuffix, parseHeaderMeta, projectDir, scanLog, sessionDir,
+  encodeSegment, eventLines, logPath, logSuffix, parseHeader, parseHeaderMeta, projectDir, scanLog, sessionDir,
   SessionLogScanner, toHeaderLine,
   type JsonlCompression,
 } from './format.ts'
@@ -175,8 +183,8 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
     return { kind: 'jsonl', path: logPath(this.root, meta.cwd, meta.id, this.compression) }
   }
 
-  create(meta: SessionHeader): Promise<void> {
-    return this.coordinator.create(meta)
+  create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void> {
+    return this.coordinator.create(meta, inheritedEventCount)
   }
 
   override ensureMaterialized(session: Session): Promise<void> {
@@ -205,7 +213,7 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
 
   // JSONL is sequential media: no loadStoredFrom hook, so the coordinator
   // parses the stored prefix (both encodings) and skips forward to fromSeq.
-  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix> {
     return this.coordinator.readFrom(id, fromSeq, signal)
   }
 
@@ -282,13 +290,13 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
     } else {
       content = buffer.toString('utf8')
     }
-    const meta = parseHeaderMeta(content.split('\n', 1)[0] as string)
-    if (meta === undefined || meta.id !== id) {
+    const storage = parseHeader(content.split('\n', 1)[0] as string)
+    if (storage === undefined || storage.meta.id !== id) {
       throw new Error(`corrupt session log: invalid header line in "${path}"`)
     }
     // The logical artifact name is `session.jsonl` regardless of the physical
     // encoding suffix (`.jsonl.zstd` marks compression only).
-    return { meta, filename: 'session.jsonl', content }
+    return { ...storage, filename: 'session.jsonl', content }
   }
 
   /**
@@ -329,10 +337,11 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
         prefix = await this.readZstdPrefix(buffer, signal)
       } else {
         signal?.throwIfAborted()
-        const { meta, events, committedBytes } = scanLog(buffer)
+        const { meta, inheritedEventCount, events, committedBytes } = scanLog(buffer)
         signal?.throwIfAborted()
         prefix = {
           meta,
+          inheritedEventCount,
           events,
           ...committedBytes < buffer.byteLength
             ? { tornMarker: { truncateTo: committedBytes, recoveredEvents: [] } }
@@ -394,7 +403,11 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
       }
       if (tornStart === undefined) {
         const prefix = scanner.finish()
-        return { meta: prefix.meta, events: prefix.events }
+        return {
+          meta: prefix.meta,
+          inheritedEventCount: prefix.inheritedEventCount,
+          events: prefix.events,
+        }
       }
 
       let recoveredPlaintext: Buffer = Buffer.alloc(0)
@@ -413,6 +426,7 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
       signal?.throwIfAborted()
       return {
         meta: recoveredPrefix.meta,
+        inheritedEventCount: recoveredPrefix.inheritedEventCount,
         events: recoveredPrefix.events,
         tornMarker: {
           truncateTo: tornStart,
@@ -429,18 +443,22 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
   }
 
   /** Durably append a batch, lazily materializing the file when not yet present. */
-  async appendBatch(meta: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void> {
+  async appendBatch(
+    storage: SessionStorageMetadata,
+    events: readonly SessionEvent[],
+    isMaterialized: boolean,
+  ): Promise<void> {
     await this.ensureRootEncoding()
     if (isMaterialized) {
-      await this.appendLines(meta, events)
+      await this.appendLines(storage.meta, events)
     } else {
-      await this.materialize(meta, events)
+      await this.materialize(storage, events)
     }
   }
 
   /** Materialize a header-only JSONL artifact for an explicitly durable empty session. */
-  async materializeHeader(meta: SessionHeader): Promise<void> {
-    await this.materialize(meta, [])
+  async materializeHeader(storage: SessionStorageMetadata): Promise<void> {
+    await this.materialize(storage, [])
   }
 
   /**
@@ -449,10 +467,11 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
    * does not require this to be atomic.
    */
   async commitRepair(
-    meta: SessionHeader,
+    storage: SessionStorageMetadata,
     tornMarker: JsonlTornMarker | undefined,
     closers: readonly SessionEvent[],
   ): Promise<void> {
+    const { meta } = storage
     if (tornMarker !== undefined) await this.repair(meta, tornMarker.truncateTo)
     const repairedEvents = [...(tornMarker?.recoveredEvents ?? []), ...closers]
     if (repairedEvents.length > 0) await this.appendLines(meta, repairedEvents)
@@ -527,12 +546,13 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
   // --- materialization / append / repair (file mechanics) ---
 
   /** Atomically write the header line + first batch (temp-write, fsync, publish). */
-  private async materialize(meta: SessionHeader, events: readonly SessionEvent[]): Promise<void> {
+  private async materialize(storage: SessionStorageMetadata, events: readonly SessionEvent[]): Promise<void> {
+    const { meta } = storage
     const project = projectDir(this.root, meta.cwd)
     const dir = sessionDir(this.root, meta.cwd, meta.id)
     const finalPath = logPath(this.root, meta.cwd, meta.id, this.compression)
     await this.rejectOppositeArtifact(meta.cwd, meta.id)
-    const content = await this.encodeMaterialization(meta, events)
+    const content = await this.encodeMaterialization(storage, events)
     /* v8 ignore next -- native Windows coverage exercises this platform dispatch; Linux covers the POSIX peer */
     if (process.platform === 'win32') {
       await this.materializeWin32(project, dir, finalPath, meta.id, content)
@@ -632,8 +652,11 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
   }
 
   /** Encode the header and first batch without combining their frame boundaries. */
-  private async encodeMaterialization(meta: SessionHeader, events: readonly SessionEvent[]): Promise<Buffer | string> {
-    const header = JSON.stringify(toHeaderLine(meta)) + '\n'
+  private async encodeMaterialization(
+    storage: SessionStorageMetadata,
+    events: readonly SessionEvent[],
+  ): Promise<Buffer | string> {
+    const header = JSON.stringify(toHeaderLine(storage.meta, storage.inheritedEventCount)) + '\n'
     if (events.length === 0) {
       return this.compression === 'none' ? header : compressZstdFrame(header)
     }
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index e08e2c628c..363ec28212 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -4,11 +4,12 @@ import { Context } from '@deepseek-ai/cordis'
 import { appendFile, mkdtemp, mkdir, rm, readFile, writeFile, readdir, stat, symlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import {
-  encodeSegment, eventLines, logPath, projectDir, projectKey, scanLog, sessionDir, SessionLogScanner, toHeaderLine,
+  encodeSegment, eventLines, logPath, parseHeader, projectDir, projectKey, scanLog, sessionDir, SessionLogScanner,
+  toHeaderLine,
 } from '../src/format.ts'
 import { runPersistenceContract, meta, oneTurnLog, appendLog } from '../../session-persistence/tests/contract.ts'
 import { runCoordinatorContract, type CoordinatorFixture } from '../../session-persistence/tests/coordinator-contract.ts'
@@ -133,6 +134,48 @@ runCoordinatorContract('jsonl-none', async (): Promise<CoordinatorFixture> => {
 })
 
 describe('JsonlSessionPersistence: format helpers', () => {
+  it.each([
+    ['absent', undefined, false, 0],
+    ['zero', 0, true, 0],
+    ['nonzero', 3, true, 3],
+  ] as const)('round-trips the v0 physical seedLength when it is %s', (
+    _case,
+    seedLength,
+    isSeeded,
+    inheritedEventCount,
+  ) => {
+    const line = {
+      type: 'session',
+      version: 0,
+      id: SessionId(`physical-seed-${_case}`),
+      createdAt: 1000,
+      ...seedLength === undefined ? {} : { seedLength },
+      delegationDepth: 0,
+    }
+    const bytes = `${JSON.stringify(line)}\n`
+
+    const scanned = scanLog(Buffer.from(bytes))
+
+    expect(scanned.meta.isSeeded).toBe(isSeeded)
+    expect(scanned.inheritedEventCount).toBe(SessionLogOffset(inheritedEventCount))
+    expect(`${JSON.stringify(toHeaderLine(scanned.meta, scanned.inheritedEventCount))}\n`).toBe(bytes)
+  })
+
+  it('requires logical lineage and the physical inherited cut to agree', () => {
+    const unseeded = meta('lineage-cut')
+    expect(() => toHeaderLine({ ...unseeded, isSeeded: true }))
+      .toThrow('seeded session header requires an inherited event count')
+    expect(() => toHeaderLine(unseeded, SessionLogOffset(1)))
+      .toThrow('unseeded session header inherited event count must be 0')
+  })
+
+  it('round-trips the subagent origin and rejects other physical values', () => {
+    const line = toHeaderLine({ ...meta('subagent-origin'), origin: 'subagent' })
+    expect(scanLog(Buffer.from(`${JSON.stringify(line)}\n`)).meta.origin).toBe('subagent')
+    expect(() => scanLog(Buffer.from(`${JSON.stringify({ ...line, origin: 'worker' })}\n`)))
+      .toThrow(/session header/)
+  })
+
   it('encodeSegment neutralizes traversal, separators, and absolute paths', () => {
     expect(encodeSegment('..')).toBe('~002E~002E')
     expect(encodeSegment('.')).toBe('~002E')
@@ -239,6 +282,11 @@ describe('JsonlSessionPersistence: format helpers', () => {
     await fiber.dispose()
   })
 
+  it('refuses a foreign version on the header-only read path', () => {
+    expect(() => parseHeader(JSON.stringify({ version: 42, id: 'future', futureOnly: true })))
+      .toThrow(expect.objectContaining({ name: 'SessionFormatUnsupportedError' }))
+  })
+
   it('points a format refusal at the raw log path', async () => {
     const absoluteRoot = await freshRoot()
     const ctx = new Context()
@@ -247,8 +295,8 @@ describe('JsonlSessionPersistence: format helpers', () => {
     const m = { ...meta('newer-format', '/work'), version: 7 }
     await ctx.sessionPersistence.create(m)
     await ctx.sessionPersistence.append(m.id, [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
     ])
     const failure = await ctx.sessionPersistence.load(m.id).then(() => undefined, (error: unknown) => error as Error)
     expect(failure?.name).toBe('SessionFormatUnsupportedError')
@@ -286,6 +334,25 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
     expect((await ctx.sessionPersistence.list()).map(h => h.id)).toContain(m.id)
   })
 
+  it('lists a seeded header without reading an event body', async () => {
+    const id = SessionId('header-only-seeded')
+    const path = rawLogPath(root, '/work', id)
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(path, `${JSON.stringify({
+      type: 'session',
+      version: 0,
+      id,
+      createdAt: 1000,
+      cwd: '/work',
+      seedLength: 0,
+      delegationDepth: 0,
+    })}\n{not-valid-json`)
+
+    await expect(ctx.sessionPersistence.list()).resolves.toEqual([
+      expect.objectContaining({ id, isSeeded: true }),
+    ])
+  })
+
   it('materializes an explicitly durable empty live session without an event row', async () => {
     const id = SessionId('durable-empty')
     const session = ctx.sessions.create(id, { meta: { cwd: '/work' } })
@@ -293,7 +360,11 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
     await ctx.sessionPersistence.ensureMaterialized(session)
 
     expect(await readFile(rawLogPath(root, '/work', id), 'utf8')).toBe(`${JSON.stringify(toHeaderLine(session.header))}\n`)
-    await expect(ctx.sessionPersistence.load(id)).resolves.toEqual({ meta: session.header, events: [] })
+    await expect(ctx.sessionPersistence.load(id)).resolves.toEqual({
+      meta: session.header,
+      inheritedEventCount: SessionLogOffset(0),
+      events: [],
+    })
   })
 
   it('delegates direct preparation through the JSONL provider', async () => {
@@ -370,11 +441,11 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
   it('round-trip is byte-identical (incl. assistant/chunk verbatim)', async () => {
     const m = meta('chunks')
     const log: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
-      { type: 'assistant/chunk', seq: 2, time: 3, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'he' } } },
-      { type: 'assistant/chunk', seq: 3, time: 4, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'llo' } } },
-      { type: 'assistant/message', seq: 4, time: 5, data: {
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'step/start', seq: SessionSeq(1), time: 2, data: { turn: 1, step: 1 } },
+      { type: 'assistant/chunk', seq: SessionSeq(2), time: 3, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'he' } } },
+      { type: 'assistant/chunk', seq: SessionSeq(3), time: 4, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'llo' } } },
+      { type: 'assistant/message', seq: SessionSeq(4), time: 5, data: {
         turn: 1, step: 1,
         message: createMessage({
           role: 'assistant',
@@ -384,9 +455,9 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
             ...{ provider: 'mock', model: 'mock' },
           },
         }),
-      }, surfaceOp: 'append', sourceEventSeqs: [2, 3] },
-      { type: 'step/end', seq: 5, time: 6, data: { turn: 1, step: 1 } },
-      { type: 'turn/end', seq: 6, time: 7, data: { turn: 1, reason: { kind: 'completed' } } },
+      }, surfaceOp: 'append', sourceEventSeqs: [SessionSeq(2), SessionSeq(3)] },
+      { type: 'step/end', seq: SessionSeq(5), time: 6, data: { turn: 1, step: 1 } },
+      { type: 'turn/end', seq: SessionSeq(6), time: 7, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
     await ctx.sessionPersistence.create(m)
     await ctx.sessionPersistence.append(m.id, log)
@@ -598,7 +669,12 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
       id: SessionId('persist-child'),
       cwd: '/workspace',
       parentSession: SessionId('persist-parent'),
-      seedLength: source.snapshotEvents().length,
+      isSeeded: true,
+    })
+    expect(loaded.inheritedEventCount).toBe(source.seq)
+    await expect(ctx.sessionPersistence.readRaw(child.id)).resolves.toMatchObject({
+      meta: { isSeeded: true },
+      inheritedEventCount: source.seq,
     })
   })
 
@@ -754,7 +830,7 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
     await ctx.sessionPersistence.create(a)
     await ctx.sessionPersistence.append(a.id, [{
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
     }])
@@ -782,7 +858,7 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
 
   it('path-traversal session ids are neutralized (no escape from root)', async () => {
     const evil = SessionId('../../etc/pwn')
-    const m = { version: 0, id: evil, createdAt: 1 }
+    const m = { version: 0, id: evil, createdAt: 1, isSeeded: false }
     await ctx.sessionPersistence.create(m)
     await ctx.sessionPersistence.append(evil, oneTurnLog())
     // The file lives UNDER root, not at ../../etc.
@@ -952,6 +1028,7 @@ describe('JsonlSessionPersistence: scanLog unit', () => {
       version: 0,
       id: SessionId('composed'),
       createdAt: 1,
+      isSeeded: false,
       delegationDepth: 0,
       agentPreset: 'minimal',
     })
@@ -1055,15 +1132,15 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
   function chunkRunLog(): SessionEvent[] {
     const deltas: SessionEvent[] = Array.from({ length: 5 }, (_, k) => ({
       type: 'assistant/chunk',
-      seq: 2 + k,
+      seq: SessionSeq(2 + k),
       time: 3 + k,
       data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: `t${k}` } },
     }))
     return [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'step/start', seq: SessionSeq(1), time: 2, data: { turn: 1, step: 1 } },
       ...deltas,
-      { type: 'assistant/message', seq: 7, time: 8, data: {
+      { type: 'assistant/message', seq: SessionSeq(7), time: 8, data: {
         turn: 1, step: 1,
         message: createMessage({
           role: 'assistant',
@@ -1073,9 +1150,9 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
             ...{ provider: 'mock', model: 'mock' },
           },
         }),
-      }, surfaceOp: 'append', sourceEventSeqs: [2, 3, 4, 5, 6] },
-      { type: 'step/end', seq: 8, time: 9, data: { turn: 1, step: 1 } },
-      { type: 'turn/end', seq: 9, time: 10, data: { turn: 1, reason: { kind: 'completed' } } },
+      }, surfaceOp: 'append', sourceEventSeqs: [2, 3, 4, 5, 6].map(SessionSeq) },
+      { type: 'step/end', seq: SessionSeq(8), time: 9, data: { turn: 1, step: 1 } },
+      { type: 'turn/end', seq: SessionSeq(9), time: 10, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
   }
 
diff --git a/packages/session/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
index 27ab56540a..9d311d2b39 100644
--- a/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
@@ -5,7 +5,7 @@ import type { FileHandle } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { performance } from 'node:perf_hooks'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { logPath, scanLog, sessionDir, toHeaderLine, type JsonlCompression } from '../src/format.ts'
@@ -332,6 +332,22 @@ describe('Zstandard frame structure', () => {
 })
 
 describe('JsonlSessionPersistence: default Zstandard encoding', () => {
+  it('lists seeded metadata from the header frame without decoding the event body', async () => {
+    const root = await freshRoot()
+    const ctx = await mount(root)
+    const header = { ...meta('zstd-header-only-seeded', '/work'), isSeeded: true }
+    const path = logPath(root, '/work', header.id, 'zstd')
+    await mkdir(sessionDir(root, '/work', header.id), { recursive: true })
+    const headerFrame = await compressZstdFrame(
+      `${JSON.stringify(toHeaderLine(header, SessionLogOffset(0)))}\n`,
+    )
+    await writeFile(path, Buffer.concat([headerFrame, Buffer.from('invalid event frame')]))
+
+    await expect(ctx.sessionPersistence.list()).resolves.toEqual([
+      expect.objectContaining({ id: header.id, isSeeded: true }),
+    ])
+  })
+
   it('materializes an explicitly durable empty session as one header frame', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
@@ -342,7 +358,11 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
     const buffer = await readFile(logPath(root, '/work', session.id, 'zstd'))
     expect(scanZstdFrames(buffer).frames).toHaveLength(1)
     expect((await decodeCompleteFrames(buffer)).toString()).toBe(`${JSON.stringify(toHeaderLine(session.header))}\n`)
-    await expect(ctx.sessionPersistence.load(session.id)).resolves.toEqual({ meta: session.header, events: [] })
+    await expect(ctx.sessionPersistence.load(session.id)).resolves.toEqual({
+      meta: session.header,
+      inheritedEventCount: 0,
+      events: [],
+    })
   })
 
   it('writes .jsonl.zstd by default with one header frame and one first-batch frame', async () => {
@@ -423,13 +443,13 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       ...base.slice(0, 3),
       ...Array.from({ length: 3 }, (_, index): SessionEvent => ({
         type: 'assistant/chunk',
-        seq: 3 + index,
+        seq: SessionSeq(3 + index),
         time: 4 + index,
         data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: `part-${index}` } },
       })),
       ...base.slice(3).map((event): SessionEvent => ({
         ...event,
-        seq: event.seq + 3,
+        seq: SessionSeq(event.seq + 3),
         time: event.time + 3,
       })),
     ]
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index 6e5028bf57..6cb47067fa 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/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/session/session-persistence/README.md
-README.md: 7165590fec9c1f017cf97786fbef61f5fb294a45
-README.zh.md: 007a59c6159835b31143a3a2cb7e0f4caf1f2674
+README.md: 6d430173b985d7e32b615e0b42713a925bc8b344
+README.zh.md: a3b6cd90fa4ccba2b28f0e81517bbabab0ce047e
diff --git a/packages/session/session-persistence/README.md b/packages/session/session-persistence/README.md
index 7165590fec..6d430173b9 100644
--- a/packages/session/session-persistence/README.md
+++ b/packages/session/session-persistence/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-session-persistence` stores a session's event log durably, reloads it on resume, and lists stored sessions through the backend-neutral `ctx.sessionPersistence` service. The persisted unit is the existing `SessionEvent` log — there is no parallel stored message type — and non-replayable metadata (format version, working directory, lineage, seed boundary) travels separately as `SessionHeader`. A backend owns its storage, while the service owns append-only logs, contiguous sequence numbers, crash recovery that preserves an interrupted turn instead of truncating it, and durable writes that resolve only after the batch is safe. The shipped JSONL provider implements this service with one artifact per Session; third-party providers may implement the same contract without changing the loop or model.
+`dsh-session-persistence` stores a session's event log durably, reloads it on resume, and lists stored sessions through the backend-neutral `ctx.sessionPersistence` service. The persisted unit is the existing `SessionEvent` log — there is no parallel stored message type. `SessionHeader.isSeeded` makes lineage visible to lightweight listing, while the exact `inheritedEventCount` accompanies every body-bearing storage read and prepared Session. A backend owns its storage, while the service owns append-only logs, contiguous sequence numbers, crash recovery that preserves an interrupted turn instead of truncating it, and durable writes that resolve only after the batch is safe. The shipped JSONL provider implements this service with one artifact per Session; third-party providers may implement the same contract without changing the loop or model.
 
 ## Table of Contents
 
@@ -36,18 +36,18 @@ The seam ships the [JSONL](../session-persistence-jsonl/README.md) backend. It s
 With a backend mounted, you can store a session's events durably, reload the stored log, and list what is stored:
 
 ```text
-await ctx.sessionPersistence.create(meta)                  // register a session
+await ctx.sessionPersistence.create(meta, inheritedEventCount) // cut required when meta.isSeeded
 await ctx.sessionPersistence.ensureMaterialized(session)   // persist an empty resumable session
 await ctx.sessionPersistence.append(id, events)            // durably persist a batch
-const { meta, events } = await ctx.sessionPersistence.load(id)   // reload on resume
+const { meta, inheritedEventCount, events } = await ctx.sessionPersistence.load(id)
 const headers = await ctx.sessionPersistence.list()        // every stored session
 ```
 
-`append` resolves only after the batch is durable, so a resolved write survives an OS crash or power loss. Ordinary `create` remains lazy; a lifecycle frontend calls `ensureMaterialized` only when an empty session must itself appear in durable listing without inventing an event. `load` returns an immutable balanced log and commits any needed crash recovery; `inspect` reads the same view without committing recovery. Consumers that resume from a watermark can read only the events at or past a sequence number, and a session's artifact location (`locate`) resolves without filesystem I/O.
+`append` resolves only after the batch is durable, so a resolved write survives an OS crash or power loss. Ordinary `create(meta, inheritedEventCount)` remains lazy; `meta.isSeeded: true` requires the sibling exact cut, while unseeded metadata may omit it and rejects a nonzero value. The first materializing batch for a seeded session must reach the complete inherited prefix, so storage never exposes metadata whose cut exceeds its log. A lifecycle frontend calls `ensureMaterialized` only when an empty session must itself appear in durable listing without inventing an event. `load` returns an immutable balanced log and commits any needed crash recovery; `inspect` reads the same complete view without committing recovery. `readFrom` accepts a `SessionLogOffset` and returns a detached `SessionEventSuffix` carrying that `fromSeq`, the unchanged inherited cut, and only stored events at or after the cut. A session's artifact location (`locate`) resolves without filesystem I/O.
 
 ### Resuming and crash recovery
 
-Resume is `load` plus session preparation: the stored log comes back with its header lineage intact, so a resumed agent sees the same history and composition. A session that crashed mid-turn reloads with its interrupted final turn preserved and balanced: `load` appends synthetic `tool/result` and `turn/end {interrupted}` closers for unanswered calls instead of dropping the events — a single turn can be large, and those events were durably written before the crash. Only a never-fully-written torn tail fragment is discarded.
+Resume is `load` plus session preparation: the stored log comes back with its header lineage and exact inherited cut intact, so ownership checks do not infer the cut from a marker or the full restore length. A session that crashed mid-turn reloads with its interrupted final turn preserved and balanced: `load` appends synthetic `tool/result` and `turn/end {interrupted}` closers for unanswered calls instead of dropping the events — a single turn can be large, and those events were durably written before the crash. Only a never-fully-written torn tail fragment is discarded.
 
 ### Failures and recovery
 
diff --git a/packages/session/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
index 007a59c615..a3b6cd90fa 100644
--- a/packages/session/session-persistence/README.zh.md
+++ b/packages/session/session-persistence/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-session-persistence` 通过后端无关的 `ctx.sessionPersistence` 服务持久存储会话的事件日志、在恢复时重新加载并列出已存储会话。持久化单元就是现有 `SessionEvent` 日志——不存在另一套并行的存储消息类型——不可回放的元数据（格式版本、工作目录、血缘、种子边界）作为 `SessionHeader` 单独传输。后端拥有自己的存储，而服务拥有仅追加日志、连续序列号、保留中断轮次而非截断的崩溃恢复，以及只在批次安全后才返回的持久写入。随产品交付的 JSONL provider 用每个 Session 一份产物实现该服务；第三方 provider 可以实现同一约定，而不改变 loop 或模型。
+`dsh-session-persistence` 通过后端无关的 `ctx.sessionPersistence` 服务持久存储会话的事件日志、在恢复时重新加载并列出已存储会话。持久化单元就是现有 `SessionEvent` 日志——不存在另一套并行的存储消息类型。`SessionHeader.isSeeded` 让轻量列表可见血缘，而精确的 `inheritedEventCount` 随每次带正文的存储读取与 prepared Session 一同传输。后端拥有自己的存储，而服务拥有仅追加日志、连续序列号、保留中断轮次而非截断的崩溃恢复，以及只在批次安全后才返回的持久写入。随产品交付的 JSONL provider 用每个 Session 一份产物实现该服务；第三方 provider 可以实现同一约定，而不改变 loop 或模型。
 
 ## 目录
 
@@ -36,18 +36,18 @@ seam 随产品交付 [JSONL](../session-persistence-jsonl/README.zh.md) 后端
 挂载后端后，你可以持久存储会话事件、重新加载已存储日志并列出已存储内容：
 
 ```text
-await ctx.sessionPersistence.create(meta)                  // register a session
+await ctx.sessionPersistence.create(meta, inheritedEventCount) // cut required when meta.isSeeded
 await ctx.sessionPersistence.ensureMaterialized(session)   // persist an empty resumable session
 await ctx.sessionPersistence.append(id, events)            // durably persist a batch
-const { meta, events } = await ctx.sessionPersistence.load(id)   // reload on resume
+const { meta, inheritedEventCount, events } = await ctx.sessionPersistence.load(id)
 const headers = await ctx.sessionPersistence.list()        // every stored session
 ```
 
-`append` 只在批次持久后返回，因此成功返回的写入在操作系统崩溃或断电后依然存在。普通 `create` 保持惰性；只有当空会话本身必须出现在持久列表中时，生命周期前端才调用 `ensureMaterialized`，且不会虚构事件。`load` 返回不可变的平衡日志并提交任何需要的崩溃恢复；`inspect` 读取同一视图但不提交恢复。从水位恢复的消费方可以只读取该序列号及之后的已存储事件，会话的产物位置（`locate`）不经文件系统 I/O 即可解析。
+`append` 只在批次持久后返回，因此成功返回的写入在操作系统崩溃或断电后依然存在。普通 `create(meta, inheritedEventCount)` 保持惰性；`meta.isSeeded: true` 要求单独的精确 cut，unseeded metadata 可以省略它并拒绝非零值。seeded 会话的首个物化批次必须到达完整继承前缀，因此存储绝不公开 cut 超过日志的 metadata。只有当空会话本身必须出现在持久列表中时，生命周期前端才调用 `ensureMaterialized`，且不会虚构事件。`load` 返回不可变的平衡日志并提交任何需要的崩溃恢复；`inspect` 读取同一份完整视图但不提交恢复。`readFrom` 接受 `SessionLogOffset`，并返回分离的 `SessionEventSuffix`，其中携带该 `fromSeq`、不变的继承 cut，以及 cut 位置或之后的存储事件。会话的产物位置（`locate`）不经文件系统 I/O 即可解析。
 
 ### 恢复与崩溃恢复
 
-恢复就是 `load` 加会话准备：存储日志连同其头部血缘一起返回，因此恢复后的 agent（智能体）看到相同的历史与组装。中途崩溃的会话重新加载时，其被中断的最终轮次会保留并保持平衡：`load` 为未获回答的调用追加合成 `tool/result` 与 `turn/end {interrupted}` closer，而不是丢弃事件——单个轮次可能很大，而这些事件在崩溃前已持久写入。只有从未完整写入的撕裂尾部碎片会被丢弃。
+恢复就是 `load` 加会话准备：存储日志连同其 header 血缘与精确继承切点一起返回，因此所有权检查不从标记或完整恢复长度推断切点。中途崩溃的会话重新加载时，其被中断的最终轮次会保留并保持平衡：`load` 为未获回答的调用追加合成 `tool/result` 与 `turn/end {interrupted}` closer，而不是丢弃事件——单个轮次可能很大，而这些事件在崩溃前已持久写入。只有从未完整写入的撕裂尾部碎片会被丢弃。
 
 ### 失败与恢复
 
diff --git a/packages/session/session-persistence/src/coordinator.ts b/packages/session/session-persistence/src/coordinator.ts
index 4075b0dc26..c16fae6d40 100644
--- a/packages/session/session-persistence/src/coordinator.ts
+++ b/packages/session/session-persistence/src/coordinator.ts
@@ -11,13 +11,28 @@ import {
   interruptedTurnClosers,
   KNOWN_SESSION_EVENT_TYPES,
   SESSION_FORMAT_VERSION,
+  SessionLogOffset,
   SessionPreparation,
+  SessionSeq,
   snapshotSessionEvent,
 } from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionId,
+  SessionHeader,
+  SessionLogOffset as SessionLogOffsetType,
+  SessionSeq as SessionSeqType,
+} from '@deepseek-ai/dsh-session'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { snapshotJsonValue } from '@deepseek-ai/dsh-util-values'
-import type { BorrowedSessionSource, SessionInspection, SessionLocation } from './index.ts'
+import type {
+  BorrowedSessionSource,
+  SessionEventSuffix,
+  SessionInspection,
+  SessionLocation,
+  SessionStorageMetadata,
+} from './index.ts'
 import { SessionPersistenceNotFoundError } from './errors.ts'
 import type { SessionPersistenceRevision } from './revision.ts'
 import { observeQueuedAbort, SessionPreparations } from './preparations.ts'
@@ -96,8 +111,7 @@ export interface PersistenceCoordinatorOptions {
  * returns its value to {@link PersistenceBackend.commitRepair}; each backend
  * owns the marker type.
  */
-export interface StoredPrefix<TornMarker = unknown> {
-  meta: SessionHeader
+export interface StoredPrefix<TornMarker = unknown> extends SessionStorageMetadata {
   events: SessionEvent[]
   /** Revision observed for exactly this detached prefix. */
   revision: SessionPersistenceRevision
@@ -110,8 +124,7 @@ export interface StoredPrefix<TornMarker = unknown> {
  * {@link PersistenceBackend.loadStoredFrom} hook. Non-mutating reads carry no
  * torn marker: there is nothing to repair.
  */
-export interface StoredSuffix {
-  meta: SessionHeader
+export interface StoredSuffix extends SessionStorageMetadata {
   events: SessionEvent[]
 }
 
@@ -174,18 +187,24 @@ export interface PersistenceBackend<TornMarker = unknown> {
    *   validated by the coordinator before this hook runs).
    * @param signal - optional cancellation for backend read work.
    */
-  loadStoredFrom?(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined>
+  loadStoredFrom?(id: SessionId, fromSeq: SessionLogOffsetType, signal?: AbortSignal): Promise<StoredSuffix | undefined>
 
   /** Durably create an empty header-only session artifact. */
-  materializeHeader?(meta: SessionHeader): Promise<void>
+  materializeHeader?(storage: SessionStorageMetadata): Promise<void>
 
   /**
    * Durably append a CONTIGUOUS batch, lazily materializing the session first
    * when `!isMaterialized`. The materialize-write and the first event batch MUST
    * commit ATOMICALLY (a crash between them must not leave a materialized-but-
    * empty session). Returns once the batch is durable.
+   * The coordinator calls this only after a first batch reaches the declared
+   * inherited prefix length.
    */
-  appendBatch(meta: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>
+  appendBatch(
+    storage: SessionStorageMetadata,
+    events: readonly SessionEvent[],
+    isMaterialized: boolean,
+  ): Promise<void>
 
   /**
    * Make a crash repair durable: truncate the torn tail (iff
@@ -194,7 +213,11 @@ export interface PersistenceBackend<TornMarker = unknown> {
    * Used by load (truncate + synthetic closers) and by live-adoption (truncate
    * only, `closers = []`).
    */
-  commitRepair(meta: SessionHeader, tornMarker: TornMarker | undefined, closers: readonly SessionEvent[]): Promise<void>
+  commitRepair(
+    storage: SessionStorageMetadata,
+    tornMarker: TornMarker | undefined,
+    closers: readonly SessionEvent[],
+  ): Promise<void>
 
   /**
    * List all stored (materialized) sessions' metadata.
@@ -220,9 +243,9 @@ export interface PersistenceBackend<TornMarker = unknown> {
 
 /** Per-session write state held by the coordinator's in-memory bookkeeping. */
 interface SessionState {
-  meta: SessionHeader
+  storage: SessionStorageMetadata
   /** The next seq the backend expects to append (the stored log length). */
-  cursor: number
+  cursor: SessionLogOffsetType
   /**
    * Whether lazy creation has produced a durable artifact. The first append
    * atomically materializes the header with events; reclaim logic uses this to
@@ -250,7 +273,7 @@ interface PreparedSessionSource<TornMarker> {
   readonly session: Session
   readonly revision: SessionPersistenceRevision
   /** Session length after constructor-owned seed markers were appended. */
-  readonly sessionLength: number
+  readonly sessionLength: SessionLogOffsetType
   readonly tornMarker: TornMarker | undefined
   readonly closers: readonly SessionEvent[]
 }
@@ -274,6 +297,26 @@ function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly Sessio
     })
 }
 
+/** Normalize the exact fork cut paired with one logical Session header. */
+function storageMetadata(
+  meta: SessionHeader,
+  inheritedEventCount?: SessionLogOffsetType,
+): SessionStorageMetadata {
+  if (meta.isSeeded && inheritedEventCount === undefined) {
+    throw new TypeError('seeded session metadata requires an inherited event count')
+  }
+  const cut = SessionLogOffset(inheritedEventCount ?? 0)
+  if (!meta.isSeeded && cut !== 0) {
+    throw new TypeError('unseeded session metadata inherited event count must be 0')
+  }
+  return { meta, inheritedEventCount: cut }
+}
+
+/** Exact storage metadata owned by one live Session. */
+function sessionStorageMetadata(session: Session): SessionStorageMetadata {
+  return storageMetadata(session.header, session.inheritedEventCount)
+}
+
 /** Reject events from an obsolete v0 vocabulary that this build cannot replay. */
 function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId): void {
   const legacyType: string = 'request/header-delta'
@@ -314,16 +357,19 @@ function hasOnlyKeys(
 type PersistedMessageId = SessionEvent<'user/message'>['data']['id']
 
 /** Mint the stable import identity for a message persisted before identities existed. */
-function legacyMessageId(id: SessionId, seq: number): PersistedMessageId {
+function legacyMessageId(id: SessionId, seq: SessionSeqType): PersistedMessageId {
   return `legacy-message:${id}:${seq}` as PersistedMessageId
 }
 
 /** Read a replacement target while leaving malformed surface metadata to the session validator. */
-function replacementStart(event: SessionEvent): number | undefined {
+function replacementStart(event: SessionEvent): SessionSeqType | undefined {
   const op = asRecord((event as SessionEvent & { surfaceOp?: unknown }).surfaceOp)
-  return op?.['op'] === 'replace' && typeof op['start'] === 'number'
-    ? op['start']
-    : undefined
+  if (op?.['op'] !== 'replace' || typeof op['start'] !== 'number') return undefined
+  try {
+    return SessionSeq(op['start'])
+  } catch {
+    return undefined
+  }
 }
 
 /** Whether one suffix event needs facts available only from the preceding stored prefix. */
@@ -466,7 +512,7 @@ function migrateLegacyTurnEndEvent(event: SessionEvent, id: SessionId): SessionE
 function migrateLegacyMessageEvent(
   event: SessionEvent,
   id: SessionId,
-  messageIds: ReadonlyMap<number, PersistedMessageId>,
+  messageIds: ReadonlyMap<SessionSeqType, PersistedMessageId>,
 ): SessionEvent {
   const data = asRecord(event.data)
   if (data === undefined) return event
@@ -548,7 +594,7 @@ function eventMessageId(event: SessionEvent): PersistedMessageId | undefined {
 /** Materialize stored events as upgraded, validated snapshots with immutable messages. */
 function snapshotStoredEvents(events: readonly SessionEvent[], id: SessionId): SessionEvent[] {
   assertSupportedEvents(events, id)
-  const messageIds = new Map<number, PersistedMessageId>()
+  const messageIds = new Map<SessionSeqType, PersistedMessageId>()
   return events.map((event) => {
     const migratedStart = migrateLegacyTurnStartEvent(event, id)
     const migratedTurn = migrateLegacyTurnEndEvent(migratedStart, id)
@@ -563,7 +609,7 @@ function snapshotStoredEvents(events: readonly SessionEvent[], id: SessionId): S
 /** Upgrade and validate an exclusively owned backend result without copying it. */
 function adoptStoredEvents(events: SessionEvent[], id: SessionId): SessionEvent[] {
   assertSupportedEvents(events, id)
-  const messageIds = new Map<number, PersistedMessageId>()
+  const messageIds = new Map<SessionSeqType, PersistedMessageId>()
   for (const [index, event] of events.entries()) {
     const migratedStart = migrateLegacyTurnStartEvent(event, id)
     const migratedTurn = migrateLegacyTurnEndEvent(migratedStart, id)
@@ -633,8 +679,10 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Register detached session metadata for lazy creation on the first append.
    * @param meta - header to snapshot; duplicate tracked or persisted ids reject.
+   * @param inheritedEventCount - exact inherited prefix length; required for
+   * a seeded header and omitted only for an unseeded header.
    */
-  create(meta: SessionHeader): Promise<void> {
+  create(meta: SessionHeader, inheritedEventCount?: SessionLogOffsetType): Promise<void> {
     // Snapshot before queueing so caller mutation cannot diverge the key and header.
     const snapshot = snapshotJsonValue(meta)
     if (snapshot === undefined) {
@@ -643,7 +691,16 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     if (!Number.isSafeInteger(snapshot.createdAt) || snapshot.createdAt < 0) {
       return Promise.reject(new TypeError('session metadata createdAt must be a non-negative safe integer'))
     }
-    return this.serialize(snapshot.id, () => this.createCore(snapshot))
+    let storage: SessionStorageMetadata
+    try {
+      storage = storageMetadata(snapshot, inheritedEventCount)
+    } catch (error: unknown) {
+      /* v8 ignore next -- Session storage validation only throws Error instances. */
+      return Promise.reject(error instanceof Error
+        ? error
+        : new TypeError('invalid session storage metadata', { cause: error }))
+    }
+    return this.serialize(snapshot.id, () => this.createCore(storage))
   }
 
   /**
@@ -660,13 +717,14 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       if (this.backend.materializeHeader === undefined) {
         throw new Error('session persistence backend cannot materialize an empty session')
       }
-      await this.backend.materializeHeader(state.meta)
+      await this.backend.materializeHeader(state.storage)
       state.materialized = true
       this.preparations.invalidate(session.id)
     })
   }
 
-  private async createCore(meta: SessionHeader): Promise<void> {
+  private async createCore(storage: SessionStorageMetadata): Promise<void> {
+    const { meta } = storage
     // Do NOT clobber an existing session: the SessionId IS the identity.
     if (this.states.has(meta.id) || this.preparations.has(meta.id)) {
       throw new Error(`session "${meta.id}" already exists in this backend`)
@@ -678,7 +736,11 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       throw new Error(`session "${meta.id}" already has a persisted log on disk; load/resume it instead of creating`)
     }
     // Pure lazy: record intent only. No artifact until the first append.
-    this.states.set(meta.id, { meta, cursor: 0, materialized: false })
+    this.states.set(meta.id, {
+      storage,
+      cursor: SessionLogOffset(0),
+      materialized: false,
+    })
   }
 
   // `async` so synchronous materialization failures below reject (not throw) per
@@ -725,11 +787,16 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       }
     }
 
-    await this.backend.appendBatch(state.meta, events, state.materialized)
+    const nextCursor = SessionLogOffset(state.cursor + events.length)
+    if (!state.materialized && nextCursor < state.storage.inheritedEventCount) {
+      throw new Error(`session "${id}" cannot materialize before its inherited prefix is complete`)
+    }
+
+    await this.backend.appendBatch(state.storage, events, state.materialized)
     // The durable write is the transaction: mark materialized + advance the
     // cursor as soon as it commits (uniform across backends).
     state.materialized = true
-    state.cursor += events.length
+    state.cursor = nextCursor
     this.preparations.invalidate(id)
   }
 
@@ -909,11 +976,20 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * @param id - persisted session to read.
    * @param fromSeq - first event seq to include; a non-negative safe integer.
    * @param signal - optional cancellation for queued and backend read work.
-   * @returns stored header and the valid stored events with `seq >= fromSeq`.
+   * @returns stored metadata, the requested offset, and valid events with `seq >= fromSeq`.
    */
-  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    if (!Number.isSafeInteger(fromSeq) || fromSeq < 0) {
-      return Promise.reject(new TypeError(`readFrom fromSeq must be a non-negative safe integer, got ${String(fromSeq)}`))
+  readFrom(
+    id: SessionId,
+    fromSeq: SessionLogOffsetType,
+    signal?: AbortSignal,
+  ): Promise<SessionEventSuffix> {
+    try {
+      SessionLogOffset(fromSeq)
+    } catch (error: unknown) {
+      /* v8 ignore next -- Session log-offset validation only throws Error instances. */
+      return Promise.reject(error instanceof Error
+        ? error
+        : new TypeError('invalid session read offset', { cause: error }))
     }
     const retired = Promise.resolve(this.retirements.get(id))
     const waited = signal === undefined ? retired : observeQueuedAbort(retired, signal, () => false)
@@ -922,9 +998,9 @@ export class PersistenceCoordinator<TornMarker = unknown> {
 
   private async readFromCore(
     id: SessionId,
-    fromSeq: number,
+    fromSeq: SessionLogOffsetType,
     signal?: AbortSignal,
-  ): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  ): Promise<SessionEventSuffix> {
     signal?.throwIfAborted()
     if (this.backend.loadStoredFrom !== undefined) {
       let suffix: StoredSuffix | undefined
@@ -940,22 +1016,37 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       this.assertVersion(suffix.meta)
       if (suffix.events.some(needsLegacyPrefix)) {
         const whole = await this.readStoredPrefix(id, signal)
-        return { meta: whole.meta, events: whole.events.filter(event => event.seq >= fromSeq) }
+        return {
+          meta: whole.meta,
+          inheritedEventCount: whole.inheritedEventCount,
+          fromSeq,
+          events: whole.events.filter(event => event.seq >= fromSeq),
+        }
       }
       const events = snapshotStoredEvents(suffix.events, id)
       this.assertEventsSupported(suffix.meta, events)
-      return { meta: structuredClone(suffix.meta), events }
+      return {
+        meta: structuredClone(suffix.meta),
+        inheritedEventCount: SessionLogOffset(suffix.inheritedEventCount),
+        fromSeq,
+        events,
+      }
     }
     const whole = await this.readStoredPrefix(id, signal)
     // Sequential fallback: contiguous seqs from 0 make the suffix an index slice.
-    return { meta: whole.meta, events: whole.events.slice(fromSeq) }
+    return {
+      meta: whole.meta,
+      inheritedEventCount: whole.inheritedEventCount,
+      fromSeq,
+      events: whole.events.slice(fromSeq),
+    }
   }
 
   /** Read one detached physical prefix without logical recovery or caching. */
   private async readStoredPrefix(
     id: SessionId,
     signal?: AbortSignal,
-  ): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  ): Promise<SessionInspection> {
     signal?.throwIfAborted()
     const stored = await this.backend.loadStored(id, signal)
     signal?.throwIfAborted()
@@ -966,6 +1057,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     this.assertEventsSupported(stored.meta, events)
     return {
       meta: structuredClone(stored.meta),
+      inheritedEventCount: SessionLogOffset(stored.inheritedEventCount),
       events,
     }
   }
@@ -975,11 +1067,14 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     const stored = await this.backend.loadStored(id)
     if (stored === undefined) throw new SessionPersistenceNotFoundError(id)
     try {
-      const { meta, events, revision, tornMarker } = stored
+      const { meta, inheritedEventCount, events, revision, tornMarker } = stored
       this.assertStoredId(id, meta)
       this.assertVersion(meta)
       const storedEvents = adoptStoredEvents(events, id)
       this.assertEventsSupported(meta, storedEvents)
+      if (inheritedEventCount > storedEvents.length) {
+        throw new Error(`session "${id}" inherited event count exceeds its stored event count`)
+      }
 
       // Preserve complete interrupted events and synthesize only missing closers.
       const closers = interruptedTurnClosers(storedEvents).map(adoptSessionEvent)
@@ -987,10 +1082,12 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       const session = this.ctx.sessions.prepare(id, {
         seed: balanced,
         meta,
+        inheritedEventCount,
         seedSource: 'persistence',
       })
       const inspection: SessionInspection = Object.freeze({
         meta: session.header,
+        inheritedEventCount: session.inheritedEventCount,
         events: Object.freeze(balanced),
       })
       return {
@@ -1017,24 +1114,24 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     source: PreparedSessionSource<TornMarker>,
   ): Promise<{ source: PreparedSessionSource<TornMarker>; state: SessionState } | undefined> {
     const id = source.inspection.meta.id
-    const cursor = source.inspection.events.length
+    const cursor = SessionLogOffset(source.inspection.events.length)
     const existing = this.states.get(id)
     if (existing?.owner !== undefined) {
       throw new Error(`session "${id}" already has a live persistence owner`)
     }
     if (!await this.isPreparedSourceCurrent(source)) return undefined
     if (source.tornMarker !== undefined || source.closers.length > 0) {
-      await this.backend.commitRepair(source.inspection.meta, source.tornMarker, source.closers)
+      await this.backend.commitRepair(source.inspection, source.tornMarker, source.closers)
       // The repair changed the durable revision. Reload the exact committed
       // graph instead of associating the old in-memory view with a newer revision.
       return undefined
     }
     const state = existing ?? {
-      meta: source.inspection.meta,
+      storage: source.inspection,
       cursor,
       materialized: true,
     }
-    state.meta = source.inspection.meta
+    state.storage = source.inspection
     state.cursor = cursor
     state.materialized = true
     this.states.set(id, state)
@@ -1063,12 +1160,20 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     if (interruptedTurnClosers(events).length > 0) {
       throw new Error(`cannot load session "${session.id}" while its live turn is open; use the live Session or wait for the turn to close`)
     }
-    return Object.freeze({ meta: state.meta, events })
+    return Object.freeze({
+      meta: state.storage.meta,
+      inheritedEventCount: state.storage.inheritedEventCount,
+      events,
+    })
   }
 
   /** Borrow one immutable view from an already-live Session. */
   private inspectLive(session: Session): SessionInspection {
-    return Object.freeze({ meta: session.header, events: session.snapshotEvents() })
+    return Object.freeze({
+      meta: session.header,
+      inheritedEventCount: session.inheritedEventCount,
+      events: session.snapshotEvents(),
+    })
   }
 
   /** Await one retiring lifecycle with caller cancellation. */
@@ -1293,7 +1398,11 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * events. A `cursor` of 0 (nothing persisted yet) trivially matches. Used when
    * a live session claims ownerless state left by a prior `load()`/`create()`.
    */
-  private async seedMatchesPersisted(id: SessionId, seed: readonly SessionEvent[], cursor: number): Promise<boolean> {
+  private async seedMatchesPersisted(
+    id: SessionId,
+    seed: readonly SessionEvent[],
+    cursor: SessionLogOffsetType,
+  ): Promise<boolean> {
     if (cursor === 0) return true
     const stored = await this.backend.loadStored(id)
     /* v8 ignore next -- a cursor > 0 means the session was materialized, so it exists */
@@ -1330,8 +1439,11 @@ export class PersistenceCoordinator<TornMarker = unknown> {
         // the stored header's cwd. The seed guard then ensures the live events
         // reproduce the persisted prefix; otherwise a fresh session reusing the
         // id could have its leading events filtered as already written.
-        if (tracked.meta.cwd !== session.header.cwd) {
-          throw new Error(`session "${id}" is already persisted at a different cwd (persisted: ${String(tracked.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
+        if (tracked.storage.meta.cwd !== session.header.cwd) {
+          throw new Error(`session "${id}" is already persisted at a different cwd (persisted: ${String(tracked.storage.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
+        }
+        if (tracked.storage.inheritedEventCount !== session.inheritedEventCount) {
+          throw new Error(`session "${id}" is already persisted with a different inherited event count (id collision)`)
         }
         if (!await this.seedMatchesPersisted(id, seed, tracked.cursor)) {
           throw new Error(`session "${id}" is already persisted with ${tracked.cursor} event(s) that do not match this live session (id collision)`)
@@ -1364,8 +1476,11 @@ export class PersistenceCoordinator<TornMarker = unknown> {
 
     // case 4: a genuinely new session. Register its meta (lazy), then persist its
     // seed (events present at creation time) once.
-    const meta: SessionHeader = { ...session.header }
-    await this.createCore(meta)
+    const storage = sessionStorageMetadata(session)
+    await this.createCore({
+      meta: { ...storage.meta },
+      inheritedEventCount: storage.inheritedEventCount,
+    })
     // Bind this state to the live session so a later DIFFERENT session reusing
     // the id is detected as a collision (case 1) rather than silently no-opped.
     const created = this.states.get(id)
@@ -1381,11 +1496,14 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * live suffix that was ahead of the stored prefix.
    */
   private async adoptLivePrefix(session: Session, seed: readonly SessionEvent[], stored: StoredPrefix<TornMarker>): Promise<void> {
-    const { meta, events, tornMarker } = stored
+    const { meta, inheritedEventCount, events, tornMarker } = stored
     this.assertStoredId(session.header.id, meta)
     if (meta.cwd !== session.header.cwd) {
       throw new Error(`session "${session.header.id}" is already persisted at a different cwd (persisted: ${String(meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
     }
+    if (inheritedEventCount !== session.inheritedEventCount) {
+      throw new Error(`session "${session.header.id}" is already persisted with a different inherited event count (id collision)`)
+    }
     this.assertVersion(meta)
     const storedEvents = snapshotStoredEvents(events, session.header.id)
     this.assertEventsSupported(meta, storedEvents)
@@ -1393,10 +1511,13 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       throw new Error(`session "${session.header.id}" already has a persisted log on disk that does not match this live session (id collision)`)
     }
     // Truncate-only repair (no closers): the open turn is NOT closed here.
-    if (tornMarker !== undefined) await this.backend.commitRepair(meta, tornMarker, [])
+    if (tornMarker !== undefined) await this.backend.commitRepair(stored, tornMarker, [])
     this.states.set(session.header.id, {
-      meta: { ...meta },
-      cursor: storedEvents.length,
+      storage: {
+        meta: { ...meta },
+        inheritedEventCount,
+      },
+      cursor: SessionLogOffset(storedEvents.length),
       materialized: true,
       owner: session,
     })
diff --git a/packages/session/session-persistence/src/index.ts b/packages/session/session-persistence/src/index.ts
index 5cb2311239..d110703d3a 100644
--- a/packages/session/session-persistence/src/index.ts
+++ b/packages/session/session-persistence/src/index.ts
@@ -6,8 +6,13 @@
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import { SessionPreparation } from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionPreparation, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionId,
+  SessionHeader,
+} from '@deepseek-ai/dsh-session'
 import type { SessionPersistenceRevision } from './revision.ts'
 
 // Re-export the metadata vocabulary so Consumers import it from the Service Definition.
@@ -23,14 +28,28 @@ export interface SessionPersistenceSnapshot {
   revision: SessionPersistenceRevision
 }
 
-/** Immutable logical session prepared from persistence or a live owner. */
-export interface SessionInspection {
-  /** Validated immutable session metadata. */
+/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
+export interface SessionStorageMetadata {
+  /** Validated immutable Session header. */
   readonly meta: SessionHeader
+  /** Number of leading events inherited from the Session's fork parent. */
+  readonly inheritedEventCount: SessionLogOffset
+}
+
+/** Immutable logical session prepared from persistence or a live owner. */
+export interface SessionInspection extends SessionStorageMetadata {
   /** Validated contiguous logical event log. */
   readonly events: readonly SessionEvent[]
 }
 
+/** Detached logical suffix returned by one explicit stored-log offset read. */
+export interface SessionEventSuffix extends SessionStorageMetadata {
+  /** First requested log offset; {@link events} contains only seqs at or after it. */
+  readonly fromSeq: SessionLogOffset
+  /** Valid contiguous stored events at or after {@link fromSeq}; not a complete Session log when the offset is nonzero. */
+  readonly events: readonly SessionEvent[]
+}
+
 /** A borrowed exact Session source returned from a cold materialization or concurrent live owner. */
 export type BorrowedSessionSource = Disposable & (
   | {
@@ -52,9 +71,7 @@ export type BorrowedSessionSource = Disposable & (
 )
 
 /** A backend's own raw artifact text for one session, verbatim. */
-export interface SessionRawArtifact {
-  /** The session header parsed from the artifact's own first line. */
-  readonly meta: SessionHeader
+export interface SessionRawArtifact extends SessionStorageMetadata {
   /** The artifact's base filename on disk, without any physical encoding suffix. */
   readonly filename: string
   /** The artifact's full text content, decoded from the backend's physical encoding. */
@@ -150,8 +167,10 @@ export abstract class SessionPersistence extends Service {
    * created-but-never-appended session is absent from {@link list}
    * — abandoned sessions leave nothing behind.
    * @param meta - the immutable header (id, version, cwd, lineage) to record.
+   * @param inheritedEventCount - exact fork-inherited prefix length. Required
+   * for a seeded header and omitted only for an unseeded header.
    */
-  abstract create(meta: SessionHeader): Promise<void>
+  abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>
 
   /**
    * Ensure a live session has a durable header even when it has no events.
@@ -168,6 +187,8 @@ export abstract class SessionPersistence extends Service {
    * seq contracts: the first event's `seq` MUST equal the stored next-seq
    * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
    * serializable `event.data` with an error naming the offending event type.
+   * A seeded session's first materializing batch must reach its complete
+   * inherited prefix.
    * @param id - the session the batch belongs to.
    * @param events - the contiguous batch to persist, in seq order.
    */
@@ -194,6 +215,7 @@ export abstract class SessionPersistence extends Service {
     return SessionPreparation.create(sessions.prepare(id, {
       seed: loaded.events.map(event => structuredClone(event)),
       meta: structuredClone(loaded.meta),
+      inheritedEventCount: SessionLogOffset(loaded.inheritedEventCount),
       seedSource: 'persistence',
     }))
   }
@@ -255,12 +277,12 @@ export abstract class SessionPersistence extends Service {
    * forward. The primitive bounds what is returned and refolded, not every
    * backend's physical read.
    * @param id - the persisted session to read.
-   * @param fromSeq - first event seq to include; a non-negative safe integer.
+   * @param fromSeq - first event offset to include.
    * @param signal - optional cancellation for queued and backend read work.
-   * @returns the header and the stored events with `seq >= fromSeq`.
+   * @returns storage metadata, the requested offset, and stored events with `seq >= fromSeq`.
    */
-  abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal):
-  Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+  abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal):
+  Promise<SessionEventSuffix>
 
   /**
    * Lightweight listing from metadata, without a full-log parse.
diff --git a/packages/session/session-persistence/tests/contract.ts b/packages/session/session-persistence/tests/contract.ts
index 5be7076bd7..b8f611eebb 100644
--- a/packages/session/session-persistence/tests/contract.ts
+++ b/packages/session/session-persistence/tests/contract.ts
@@ -9,8 +9,22 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { SESSION_FORMAT_VERSION, Session, SessionId, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionHeader, SurfaceEventType, SurfaceIntent } from '@deepseek-ai/dsh-session'
+import {
+  SESSION_FORMAT_VERSION,
+  Session,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+  TOOL_NOT_STARTED,
+  TOOL_OUTCOME_UNKNOWN,
+} from '@deepseek-ai/dsh-session'
+import type {
+  SessionEvent,
+  SessionHeader,
+  SessionLogOffset as SessionLogOffsetType,
+  SurfaceEventType,
+  SurfaceIntent,
+} from '@deepseek-ai/dsh-session'
 import { ToolCallId, MessageId, createMessage, freezeMessage } from '@deepseek-ai/dsh-llm'
 import type { SessionPersistence } from '../src/index.ts'
 
@@ -27,20 +41,21 @@ export function meta(id: string, cwd?: string): SessionHeader {
     id: SessionId(id),
     createdAt: 1000,
     ...cwd !== undefined ? { cwd } : {},
+    isSeeded: false,
   }
 }
 
 /** A well-formed one-turn event log (contiguous seqs from 0). */
 export function oneTurnLog(): SessionEvent[] {
   return [
-    { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-    { type: 'user/message', seq: 1, time: 2, data: freezeMessage({
+    { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+    { type: 'user/message', seq: SessionSeq(1), time: 2, data: freezeMessage({
       id: MessageId('one-turn-user'),
       role: 'user',
       content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
     }), surfaceOp: 'append' },
-    { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
-    { type: 'assistant/message', seq: 3, time: 4, data: {
+    { type: 'step/start', seq: SessionSeq(2), time: 3, data: { turn: 1, step: 1 } },
+    { type: 'assistant/message', seq: SessionSeq(3), time: 4, data: {
       turn: 1, step: 1,
       message: freezeMessage({
         id: MessageId('one-turn-assistant'),
@@ -52,8 +67,8 @@ export function oneTurnLog(): SessionEvent[] {
         },
       }),
     }, surfaceOp: 'append' },
-    { type: 'step/end', seq: 4, time: 5, data: { turn: 1, step: 1 } },
-    { type: 'turn/end', seq: 5, time: 6, data: { turn: 1, reason: { kind: 'completed' } } },
+    { type: 'step/end', seq: SessionSeq(4), time: 5, data: { turn: 1, step: 1 } },
+    { type: 'turn/end', seq: SessionSeq(5), time: 6, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
 }
 
@@ -115,6 +130,44 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
       }
     })
 
+    it('requires an explicit inherited cut exactly when the header is seeded', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const seeded = { ...meta('seeded-create'), isSeeded: true }
+        await expect(persistence.create(seeded))
+          .rejects.toThrow('seeded session metadata requires an inherited event count')
+        await expect(persistence.create(meta('unseeded-nonzero'), SessionLogOffset(1)))
+          .rejects.toThrow('unseeded session metadata inherited event count must be 0')
+
+        await persistence.create(seeded, SessionLogOffset(0))
+        await persistence.append(seeded.id, oneTurnLog())
+        await expect(persistence.load(seeded.id)).resolves.toMatchObject({
+          meta: { isSeeded: true },
+          inheritedEventCount: 0,
+        })
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('does not materialize a seeded artifact before its complete inherited prefix', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const seeded = { ...meta('seeded-partial-create'), isSeeded: true }
+        await persistence.create(seeded, SessionLogOffset(2))
+        await expect(persistence.append(seeded.id, oneTurnLog().slice(0, 1)))
+          .rejects.toThrow('cannot materialize before its inherited prefix is complete')
+        expect((await persistence.list()).map(header => header.id)).not.toContain(seeded.id)
+
+        await persistence.append(seeded.id, oneTurnLog())
+        await expect(persistence.load(seeded.id)).resolves.toMatchObject({
+          inheritedEventCount: 2,
+        })
+      } finally {
+        await dispose()
+      }
+    })
+
     it('crash recovery: load preserves an interrupted (unclosed) turn and closes it with turn/end {interrupted}', async () => {
       const { persistence, dispose } = await make()
       try {
@@ -124,8 +177,8 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         // A second turn that crashed mid-flight: turn/start + step/start were
         // durably written, but no step/end / turn/end ever arrived.
         await persistence.append(m.id, [
-          { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-          { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } },
+          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+          { type: 'step/start', seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
         ])
         const beforeRepair = (await persistence.listSnapshots())
           .find(snapshot => snapshot.header.id === m.id)?.revision
@@ -157,8 +210,8 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         // The closed log is durable and continuable: a fresh append continues at
         // the balanced length (seq 10), and a reload round-trips identically.
         await persistence.append(m.id, [
-          { type: 'turn/start', seq: 10, time: 9, data: { turn: 3 } },
-          { type: 'turn/end', seq: 11, time: 10, data: { turn: 3, reason: { kind: 'completed' } } },
+          { type: 'turn/start', seq: SessionSeq(10), time: 9, data: { turn: 3 } },
+          { type: 'turn/end', seq: SessionSeq(11), time: 10, data: { turn: 3, reason: { kind: 'completed' } } },
         ])
         const reloaded = await persistence.load(m.id)
         expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
@@ -177,9 +230,9 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         // BEFORE the tool/result was written (the loop runs tools after logging
         // the assistant message — a process killed mid-tool lands exactly here).
         await persistence.append(m.id, [
-          { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-          { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } },
-          { type: 'assistant/message', seq: 8, time: 9, data: {
+          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+          { type: 'step/start', seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
+          { type: 'assistant/message', seq: SessionSeq(8), time: 9, data: {
             turn: 2, step: 1,
             message: createMessage({
               role: 'assistant',
@@ -227,9 +280,9 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         const m = meta('unknown-tool-outcome')
         await persistence.create(m)
         await persistence.append(m.id, [
-          { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-          { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
-          { type: 'assistant/message', seq: 2, time: 3, data: {
+          { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+          { type: 'step/start', seq: SessionSeq(1), time: 2, data: { turn: 1, step: 1 } },
+          { type: 'assistant/message', seq: SessionSeq(2), time: 3, data: {
             turn: 1, step: 1,
             message: createMessage({
               role: 'assistant',
@@ -242,7 +295,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
               },
             }),
           }, surfaceOp: 'append' },
-          { type: 'tool/call', seq: 3, time: 4, data: { turn: 1, step: 1, callId: ToolCallId('call-risk'), name: 'write', arguments: '{}' } },
+          { type: 'tool/call', seq: SessionSeq(3), time: 4, data: { turn: 1, step: 1, callId: ToolCallId('call-risk'), name: 'write', arguments: '{}' } },
         ])
 
         const loaded = await persistence.load(m.id)
@@ -289,7 +342,11 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         await expect(persistence.listSnapshots(controller.signal)).rejects.toBe(reason)
         await expect(persistence.inspect(SessionId('cancelled-inspect'), controller.signal))
           .rejects.toBe(reason)
-        await expect(persistence.readFrom(SessionId('cancelled-read-from'), 0, controller.signal))
+        await expect(persistence.readFrom(
+          SessionId('cancelled-read-from'),
+          SessionLogOffset(0),
+          controller.signal,
+        ))
           .rejects.toBe(reason)
       } finally {
         await dispose()
@@ -304,28 +361,35 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         await persistence.create(m)
         await persistence.append(m.id, log)
 
-        const whole = await persistence.readFrom(m.id, 0)
+        const whole = await persistence.readFrom(m.id, SessionLogOffset(0))
         expect(whole.meta).toMatchObject({ id: m.id, cwd: '/work' })
+        expect(whole.fromSeq).toBe(0)
         expect(whole.events).toEqual(log)
 
-        const suffix = await persistence.readFrom(m.id, 3)
+        const suffix = await persistence.readFrom(m.id, SessionLogOffset(3))
+        expect(suffix.fromSeq).toBe(3)
         expect(suffix.events).toEqual(log.slice(3))
         expect(suffix.events[0]?.seq).toBe(3)
 
         // At/past the stored end: an empty tail, never an error.
-        await expect(persistence.readFrom(m.id, log.length)).resolves.toMatchObject({ events: [] })
-        await expect(persistence.readFrom(m.id, log.length + 100)).resolves.toMatchObject({ events: [] })
+        await expect(persistence.readFrom(m.id, SessionLogOffset(log.length)))
+          .resolves.toMatchObject({ fromSeq: log.length, events: [] })
+        await expect(persistence.readFrom(m.id, SessionLogOffset(log.length + 100)))
+          .resolves.toMatchObject({ fromSeq: log.length + 100, events: [] })
 
         // Non-mutating: an interrupted-turn log is served as stored, no closers.
         await persistence.append(m.id, [
-          { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
+          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
         ])
-        const tail = await persistence.readFrom(m.id, 6)
+        const tail = await persistence.readFrom(m.id, SessionLogOffset(6))
         expect(tail.events.map(event => event.type)).toEqual(['turn/start'])
 
-        await expect(persistence.readFrom(SessionId('absent-read-from'), 0)).rejects.toThrow('not found')
-        await expect(persistence.readFrom(m.id, -1)).rejects.toThrow('non-negative safe integer')
-        await expect(persistence.readFrom(m.id, 1.5)).rejects.toThrow('non-negative safe integer')
+        await expect(persistence.readFrom(SessionId('absent-read-from'), SessionLogOffset(0)))
+          .rejects.toThrow('not found')
+        await expect(persistence.readFrom(m.id, -1 as SessionLogOffsetType))
+          .rejects.toThrow('non-negative safe integer')
+        await expect(persistence.readFrom(m.id, 1.5 as SessionLogOffsetType))
+          .rejects.toThrow('non-negative safe integer')
       } finally {
         await dispose()
       }
@@ -345,7 +409,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
 
         await persistence.append(m.id, [{
           type: 'turn/start',
-          seq: 6,
+          seq: SessionSeq(6),
           time: 7,
           data: { turn: 2 },
         }])
@@ -376,8 +440,8 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         const m = meta('s4')
         await persistence.create(m)
         const gapped: SessionEvent[] = [
-          { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-          { type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }, // gap: missing seq 1
+          { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+          { type: 'step/start', seq: SessionSeq(2), time: 2, data: { turn: 1, step: 1 } }, // gap: missing seq 1
         ]
         await expect(persistence.append(m.id, gapped)).rejects.toThrow()
       } finally {
@@ -411,7 +475,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           const events = [
             {
               type: 'user/message',
-              seq: 0,
+              seq: SessionSeq(0),
               time: 1,
               data: {
                 id: MessageId(`invalid-json-${i}`),
diff --git a/packages/session/session-persistence/tests/coordinator-contract.ts b/packages/session/session-persistence/tests/coordinator-contract.ts
index 908117a18e..587d7ff1c3 100644
--- a/packages/session/session-persistence/tests/coordinator-contract.ts
+++ b/packages/session/session-persistence/tests/coordinator-contract.ts
@@ -13,7 +13,13 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it, vi } from 'vitest'
 import { Context, type Fiber } from '@deepseek-ai/cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
-import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, {
+  SESSION_FORMAT_VERSION,
+  Session,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+} from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { meta, oneTurnLog, appendLog } from './contract.ts'
 
@@ -283,7 +289,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         const header = meta(id, WORK)
         const start: SessionEvent = {
           type: 'turn/start',
-          seq: 0,
+          seq: SessionSeq(0),
           time: 1,
           data: { turn: 1 },
         }
@@ -322,23 +328,49 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
-    it('round-trips the seed boundary (seedLength) through persistence', async () => {
-      // A forked child records how many leading events were inherited via the seed; the
-      // boundary must survive a reload (so a resume/replay can tell the inherited prefix from
-      // the child's own events). The backend must preserve it in stored metadata.
+    it('preserves the exact inherited cut through load, inspect, suffix read, prepare, and reopen', async () => {
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
+      const inherited = oneTurnLog()
       try {
         let session!: Session
         const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
-          session = inner.sessions.create(SessionId('forked-child'), { meta: { cwd: WORK, seedLength: 3 } })
+          session = inner.sessions.create(SessionId('forked-child'), {
+            seed: inherited,
+            inheritedEventCount: SessionLogOffset(inherited.length),
+            meta: { cwd: WORK, isSeeded: true },
+          })
         }, { inject: ['sessions'] }))
-        send(session, oneTurnLog())
         await ctx.sessions.flush(session)
         await sessionFiber.dispose()
 
         const loaded = await ctx.sessionPersistence.load(SessionId('forked-child'))
-        expect(loaded.meta.seedLength).toBe(3)
+        expect(loaded.meta.isSeeded).toBe(true)
+        expect(loaded.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
+        expect((await ctx.sessionPersistence.inspect(SessionId('forked-child'))).inheritedEventCount)
+          .toBe(SessionLogOffset(inherited.length))
+        const suffix = await ctx.sessionPersistence.readFrom(
+          SessionId('forked-child'),
+          SessionLogOffset(3),
+        )
+        expect(suffix.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
+        expect(suffix.fromSeq).toBe(3)
+        expect(suffix.events[0]?.seq).toBe(3)
+        const preparation = await ctx.sessionPersistence.prepare(SessionId('forked-child'))
+        expect(preparation.session.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
+        preparation[Symbol.dispose]()
+
+        await fiber.dispose()
+        const reopened = await freshCtx(fix)
+        try {
+          const reopenedLoad = await reopened.ctx.sessionPersistence.load(SessionId('forked-child'))
+          expect(reopenedLoad.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
+          const reopenedPreparation = await reopened.ctx.sessionPersistence.prepare(SessionId('forked-child'))
+          expect(reopenedPreparation.session.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
+          reopenedPreparation[Symbol.dispose]()
+        } finally {
+          await reopened.fiber.dispose()
+        }
       } finally {
         await fiber.dispose()
         await fix.cleanup()
@@ -458,7 +490,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
           ])
         }
 
-        const replacementSuffix = await ctx.sessionPersistence.readFrom(id, 6)
+        const replacementSuffix = await ctx.sessionPersistence.readFrom(id, SessionLogOffset(6))
         expect(replacementSuffix.events[0]).toMatchObject({
           type: 'tool/result',
           seq: 6,
@@ -482,7 +514,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
 
         const snapshots = [
           await ctx.sessionPersistence.inspect(id),
-          await ctx.sessionPersistence.readFrom(id, 0),
+          await ctx.sessionPersistence.readFrom(id, SessionLogOffset(0)),
           await ctx.sessionPersistence.load(id),
         ]
         for (const snapshot of snapshots) {
@@ -529,7 +561,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
           ])
         }
 
-        const suffix = await ctx.sessionPersistence.readFrom(id, 3)
+        const suffix = await ctx.sessionPersistence.readFrom(id, SessionLogOffset(3))
         expect(suffix.events[0]).toMatchObject({
           type: 'user/message',
           seq: 3,
@@ -563,7 +595,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         const extendedId = SessionId('current-extended-turn-end')
         await ctx.sessionPersistence.create(meta(extendedId, WORK))
         await ctx.sessionPersistence.append(extendedId, [
-          { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
+          { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
           {
             type: 'turn/end', seq: 1, time: 2,
             data: { turn: 1, reason: { kind: 'extension-reason' } },
@@ -689,9 +721,28 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
           await ctx.sessionPersistence.create(meta(malformedId, WORK))
           await ctx.sessionPersistence.append(malformedId, [malformed.event])
           await expect(ctx.sessionPersistence.inspect(malformedId)).rejects.toThrow(malformed.message)
-          await expect(ctx.sessionPersistence.readFrom(malformedId, 0)).rejects.toThrow(malformed.message)
+          await expect(ctx.sessionPersistence.readFrom(malformedId, SessionLogOffset(0)))
+            .rejects.toThrow(malformed.message)
         }
 
+        const malformedReplacementId = SessionId('invalid-old-tool-result-replacement')
+        await ctx.sessionPersistence.create(meta(malformedReplacementId, WORK))
+        await ctx.sessionPersistence.append(malformedReplacementId, [{
+          type: 'tool/result',
+          seq: 0,
+          time: 1,
+          surfaceOp: { op: 'replace', start: -1, end: -1 },
+          data: {
+            turn: 1,
+            step: 1,
+            callId: 'call',
+            content: [{ type: 'text', text: 'result' }],
+            isError: false,
+          },
+        } as unknown as SessionEvent])
+        await expect(ctx.sessionPersistence.inspect(malformedReplacementId))
+          .rejects.toThrow('invalid replace surfaceOp')
+
         for (const type of ['tool/result'] as const) {
           const malformedId = SessionId(`invalid-${type}`)
           await ctx.sessionPersistence.create(meta(malformedId, WORK))
@@ -720,7 +771,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         } as unknown as SessionEvent])
         await expect(ctx.sessionPersistence.inspect(pluginId))
           .resolves.toMatchObject({ events: [{ type: 'plugin/test', data: null, ignorable: true }] })
-        await expect(ctx.sessionPersistence.readFrom(pluginId, 0))
+        await expect(ctx.sessionPersistence.readFrom(pluginId, SessionLogOffset(0)))
           .resolves.toMatchObject({ events: [{ type: 'plugin/test', data: null, ignorable: true }] })
 
         for (const type of ['user/message', 'assistant/message'] as const) {
@@ -733,7 +784,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
             surfaceOp: 'append',
             data: {},
           } as unknown as SessionEvent])
-          await expect(ctx.sessionPersistence.readFrom(missingContentId, 0))
+          await expect(ctx.sessionPersistence.readFrom(missingContentId, SessionLogOffset(0)))
             .rejects.toThrow('lacks an identified message')
         }
       } finally {
@@ -753,7 +804,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         const p = ctx.sessionPersistence.append(m.id, events)
         // Mutate the caller's array AND an event object after the call but before
         // the queued op runs: the snapshot taken at call time must shield the copy.
-        events.push({ type: 'turn/start', seq: 6, time: 99, data: { turn: 2 } })
+        events.push({ type: 'turn/start', seq: SessionSeq(6), time: 99, data: { turn: 2 } })
         if (userMsg?.type === 'user/message') {
           (userMsg.data as { content: unknown[] }).content = [{ type: 'text', text: 'MUTATED' }]
         }
@@ -1170,8 +1221,8 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         const contFiber = await ctx.plugin(Object.assign((inner: Context) => {
           cont = inner.sessions.create(SessionId('claim'), { seed: [
             ...events,
-            { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-            { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+            { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+            { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
           ], meta: { cwd: WORK, createdAt: 2000 } })
         }, { inject: ['sessions'] }))
         await ctx.sessions.flush(cont)
@@ -1210,6 +1261,59 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
+    it('a live session cannot claim ownerless state with a different inherited cut', async () => {
+      const fix = await makeFixture()
+      const { ctx, fiber } = await freshCtx(fix)
+      try {
+        const id = SessionId('wrong-cut-claim')
+        await ctx.sessionPersistence.create(
+          { ...meta(id, WORK), isSeeded: true },
+          SessionLogOffset(0),
+        )
+        const live = ctx.sessions.create(id, {
+          seed: oneTurnLog(),
+          inheritedEventCount: SessionLogOffset(1),
+          meta: { cwd: WORK, isSeeded: true },
+        })
+
+        await expect(ctx.sessions.flush(live))
+          .rejects.toThrow(/different inherited event count|id collision/)
+      } finally {
+        await fiber.dispose()
+        await fix.cleanup()
+      }
+    })
+
+    it('a live session cannot adopt a stored prefix with a different inherited cut', async () => {
+      const fix = await makeFixture()
+      const id = SessionId('wrong-cut-adoption')
+      const first = await freshCtx(fix)
+      try {
+        await first.ctx.sessionPersistence.create(
+          { ...meta(id, WORK), isSeeded: true },
+          SessionLogOffset(0),
+        )
+        await first.ctx.sessionPersistence.append(id, oneTurnLog())
+      } finally {
+        await first.fiber.dispose()
+      }
+
+      const second = await freshCtx(fix)
+      try {
+        const live = second.ctx.sessions.create(id, {
+          seed: oneTurnLog(),
+          inheritedEventCount: SessionLogOffset(1),
+          meta: { cwd: WORK, isSeeded: true },
+        })
+
+        await expect(second.ctx.sessions.flush(live))
+          .rejects.toThrow(/different inherited event count|id collision/)
+      } finally {
+        await second.fiber.dispose()
+        await fix.cleanup()
+      }
+    })
+
     it('a live session at a DIFFERENT cwd cannot claim loaded-prefix ownerless state (cwd scope)', async () => {
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
@@ -1262,8 +1366,8 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       const second = await freshCtx(fix)
       try {
         await second.ctx.sessionPersistence.append(SessionId('adopt-append'), [
-          { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-          { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+          { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
         ])
         const loaded = await second.ctx.sessionPersistence.load(SessionId('adopt-append'))
         expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
@@ -1329,7 +1433,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
-        const m = { version: 99, id: SessionId('v99'), createdAt: 1, cwd: WORK }
+        const m = { version: 99, id: SessionId('v99'), createdAt: 1, cwd: WORK, isSeeded: false }
         await ctx.sessionPersistence.create(m)
         await ctx.sessionPersistence.append(m.id, oneTurnLog())
         const failure = await ctx.sessionPersistence.load(m.id).then(() => undefined, (error: unknown) => error as Error)
@@ -1345,7 +1449,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
-        const m = { version: -1, id: SessionId('v-older'), createdAt: 1, cwd: WORK }
+        const m = { version: -1, id: SessionId('v-older'), createdAt: 1, cwd: WORK, isSeeded: false }
         await ctx.sessionPersistence.create(m)
         await ctx.sessionPersistence.append(m.id, oneTurnLog())
         const failure = await ctx.sessionPersistence.load(m.id).then(() => undefined, (error: unknown) => error as Error)
@@ -1389,7 +1493,14 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
-        const m = { version: SESSION_FORMAT_VERSION, id: SessionId('forked-child'), createdAt: 1, cwd: WORK, parentSession: SessionId('the-parent') }
+        const m = {
+          version: SESSION_FORMAT_VERSION,
+          id: SessionId('forked-child'),
+          createdAt: 1,
+          cwd: WORK,
+          parentSession: SessionId('the-parent'),
+          isSeeded: false,
+        }
         await ctx.sessionPersistence.create(m)
         await ctx.sessionPersistence.append(m.id, oneTurnLog())
         const loaded = await ctx.sessionPersistence.load(m.id)
@@ -1441,8 +1552,8 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         await first.ctx.sessionPersistence.append(m.id, oneTurnLog()) // committed 0..5 (balanced)
         // A second turn whose real events are durable but never closed (open turn).
         await first.ctx.sessionPersistence.append(m.id, [
-          { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-          { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } },
+          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+          { type: 'step/start', seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
         ])
       } finally {
         await first.fiber.dispose()
@@ -1468,8 +1579,8 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         // The repair is durable: the next append continues at the balanced length
         // (seq 10) and a reload round-trips identically.
         await second.ctx.sessionPersistence.append(SessionId('torn'), [
-          { type: 'turn/start', seq: 10, time: 9, data: { turn: 3 } },
-          { type: 'turn/end', seq: 11, time: 10, data: { turn: 3, reason: { kind: 'completed' } } },
+          { type: 'turn/start', seq: SessionSeq(10), time: 9, data: { turn: 3 } },
+          { type: 'turn/end', seq: SessionSeq(11), time: 10, data: { turn: 3, reason: { kind: 'completed' } } },
         ])
         const reloaded = await second.ctx.sessionPersistence.load(SessionId('torn'))
         expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
diff --git a/packages/session/session-persistence/tests/persistence.spec.ts b/packages/session/session-persistence/tests/persistence.spec.ts
index afb7ab59b9..dd002882f7 100644
--- a/packages/session/session-persistence/tests/persistence.spec.ts
+++ b/packages/session/session-persistence/tests/persistence.spec.ts
@@ -1,12 +1,22 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, {
+  Session,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+} from '@deepseek-ai/dsh-session'
 import { isJsonValue } from '@deepseek-ai/dsh-util-values'
-import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import type {
+  SessionEvent,
+  SessionHeader,
+  SessionLogOffset as SessionLogOffsetType,
+} from '@deepseek-ai/dsh-session'
 import {
   DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS,
   SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
-  type PersistenceBackend, type SessionPersistenceSnapshot, type StoredPrefix, type StoredSuffix,
+  type PersistenceBackend, type SessionEventSuffix, type SessionInspection, type SessionPersistenceSnapshot,
+  type SessionStorageMetadata, type StoredPrefix, type StoredSuffix,
 } from '../src/index.ts'
 import { runPersistenceContract, meta, oneTurnLog } from './contract.ts'
 import {
@@ -14,10 +24,18 @@ import {
 } from './coordinator-contract.ts'
 
 /** The durable store shape: materialized sessions only (no lazy entries). */
-type MemoryStore = Map<string, { meta: SessionHeader; events: SessionEvent[] }>
+type MemoryStore = Map<string, {
+  meta: SessionHeader
+  inheritedEventCount?: SessionLogOffsetType
+  events: SessionEvent[]
+}>
 
 /** Test-store revision that changes for any metadata or event mutation. */
-function memoryRevision(entry: { meta: SessionHeader; events: SessionEvent[] }): SessionPersistenceRevision {
+function memoryRevision(entry: {
+  meta: SessionHeader
+  inheritedEventCount?: SessionLogOffsetType
+  events: SessionEvent[]
+}): SessionPersistenceRevision {
   return SessionPersistenceRevision(JSON.stringify(entry))
 }
 
@@ -96,8 +114,8 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     return undefined
   }
 
-  create(m: SessionHeader): Promise<void> {
-    return this.coordinator.create(m)
+  create(m: SessionHeader, inheritedEventCount?: SessionLogOffsetType): Promise<void> {
+    return this.coordinator.create(m, inheritedEventCount)
   }
 
   override ensureMaterialized(session: Session): Promise<void> {
@@ -112,20 +130,28 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     return this.coordinator.prepare(id, signal)
   }
 
-  load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    return this.coordinator.load(id).then(loaded => ({ meta: loaded.meta, events: [...loaded.events] }))
+  load(id: SessionId): Promise<SessionInspection> {
+    return this.coordinator.load(id).then(loaded => ({
+      meta: loaded.meta,
+      inheritedEventCount: loaded.inheritedEventCount,
+      events: [...loaded.events],
+    }))
   }
 
-  inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection> {
     return this.coordinator.inspect(id, signal)
-      .then(loaded => ({ meta: loaded.meta, events: [...loaded.events] }))
+      .then(loaded => ({
+        meta: loaded.meta,
+        inheritedEventCount: loaded.inheritedEventCount,
+        events: [...loaded.events],
+      }))
   }
 
   borrowSession(id: SessionId, signal?: AbortSignal): ReturnType<PersistenceCoordinator['borrowSession']> {
     return this.coordinator.borrowSession(id, signal)
   }
 
-  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  readFrom(id: SessionId, fromSeq: SessionLogOffsetType, signal?: AbortSignal): Promise<SessionEventSuffix> {
     return this.coordinator.readFrom(id, fromSeq, signal)
   }
 
@@ -137,6 +163,7 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     if (!entry) return undefined
     return {
       meta: structuredClone(entry.meta),
+      inheritedEventCount: SessionLogOffset(entry.inheritedEventCount ?? 0),
       events: structuredClone(entry.events),
       revision: memoryRevision(entry),
     }
@@ -147,31 +174,45 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     return entry === undefined ? undefined : memoryRevision(entry)
   }
 
-  async appendBatch(m: SessionHeader, events: readonly SessionEvent[], _isMaterialized: boolean): Promise<void> {
+  async appendBatch(
+    storage: SessionStorageMetadata,
+    events: readonly SessionEvent[],
+    _isMaterialized: boolean,
+  ): Promise<void> {
     // Defense-in-depth: the coordinator already validates serializability, but a
     // durable store must reject non-JSON data at its own boundary too.
     for (const e of events) {
       if (!isJsonValue(e.data)) throw new Error(`event "${e.type}" carries non-JSON-serializable data`)
     }
+    const { meta: m, inheritedEventCount } = storage
     const existing = this.store.get(m.id)
     if (!existing) {
       // The coordinator sends the first batch for materialization; later batches append.
-      this.store.set(m.id, { meta: structuredClone(m), events: structuredClone(events) as SessionEvent[] })
+      this.store.set(m.id, {
+        meta: structuredClone(m),
+        inheritedEventCount,
+        events: structuredClone(events) as SessionEvent[],
+      })
     } else {
       existing.events.push(...structuredClone(events) as SessionEvent[])
     }
   }
 
-  materializeHeader(m: SessionHeader): Promise<void> {
-    this.store.set(m.id, { meta: structuredClone(m), events: [] })
+  materializeHeader(storage: SessionStorageMetadata): Promise<void> {
+    const { meta: m, inheritedEventCount } = storage
+    this.store.set(m.id, { meta: structuredClone(m), inheritedEventCount, events: [] })
     return Promise.resolve()
   }
 
-  async commitRepair(m: SessionHeader, _tornMarker: undefined, closers: readonly SessionEvent[]): Promise<void> {
+  async commitRepair(
+    storage: SessionStorageMetadata,
+    _tornMarker: undefined,
+    closers: readonly SessionEvent[],
+  ): Promise<void> {
     // No torn tails in a Map store, so `_tornMarker` is always undefined; only the
     // synthetic closers are appended (the same DELETE+INSERT a DB backend does,
     // minus the truncate).
-    const entry = this.store.get(m.id)
+    const entry = this.store.get(storage.meta.id)
     /* v8 ignore next -- commitRepair only runs for a materialized (stored) session */
     if (!entry) return
     if (closers.length > 0) entry.events.push(...structuredClone(closers) as SessionEvent[])
@@ -203,9 +244,17 @@ class ControlledBackend implements PersistenceBackend<never> {
   beforeAppend?: (attempt: number) => Promise<void>
   beforeLoadStored?: (attempt: number, signal?: AbortSignal) => Promise<void>
   /** When set, the declared seek hook delegates here so readFrom exercises it; unset throws (tests set it first). */
-  seekHook?: (id: SessionId, fromSeq: number, signal?: AbortSignal) => Promise<StoredSuffix | undefined>
+  seekHook?: (
+    id: SessionId,
+    fromSeq: SessionLogOffsetType,
+    signal?: AbortSignal,
+  ) => Promise<StoredSuffix | undefined>
 
-  loadStoredFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined> {
+  loadStoredFrom(
+    id: SessionId,
+    fromSeq: SessionLogOffsetType,
+    signal?: AbortSignal,
+  ): Promise<StoredSuffix | undefined> {
     if (this.seekHook === undefined) throw new Error('seekHook not configured for this test')
     return this.seekHook(id, fromSeq, signal)
   }
@@ -217,6 +266,7 @@ class ControlledBackend implements PersistenceBackend<never> {
     if (entry === undefined) return undefined
     return {
       meta: structuredClone(entry.meta),
+      inheritedEventCount: SessionLogOffset(entry.inheritedEventCount ?? 0),
       events: structuredClone(entry.events),
       revision: memoryRevision(entry),
     }
@@ -228,21 +278,34 @@ class ControlledBackend implements PersistenceBackend<never> {
     return entry === undefined ? undefined : memoryRevision(entry)
   }
 
-  async appendBatch(m: SessionHeader, events: readonly SessionEvent[], _isMaterialized: boolean): Promise<void> {
+  async appendBatch(
+    storage: SessionStorageMetadata,
+    events: readonly SessionEvent[],
+    _isMaterialized: boolean,
+  ): Promise<void> {
+    const { meta: m, inheritedEventCount } = storage
     this.lastAppendedBatch = events
     const attempt = ++this.appendAttempts
     await this.beforeAppend?.(attempt)
     const entry = this.store.get(m.id)
     if (entry === undefined) {
-      this.store.set(m.id, { meta: structuredClone(m), events: structuredClone(events) as SessionEvent[] })
+      this.store.set(m.id, {
+        meta: structuredClone(m),
+        inheritedEventCount,
+        events: structuredClone(events) as SessionEvent[],
+      })
     } else {
       entry.events.push(...structuredClone(events) as SessionEvent[])
     }
   }
 
-  async commitRepair(m: SessionHeader, _tornMarker: undefined, closers: readonly SessionEvent[]): Promise<void> {
+  async commitRepair(
+    storage: SessionStorageMetadata,
+    _tornMarker: undefined,
+    closers: readonly SessionEvent[],
+  ): Promise<void> {
     this.repairAttempts += 1
-    const entry = this.store.get(m.id)
+    const entry = this.store.get(storage.meta.id)
     if (entry !== undefined) entry.events.push(...structuredClone(closers) as SessionEvent[])
   }
 
@@ -445,7 +508,7 @@ describe('PersistenceCoordinator stored identity', () => {
       meta: meta('different'),
       events: [{
         type: 'turn/start',
-        seq: 0,
+        seq: SessionSeq(0),
         time: 1,
         data: { turn: 1 },
       }],
@@ -464,6 +527,35 @@ describe('PersistenceCoordinator stored identity', () => {
     }
   })
 
+  it('rejects an inherited cut beyond the stored prefix before repair', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const id = SessionId('invalid-inherited-cut')
+    backend.store.set(id, {
+      meta: { ...meta(id), isSeeded: true },
+      inheritedEventCount: SessionLogOffset(2),
+      events: [{
+        type: 'turn/start',
+        seq: SessionSeq(0),
+        time: 1,
+        data: { turn: 1 },
+      }],
+    })
+    let coordinator!: PersistenceCoordinator<never>
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+    try {
+      await expect(coordinator.load(id)).rejects.toThrow(/inherited event count exceeds its stored event count/)
+      expect(backend.repairAttempts).toBe(0)
+      expect((coordinator as unknown as CoordinatorInternals).states.size).toBe(0)
+    } finally {
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
   it('reserves a cold id across asynchronous storage repair', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -472,7 +564,7 @@ describe('PersistenceCoordinator stored identity', () => {
     const header = meta(id)
     const start: SessionEvent = {
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
     }
@@ -634,14 +726,14 @@ describe('PersistenceCoordinator session preparations', () => {
     const states = (coordinator as unknown as {
       states: Map<SessionId, {
         meta: SessionHeader
-        cursor: number
+        cursor: SessionLogOffsetType
         materialized: boolean
         owner?: Session
       }>
     }).states
     states.set(id, {
       meta: owner.header,
-      cursor: oneTurnLog().length,
+      cursor: SessionLogOffset(oneTurnLog().length),
       materialized: true,
       owner,
     })
@@ -667,12 +759,12 @@ describe('PersistenceCoordinator session preparations', () => {
     const preparation = await coordinator.prepare(id)
     const preparations = (coordinator as unknown as {
       preparations: {
-        reservationFor: (session: Session) => { state: { cursor: number } } | undefined
+        reservationFor: (session: Session) => { state: { cursor: SessionLogOffsetType } } | undefined
       }
     }).preparations
     const reservation = preparations.reservationFor(preparation.session)
     if (reservation === undefined) throw new Error('test preparation must stay reserved')
-    reservation.state.cursor += 1
+    reservation.state.cursor = SessionLogOffset(reservation.state.cursor + 1)
     const detach = ctx.sessions.enter(preparation.session)
 
     try {
@@ -795,8 +887,8 @@ describe('PersistenceCoordinator session preparations', () => {
     try {
       const first = await coordinator.inspect(id)
       backend.store.get(id)!.events.push(
-        { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-        { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+        { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+        { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
       )
 
       const refreshed = await coordinator.inspect(id)
@@ -824,8 +916,8 @@ describe('PersistenceCoordinator session preparations', () => {
     try {
       const inspected = await coordinator.inspect(id)
       backend.store.get(id)!.events.push(
-        { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-        { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+        { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+        { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
       )
 
       preparation = await coordinator.prepare(id)
@@ -856,8 +948,8 @@ describe('PersistenceCoordinator session preparations', () => {
       const cached = await coordinator.inspect(id)
       preparation = await coordinator.prepare(id)
       backend.store.get(id)!.events.push(
-        { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-        { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+        { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+        { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
       )
 
       await expect(coordinator.inspect(id)).resolves.toBe(cached)
@@ -892,7 +984,7 @@ describe('PersistenceCoordinator session preparations', () => {
       const inspection = coordinator.inspect(id)
       const append = coordinator.append(id, [{
         type: 'turn/start',
-        seq: oneTurnLog().length,
+        seq: SessionSeq(oneTurnLog().length),
         time: 7,
         data: { turn: 2 },
       }])
@@ -924,7 +1016,7 @@ describe('PersistenceCoordinator session preparations', () => {
     try {
       const append = coordinator.append(id, [{
         type: 'turn/start',
-        seq: oneTurnLog().length,
+        seq: SessionSeq(oneTurnLog().length),
         time: 7,
         data: { turn: 2 },
       }])
@@ -961,7 +1053,7 @@ describe('PersistenceCoordinator session preparations', () => {
     try {
       await coordinator.append(id, [{
         type: 'turn/start',
-        seq: oneTurnLog().length,
+        seq: SessionSeq(oneTurnLog().length),
         time: 7,
         data: { turn: 2 },
       }])
@@ -1007,7 +1099,7 @@ describe('PersistenceCoordinator session preparations', () => {
       meta: meta(id),
       events: [{
         type: 'turn/start',
-        seq: 0,
+        seq: SessionSeq(0),
         time: 1,
         data: { turn: 1 },
       }],
@@ -1049,7 +1141,7 @@ describe('PersistenceCoordinator session preparations', () => {
     const id = SessionId('repair-external-append')
     backend.store.set(id, {
       meta: meta(id),
-      events: [{ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }],
+      events: [{ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }],
     })
     const commitRepair = backend.commitRepair.bind(backend)
     vi.spyOn(backend, 'commitRepair').mockImplementation(async (header, tornMarker, closers) => {
@@ -1058,8 +1150,8 @@ describe('PersistenceCoordinator session preparations', () => {
       if (entry === undefined) throw new Error('test repair must keep storage materialized')
       const seq = entry.events.length
       entry.events.push(
-        { type: 'turn/start', seq, time: 3, data: { turn: 2 } },
-        { type: 'turn/end', seq: seq + 1, time: 4, data: { turn: 2, reason: { kind: 'completed' } } },
+        { type: 'turn/start', seq: SessionSeq(seq), time: 3, data: { turn: 2 } },
+        { type: 'turn/end', seq: SessionSeq(seq + 1), time: 4, data: { turn: 2, reason: { kind: 'completed' } } },
       )
     })
     let coordinator!: PersistenceCoordinator<never>
@@ -1094,7 +1186,7 @@ describe('PersistenceCoordinator session preparations', () => {
     const id = SessionId('repair-disappeared')
     backend.store.set(id, {
       meta: meta(id),
-      events: [{ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }],
+      events: [{ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }],
     })
     const commitRepair = backend.commitRepair.bind(backend)
     vi.spyOn(backend, 'commitRepair').mockImplementation(async (header, tornMarker, closers) => {
@@ -1194,7 +1286,7 @@ describe('PersistenceCoordinator session preparations', () => {
       preparation = await coordinator.prepare(id)
       await expect(coordinator.append(id, [{
         type: 'turn/start',
-        seq: oneTurnLog().length,
+        seq: SessionSeq(oneTurnLog().length),
         time: 7,
         data: { turn: 2 },
       }])).rejects.toThrow(/persisted preparation is reserved/)
@@ -1219,13 +1311,17 @@ describe('PersistenceCoordinator seek reads', () => {
     backend.seekHook = async (hookId, fromSeq) => {
       const entry = backend.store.get(hookId)
       if (entry === undefined) return undefined
-      return { meta: structuredClone(entry.meta), events: entry.events.filter(e => e.seq >= fromSeq) }
+      return {
+        meta: structuredClone(entry.meta),
+        inheritedEventCount: SessionLogOffset(entry.inheritedEventCount ?? 0),
+        events: entry.events.filter(e => e.seq >= fromSeq),
+      }
     }
 
     try {
       const assertLegacySuffixUsesWholePrefix = async (
         events: SessionEvent[],
-        fromSeq: number,
+        fromSeq: SessionLogOffsetType,
         firstType: SessionEvent['type'],
       ): Promise<void> => {
         backend.store.set(id, { meta: meta(id), events })
@@ -1235,18 +1331,18 @@ describe('PersistenceCoordinator seek reads', () => {
         expect(backend.loadAttempts).toBe(loadsBefore + 1)
       }
       const legacyMessages = legacyMessageLog()
-      await assertLegacySuffixUsesWholePrefix(legacyMessages, 1, 'user/message')
-      await assertLegacySuffixUsesWholePrefix(legacyMessages, 3, 'assistant/message')
-      await assertLegacySuffixUsesWholePrefix(legacyMessages, 5, 'tool/result')
-      await assertLegacySuffixUsesWholePrefix(preReactLoopLog(), 3, 'user/message')
+      await assertLegacySuffixUsesWholePrefix(legacyMessages, SessionLogOffset(1), 'user/message')
+      await assertLegacySuffixUsesWholePrefix(legacyMessages, SessionLogOffset(3), 'assistant/message')
+      await assertLegacySuffixUsesWholePrefix(legacyMessages, SessionLogOffset(5), 'tool/result')
+      await assertLegacySuffixUsesWholePrefix(preReactLoopLog(), SessionLogOffset(3), 'user/message')
 
       backend.store.set(id, { meta: meta(id), events: legacyMessages })
-      const directCurrent = await coordinator.readFrom(id, 0)
-      backend.store.set(id, { meta: meta(id), events: directCurrent.events })
+      const directCurrent = await coordinator.readFrom(id, SessionLogOffset(0))
+      backend.store.set(id, { meta: meta(id), events: [...directCurrent.events] })
       const loadsBeforeCurrent = backend.loadAttempts
-      await coordinator.readFrom(id, 1)
-      await coordinator.readFrom(id, 3)
-      await coordinator.readFrom(id, 5)
+      await coordinator.readFrom(id, SessionLogOffset(1))
+      await coordinator.readFrom(id, SessionLogOffset(3))
+      await coordinator.readFrom(id, SessionLogOffset(5))
       expect(backend.loadAttempts).toBe(loadsBeforeCurrent)
 
       for (const [type, data] of [
@@ -1259,7 +1355,7 @@ describe('PersistenceCoordinator seek reads', () => {
           events: [{ type, seq: 0, time: 1, data } as unknown as SessionEvent],
         })
         const loadsBefore = backend.loadAttempts
-        await expect(coordinator.readFrom(id, 0)).rejects.toThrow('lacks an identified message')
+        await expect(coordinator.readFrom(id, SessionLogOffset(0))).rejects.toThrow('lacks an identified message')
         expect(backend.loadAttempts).toBe(loadsBefore)
       }
       backend.store.set(id, {
@@ -1269,7 +1365,7 @@ describe('PersistenceCoordinator seek reads', () => {
         } as unknown as SessionEvent],
       })
       const loadsBeforeNullData = backend.loadAttempts
-      expect((await coordinator.readFrom(id, 0)).events[0]?.data).toBeNull()
+      expect((await coordinator.readFrom(id, SessionLogOffset(0))).events[0]?.data).toBeNull()
       expect(backend.loadAttempts).toBe(loadsBeforeNullData)
     } finally {
       await fiber.dispose()
@@ -1565,17 +1661,22 @@ describe('PersistenceCoordinator observation cancellation', () => {
       backend.seekHook = async (hookId, fromSeq) => {
         const entry = backend.store.get(hookId)
         if (entry === undefined) return undefined
-        return { meta: structuredClone(entry.meta), events: entry.events.filter(e => e.seq >= fromSeq) }
+        return {
+          meta: structuredClone(entry.meta),
+          inheritedEventCount: SessionLogOffset(entry.inheritedEventCount ?? 0),
+          events: entry.events.filter(e => e.seq >= fromSeq),
+        }
       }
-      const suffix = await coordinator.readFrom(id, 3)
+      const suffix = await coordinator.readFrom(id, SessionLogOffset(3))
       expect(suffix.events).toEqual(log.slice(3))
       // The hook's `undefined` is the backend contract's not-found result.
-      await expect(coordinator.readFrom(SessionId('missing-seek'), 0)).rejects.toThrow('not found')
+      await expect(coordinator.readFrom(SessionId('missing-seek'), SessionLogOffset(0)))
+        .rejects.toThrow('not found')
 
       // A hook failure with no cancellation in play propagates as-is.
       const hookFailure = new Error('seek backend exploded')
       backend.seekHook = () => Promise.reject(hookFailure)
-      await expect(coordinator.readFrom(id, 0)).rejects.toBe(hookFailure)
+      await expect(coordinator.readFrom(id, SessionLogOffset(0))).rejects.toBe(hookFailure)
 
       // A hook failure after cancellation surfaces the caller's abort reason,
       // not the backend's internal teardown error. The abort fires only once
@@ -1589,7 +1690,7 @@ describe('PersistenceCoordinator observation cancellation', () => {
         await new Promise<void>((resolve) => { signal?.addEventListener('abort', () => { resolve() }, { once: true }) })
         throw new Error('backend teardown after abort')
       }
-      const pending = coordinator.readFrom(id, 0, controller.signal)
+      const pending = coordinator.readFrom(id, SessionLogOffset(0), controller.signal)
       const observed = pending.catch((error: unknown) => error)
       await vi.waitFor(() => { expect(hookEntered).toBe(true) })
       controller.abort(reason)
@@ -1715,7 +1816,7 @@ describe('PersistenceCoordinator retirement', () => {
         await readGate.promise
         return undefined
       }
-      const parked = coordinator.readFrom(id, 0).catch((error: unknown) => error)
+      const parked = coordinator.readFrom(id, SessionLogOffset(0)).catch((error: unknown) => error)
       await readEntered.promise
 
       // First retirement queues behind the gate and stays pending.
@@ -1861,13 +1962,13 @@ describe('PersistenceCoordinator retirement', () => {
       await coordinator.create(meta(id))
       const firstAppend = coordinator.append(id, [{
         type: 'turn/start',
-        seq: 0,
+        seq: SessionSeq(0),
         time: 1,
         data: { turn: 1 },
       }])
       const secondAppend = coordinator.append(id, [{
         type: 'turn/end',
-        seq: 1,
+        seq: SessionSeq(1),
         time: 2,
         data: { turn: 1, reason: { kind: 'completed' } },
       }])
@@ -2001,7 +2102,7 @@ describe('PersistenceCoordinator retirement', () => {
       await coordinator.create(meta(id))
       const append = coordinator.append(id, [{
         type: 'turn/start',
-        seq: 0,
+        seq: SessionSeq(0),
         time: 1,
         data: { turn: 1 },
       }])
@@ -2034,7 +2135,11 @@ describe('SessionPersistence service registration', () => {
     await ctx.sessionPersistence.ensureMaterialized(session)
 
     await expect(ctx.sessionPersistence.list()).resolves.toEqual([session.header])
-    await expect(ctx.sessionPersistence.load(session.id)).resolves.toEqual({ meta: session.header, events: [] })
+    await expect(ctx.sessionPersistence.load(session.id)).resolves.toEqual({
+      meta: session.header,
+      inheritedEventCount: SessionLogOffset(0),
+      events: [],
+    })
     await ctx.fiber.dispose()
   })
 
@@ -2063,11 +2168,11 @@ describe('SessionPersistence service registration', () => {
     await ctx.plugin(SessionStore)
     const endings: SessionEvent[] = [
       {
-        type: 'turn/end', seq: 5, time: 6,
+        type: 'turn/end', seq: SessionSeq(5), time: 6,
         data: { turn: 1, reason: { kind: 'aborted', reason: { kind: 'user' } } },
       },
       {
-        type: 'turn/end', seq: 5, time: 6,
+        type: 'turn/end', seq: SessionSeq(5), time: 6,
         data: { turn: 1, reason: { kind: 'error', error: { message: 'failed', code: 'UNKNOWN' } } },
       },
     ]
diff --git a/packages/session/session-persistence/tests/write-behind.spec.ts b/packages/session/session-persistence/tests/write-behind.spec.ts
index df445e0cf7..8b33dc34d0 100644
--- a/packages/session/session-persistence/tests/write-behind.spec.ts
+++ b/packages/session/session-persistence/tests/write-behind.spec.ts
@@ -1,9 +1,9 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session'
 import { SessionWriteBehind } from '../src/write-behind.ts'
 
 /** Minimal ordered event fixture; batching does not interpret event vocabulary. */
-function event(seq: number): SessionEvent<'turn/start'> {
+function event(seq: SessionSeq): SessionEvent<'turn/start'> {
   return {
     type: 'turn/start',
     seq,
@@ -25,12 +25,12 @@ describe('SessionWriteBehind', () => {
       write: async (events) => { batches.push(structuredClone(events) as SessionEvent[]) },
       reportBackgroundFailure: vi.fn(),
     })
-    const first = event(0)
+    const first = event(SessionSeq(0))
 
     controller.enqueue(first)
     first.data.turn = 99
     await vi.advanceTimersByTimeAsync(150)
-    controller.enqueue(event(1))
+    controller.enqueue(event(SessionSeq(1)))
     await vi.advanceTimersByTimeAsync(49)
     expect(batches).toEqual([])
 
@@ -51,10 +51,10 @@ describe('SessionWriteBehind', () => {
       reportBackgroundFailure: vi.fn(),
     })
 
-    controller.enqueue(event(0))
+    controller.enqueue(event(SessionSeq(0)))
     for (let seq = 1; seq < 20; seq += 1) {
       await vi.advanceTimersByTimeAsync(10)
-      controller.enqueue(event(seq))
+      controller.enqueue(event(SessionSeq(seq)))
     }
     expect(batches).toEqual([])
 
@@ -76,14 +76,14 @@ describe('SessionWriteBehind', () => {
       reportBackgroundFailure: vi.fn(),
     })
 
-    controller.enqueue(event(0))
+    controller.enqueue(event(SessionSeq(0)))
     const first = controller.flush()
     const second = controller.flush()
     expect(second).toBe(first)
     await Promise.resolve()
     expect(batches).toEqual([[0]])
 
-    controller.enqueue(event(1))
+    controller.enqueue(event(SessionSeq(1)))
     gate.resolve(true)
     await first
     expect(batches).toEqual([[0], [1]])
@@ -101,7 +101,7 @@ describe('SessionWriteBehind', () => {
     })
 
     const barrier = controller.flush()
-    controller.enqueue(event(0))
+    controller.enqueue(event(SessionSeq(0)))
     await barrier
     expect(batches).toEqual([])
     expect(vi.getTimerCount()).toBe(1)
@@ -124,10 +124,10 @@ describe('SessionWriteBehind', () => {
       reportBackgroundFailure: vi.fn(),
     })
 
-    controller.enqueue(event(0))
+    controller.enqueue(event(SessionSeq(0)))
     await vi.advanceTimersByTimeAsync(200)
     expect(batches).toEqual([[0]])
-    controller.enqueue(event(1))
+    controller.enqueue(event(SessionSeq(1)))
     await vi.advanceTimersByTimeAsync(200)
     expect(batches).toEqual([[0]])
 
@@ -150,9 +150,9 @@ describe('SessionWriteBehind', () => {
       reportBackgroundFailure: vi.fn(),
     })
 
-    controller.enqueue(event(0))
+    controller.enqueue(event(SessionSeq(0)))
     await vi.advanceTimersByTimeAsync(200)
-    controller.enqueue(event(1))
+    controller.enqueue(event(SessionSeq(1)))
     await vi.advanceTimersByTimeAsync(50)
     gate.resolve(true)
     await vi.advanceTimersByTimeAsync(0)
@@ -180,14 +180,14 @@ describe('SessionWriteBehind', () => {
       reportBackgroundFailure: report,
     })
 
-    controller.enqueue(event(0))
+    controller.enqueue(event(SessionSeq(0)))
     await vi.advanceTimersByTimeAsync(200)
     expect(report).toHaveBeenCalledWith(failure)
     expect(controller.hasWork).toBe(true)
     await vi.advanceTimersByTimeAsync(1_000)
     expect(batches).toEqual([[0]])
 
-    controller.enqueue(event(1))
+    controller.enqueue(event(SessionSeq(1)))
     await vi.advanceTimersByTimeAsync(199)
     expect(batches).toEqual([[0]])
     await vi.advanceTimersByTimeAsync(1)
@@ -212,7 +212,7 @@ describe('SessionWriteBehind', () => {
       reportBackgroundFailure: report,
     })
 
-    controller.enqueue(event(0))
+    controller.enqueue(event(SessionSeq(0)))
     await vi.advanceTimersByTimeAsync(200)
     const first = controller.flush()
     const second = controller.flush()
@@ -239,12 +239,12 @@ describe('SessionWriteBehind', () => {
       reportBackgroundFailure: report,
     })
 
-    controller.enqueue(event(0))
+    controller.enqueue(event(SessionSeq(0)))
     await expect(controller.flush()).rejects.toBe(failure)
     expect(report).not.toHaveBeenCalled()
     expect(controller.hasWork).toBe(true)
 
-    controller.enqueue(event(1))
+    controller.enqueue(event(SessionSeq(1)))
     await vi.advanceTimersByTimeAsync(200)
     expect(batches).toEqual([[0], [0, 1]])
     await controller.flush()
@@ -264,7 +264,7 @@ describe('SessionWriteBehind', () => {
       reportBackgroundFailure: vi.fn(),
     })
 
-    for (let seq = 0; seq < batchSize; seq += 1) controller.enqueue(event(seq))
+    for (let seq = 0; seq < batchSize; seq += 1) controller.enqueue(event(SessionSeq(seq)))
     await expect(controller.flush()).rejects.toBe(failure)
     expect(controller.hasWork).toBe(true)
 
diff --git a/packages/session/session-projection-cache/README.i18n.yaml b/packages/session/session-projection-cache/README.i18n.yaml
index 3bab27725d..e4fe8490a2 100644
--- a/packages/session/session-projection-cache/README.i18n.yaml
+++ b/packages/session/session-projection-cache/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/session/session-projection-cache/README.md
-README.md: 9d6c7fef235013dbeb72d7b3d8fbf7e8a3beb8ba
-README.zh.md: b3fbc8a4ef48687a7c353dc4c00a5b731011979d
+README.md: 51b9d86724af96304cf09a5c7c1b61b7394d336a
+README.zh.md: bb84b67bdde678884fd4f2be1b14b2161da8c2a0
diff --git a/packages/session/session-projection-cache/README.md b/packages/session/session-projection-cache/README.md
index 9d6c7fef23..51b9d86724 100644
--- a/packages/session/session-projection-cache/README.md
+++ b/packages/session/session-projection-cache/README.md
@@ -58,11 +58,11 @@ Three mandatory points always write: session creation persists the seed-derived
 
 ### Reading cached values
 
-`cachedSnapshot(meta)` synchronously serves client values from the storage domain's in-memory tables with zero I/O. It accepts only an identity-matching record and version- and schema-matching keys, then returns a `{ asOfSeq, values }` cut at the lowest served-row watermark. It returns `undefined` for an unknown id, unrelated lifecycle, absent or foreign record document, or no usable rows. `coldSnapshot(meta, events)` accepts a complete ordered log, skips the checkpointed prefix while folding, and refreshes the record without reading the persistence layer itself.
+`cachedSnapshot(meta, inheritedEventCount)` synchronously serves client values from the storage domain's in-memory tables with zero I/O. It accepts only an identity-matching record and version- and schema-matching keys, then returns a `{ asOfSeq, values }` cut at the lowest served-row watermark. An unseeded listing knows that its cut is zero; a seeded header-only listing does not know the numeric cut and must skip this fast path until an authoritative body read supplies it. `coldSnapshot(meta, inheritedEventCount, events)` accepts the exact cut with a complete ordered log, skips the checkpointed prefix while folding, and refreshes the record without reading persistence itself.
 
 ### What the cache guarantees
 
-The log leads and the cache follows: a live checkpoint flushes the session's buffered events durably before the cache row lands, so a crash can leave the cache behind the log but never ahead of it. Reads and writes share the storage domain's coherent in-memory state; the per-unit write chain mutates memory only after durability. Each version-stamped record must match the live unit schema and session header identity (`createdAt`, `cwd`), so malformed, stale, or unrelated records read as absent. The JSON backend stores each record at `<root>/session_projcache/sessions/<id>.json` in an owner-only directory tree.
+The log leads and the cache follows: a live checkpoint flushes the session's buffered events durably before the cache row lands, so a crash can leave the cache behind the log but never ahead of it. Reads and writes share the storage domain's coherent in-memory state; the per-unit write chain mutates memory only after durability. Each version-stamped record must match the live unit schema and complete lifecycle identity (`createdAt`, `cwd`, `isSeeded`, and `inheritedEventCount`), so a row initialized under one fork cut cannot seed another. The JSON backend stores each record at `<root>/session_projcache/sessions/<id>.json` in an owner-only directory tree.
 
 -----
 
diff --git a/packages/session/session-projection-cache/README.zh.md b/packages/session/session-projection-cache/README.zh.md
index b3fbc8a4ef..bb84b67bdd 100644
--- a/packages/session/session-projection-cache/README.zh.md
+++ b/packages/session/session-projection-cache/README.zh.md
@@ -58,11 +58,11 @@ kind: "package-reference"
 
 ### 读取缓存值
 
-`cachedSnapshot(meta)` 以零 I/O 从存储域的内存表同步提供客户端值。它只接受身份匹配的记录以及版本和 schema 均匹配的 key，再按所服务行的最低水位返回 `{ asOfSeq, values }` 切面。对于未知 id、无关生命周期、缺失或外来的记录文档，或没有可用行的情况，它返回 `undefined`。`coldSnapshot(meta, events)` 接受完整有序日志，在折叠时跳过已检查点化的前缀，并在自身不读取持久化层的情况下刷新记录。
+`cachedSnapshot(meta, inheritedEventCount)` 以零 I/O 从存储域的内存表同步提供客户端值。它只接受身份匹配的记录以及版本和 schema 均匹配的 key，再按所服务行的最低水位返回 `{ asOfSeq, values }` 切面。未 seeded 的列表知道切点为零；仅 header 的 seeded 列表不知道数字切点，必须跳过该快速路径，直到权威正文读取提供它。`coldSnapshot(meta, inheritedEventCount, events)` 接受精确切点与完整有序日志，在折叠时跳过已检查点化的前缀，并在自身不读取持久化层的情况下刷新记录。
 
 ### 缓存保证什么
 
-日志领先，缓存跟随：实时检查点先把会话的缓冲事件持久化，然后才保存缓存记录。因此崩溃可能让缓存落后于日志，但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态；逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 schema 与会话 header 身份（`createdAt`、`cwd`），因此畸形、陈旧或无关的记录都会读作不存在。JSON 后端把每条记录存于仅所有者可访问的 `<root>/session_projcache/sessions/<id>.json` 目录树中。
+日志领先，缓存跟随：实时检查点先把会话的缓冲事件持久化，然后才保存缓存记录。因此崩溃可能让缓存落后于日志，但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态；逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 schema 与完整生命周期身份（`createdAt`、`cwd`、`isSeeded` 和 `inheritedEventCount`），因此在一个 fork 切点下初始化的行不能播种另一个切点。JSON 后端把每条记录存于仅所有者可访问的 `<root>/session_projcache/sessions/<id>.json` 目录树中。
 
 -----
 
diff --git a/packages/session/session-projection-cache/src/index.ts b/packages/session/session-projection-cache/src/index.ts
index 4e067241da..35bf5d9eed 100644
--- a/packages/session/session-projection-cache/src/index.ts
+++ b/packages/session/session-projection-cache/src/index.ts
@@ -19,7 +19,14 @@
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { snapshotJsonValue } from '@deepseek-ai/dsh-util-values'
-import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionHeader,
+  SessionId,
+  SessionSeqCursor,
+} from '@deepseek-ai/dsh-session'
 import type {
   ProjectionCheckpoint,
   ProjectionSnapshot,
@@ -121,15 +128,18 @@ export class SessionProjectionCache extends Service {
    * paths (the history tail baseline) supersede these values whenever a
    * session is actually opened.
    * @param meta - the listed session's header (identity witness; no log read).
+   * @param inheritedEventCount - exact inherited prefix length that completes
+   * the checkpoint identity.
    * @param keys - optional projection keys required by the caller's audience.
    * @returns the cut (`asOfSeq` = lowest served-row watermark), or
    *   `undefined` when no usable row exists for this lifecycle.
    */
   cachedSnapshot(
     meta: SessionHeader,
+    inheritedEventCount: SessionLogOffset,
     keys?: readonly Extract<keyof SessionProjectionMap, string>[],
   ): ProjectionSnapshot | undefined {
-    const record = this.recordFor(meta.id, identityOf(meta))
+    const record = this.recordFor(meta.id, identityOf(meta, inheritedEventCount))
     if (record === undefined) return undefined
     const values = this.ctx.sessionProjections.viewCheckpoint(record.rows, keys)
     const servedKeys = Object.keys(values)
@@ -137,7 +147,15 @@ export class SessionProjectionCache extends Service {
     // The block carries ONE cut: the lowest served watermark is the seq every
     // value is at least current as of (under-claiming is safe under
     // higher-seq-wins; over-claiming would let a stale value outrank pushes).
-    const asOfSeq = Math.min(...servedKeys.map(key => (record.rows[key] as { seq: number }).seq))
+    let asOfSeq: SessionSeqCursor | undefined
+    for (const key of servedKeys) {
+      const row = record.rows[key]
+      if (row !== undefined && (asOfSeq === undefined || row.seq < asOfSeq)) {
+        asOfSeq = row.seq
+      }
+    }
+    /* v8 ignore next -- A nonempty checkpoint view contains a stored row for every returned key. */
+    if (asOfSeq === undefined) return undefined
     return { asOfSeq, values }
   }
 
@@ -147,25 +165,31 @@ export class SessionProjectionCache extends Service {
    * advances every unit to the observation cut. No checkpoint is written
    * because the logical observation may contain recovery events not yet durable.
    * @param session - exact unpublished Session retained by persistence.
-   * @param meta - observed lifecycle header.
    * @param events - exact logical event prefix represented by the observation.
    * @returns all projection values at the event cut.
    */
   hydratePrepared(
     session: Session,
-    meta: SessionHeader,
     events: readonly SessionEvent[],
   ): ProjectionSnapshot {
-    const record = this.recordFor(meta.id, identityOf(meta))
+    const record = this.recordFor(
+      session.id,
+      identityOf(session.header, session.inheritedEventCount),
+    )
     if (record === undefined) {
-      return this.ctx.sessionProjections.hydrate(session, {}, events, 0)
+      return this.ctx.sessionProjections.hydrate(session, {}, events, SessionLogOffset(0))
     }
     try {
-      return this.ctx.sessionProjections.hydrate(session, record.rows, events, 0)
+      return this.ctx.sessionProjections.hydrate(
+        session,
+        record.rows,
+        events,
+        SessionLogOffset(0),
+      )
     } catch {
       // Cached rows are disposable derived data. Retry from the exact log so a
       // stale schema cannot make a valid Session unreadable.
-      return this.ctx.sessionProjections.hydrate(session, {}, events, 0)
+      return this.ctx.sessionProjections.hydrate(session, {}, events, SessionLogOffset(0))
     }
   }
 
@@ -189,7 +213,11 @@ export class SessionProjectionCache extends Service {
     // already gone; persistence's own retirement drain covers that path and
     // any residual overreach is caught by the cold read's anchored floor.
     if (this.ctx.sessions.get(session.id) === session) await this.ctx.sessions.flush(session)
-    await this.put(session.id, identityOf(session.header), rows)
+    await this.put(
+      session.id,
+      identityOf(session.header, session.inheritedEventCount),
+      rows,
+    )
   }
 
   /**
@@ -201,14 +229,26 @@ export class SessionProjectionCache extends Service {
    * The caller supplies the complete log in seq order: this service never
    * consults the persistence layer.
    * @param meta - the stored session header (identity witness).
+   * @param inheritedEventCount - exact inherited prefix length for projection initialization and identity.
    * @param events - the session's complete log, in seq order.
    * @returns the projection cut at the log end.
    */
-  coldSnapshot(meta: SessionHeader, events: readonly SessionEvent[]): ProjectionSnapshot {
-    const restored = this.ctx.sessionProjections.restore(this.recordFor(meta.id, identityOf(meta))?.rows ?? {}, events, 0, meta)
+  coldSnapshot(
+    meta: SessionHeader,
+    inheritedEventCount: SessionLogOffset,
+    events: readonly SessionEvent[],
+  ): ProjectionSnapshot {
+    const identity = identityOf(meta, inheritedEventCount)
+    const restored = this.ctx.sessionProjections.restore(
+      this.recordFor(meta.id, identity)?.rows ?? {},
+      events,
+      SessionLogOffset(0),
+      meta,
+      inheritedEventCount,
+    )
     // Refresh the row so the next cold read seeds from it; fail-soft and
     // fire-and-forget — a failed write-back only costs a longer tail replay.
-    void this.put(meta.id, identityOf(meta), restored.checkpoint).catch((error: unknown) => {
+    void this.put(meta.id, identity, restored.checkpoint).catch((error: unknown) => {
       this.ctx.logger.warn(`session projection cache: cold-read write-back for "${meta.id}" failed (cache stays stale): ${String(error)}`)
     })
     return restored.snapshot
@@ -311,13 +351,28 @@ export class SessionProjectionCache extends Service {
 }
 
 /** Project a header onto the identity fields a record is bound to. */
-function identityOf(header: SessionHeader): CheckpointIdentity {
-  return { createdAt: header.createdAt, ...header.cwd === undefined ? {} : { cwd: header.cwd } }
+function identityOf(
+  header: SessionHeader,
+  inheritedEventCount: SessionLogOffset,
+): CheckpointIdentity {
+  const cut = SessionLogOffset(inheritedEventCount)
+  if (!header.isSeeded && cut !== 0) {
+    throw new Error('unseeded projection-cache identity inherited event count must be 0')
+  }
+  return {
+    createdAt: header.createdAt,
+    ...header.cwd === undefined ? {} : { cwd: header.cwd },
+    isSeeded: header.isSeeded,
+    inheritedEventCount: cut,
+  }
 }
 
 /** Whether a stored record's bound identity names the caller's lifecycle. */
 function identityMatches(stored: CheckpointIdentity, expected: CheckpointIdentity): boolean {
-  return stored.createdAt === expected.createdAt && stored.cwd === expected.cwd
+  return stored.createdAt === expected.createdAt
+    && stored.cwd === expected.cwd
+    && stored.isSeeded === expected.isSeeded
+    && stored.inheritedEventCount === expected.inheritedEventCount
 }
 
 export default SessionProjectionCache
diff --git a/packages/session/session-projection-cache/src/spec.ts b/packages/session/session-projection-cache/src/spec.ts
index 8564ec710c..35351917a5 100644
--- a/packages/session/session-projection-cache/src/spec.ts
+++ b/packages/session/session-projection-cache/src/spec.ts
@@ -11,7 +11,8 @@
  */
 
 import { z } from 'zod'
-import type { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import type { SessionId, SessionSeqCursor } from '@deepseek-ai/dsh-session'
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
 
 /**
@@ -24,7 +25,8 @@ import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
  */
 export const checkpointRow = z.object({
   ver: z.number().int().nonnegative(),
-  seq: z.number().int().gte(-1),
+  seq: z.number().int().gte(-1).transform((value): SessionSeqCursor =>
+    value === -1 ? -1 : SessionSeq(value)),
   val: z.json(),
 })
 
@@ -40,6 +42,8 @@ export const checkpointRow = z.object({
 export const checkpointIdentity = z.object({
   createdAt: z.number().int().nonnegative(),
   cwd: z.string().optional(),
+  isSeeded: z.boolean(),
+  inheritedEventCount: z.number().int().nonnegative().transform(SessionLogOffset),
 })
 
 /** The identity fields a record is bound to, inferred from {@link checkpointIdentity}. */
@@ -68,7 +72,7 @@ export type CheckpointRecord = z.infer<typeof checkpointRecord>
  */
 export const projectionCacheDomainSpec = defineDomain({
   name: 'session_projcache',
-  version: 4,
+  version: 5,
   layout: 'per-record',
   tables: { sessions: domainTable<SessionId, CheckpointRecord>(checkpointRecord) },
 })
diff --git a/packages/session/session-projection-cache/tests/cache.spec.ts b/packages/session/session-projection-cache/tests/cache.spec.ts
index 6fe271871e..bfdca18567 100644
--- a/packages/session/session-projection-cache/tests/cache.spec.ts
+++ b/packages/session/session-projection-cache/tests/cache.spec.ts
@@ -16,7 +16,12 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
 import { z } from 'zod'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, {
+  Session,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+} from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
@@ -80,7 +85,7 @@ const recordPath = (root: string, id: Session['id']): string =>
 
 /** Header shape for cachedSnapshot calls. */
 const headerOf = (id: SessionId, createdAt = 0, cwd?: string) =>
-  ({ version: 0, id, createdAt, ...cwd === undefined ? {} : { cwd } })
+  ({ version: 0, id, createdAt, isSeeded: false, ...cwd === undefined ? {} : { cwd } })
 
 interface HarnessOptions {
   root?: string
@@ -134,7 +139,11 @@ async function seedRecord(
   root: string,
   id: string,
   rows: CheckpointRecord['rows'],
-  identity: CheckpointRecord['identity'] = { createdAt: 0 },
+  identity: CheckpointRecord['identity'] = {
+    createdAt: 0,
+    isSeeded: false,
+    inheritedEventCount: SessionLogOffset(0),
+  },
 ): Promise<void> {
   const path = recordPath(root, SessionId(id))
   await mkdir(dirname(path), { recursive: true })
@@ -294,36 +303,77 @@ describe('SessionProjectionCache write policy', () => {
 })
 
 describe('SessionProjectionCache listing read', () => {
+  it('refuses a checkpoint created for a different inherited cut', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-'))
+    roots.push(root)
+    const id = SessionId('cut-identity')
+    await seedRecord(
+      root,
+      id,
+      { 'cache-test/marks': { ver: 1, seq: SessionSeq(1), val: { marks: ['seed'] } } },
+      {
+        createdAt: 0,
+        isSeeded: true,
+        inheritedEventCount: SessionLogOffset(2),
+      },
+    )
+    const { cache } = await harness({ root })
+    const seededHeader = { ...headerOf(id), isSeeded: true }
+
+    expect(cache.cachedSnapshot(seededHeader, SessionLogOffset(2))?.values['cache-test/marks'])
+      .toEqual({ marks: ['seed'] })
+    expect(cache.cachedSnapshot(seededHeader, SessionLogOffset(1))).toBeUndefined()
+    expect(() => cache.cachedSnapshot(headerOf(id), SessionLogOffset(1)))
+      .toThrow('unseeded projection-cache identity inherited event count must be 0')
+  })
+
+  it('serves a creation-time checkpoint at the before-first-event cursor', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-'))
+    roots.push(root)
+    await seedRecord(root, 'before-first-event', {
+      'cache-test/marks': { ver: 1, seq: -1, val: null },
+    })
+    const { cache } = await harness({ root })
+
+    expect(cache.cachedSnapshot(headerOf(SessionId('before-first-event')), SessionLogOffset(0)))
+      .toEqual({ asOfSeq: -1, values: { 'cache-test/marks': { marks: [] } } })
+  })
+
   it('keeps host-only checkpoint state out of cached wire snapshots', async () => {
     const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-'))
     roots.push(root)
     await seedRecord(root, 'host-state', {
-      'cache-test/marks': { ver: 1, seq: 4, val: { marks: ['wire'] } },
-      'cache-test/secret': { ver: 1, seq: 4, val: 'private prompt text' },
+      'cache-test/marks': { ver: 1, seq: SessionSeq(4), val: { marks: ['wire'] } },
+      'cache-test/secret': { ver: 1, seq: SessionSeq(4), val: 'private prompt text' },
     })
     const { ctx, cache } = await harness({ root })
     ctx.sessionProjections.register(secretUnit)
     const header = headerOf(SessionId('host-state'))
 
-    expect(cache.cachedSnapshot(header)).toEqual({
+    expect(cache.cachedSnapshot(header, SessionLogOffset(0))).toEqual({
       asOfSeq: 4,
       values: { 'cache-test/marks': { marks: ['wire'] } },
     })
-    expect(JSON.stringify(cache.cachedSnapshot(header))).not.toContain('private prompt text')
+    expect(JSON.stringify(cache.cachedSnapshot(header, SessionLogOffset(0))))
+      .not.toContain('private prompt text')
   })
 
   it('serves identity-matching rows with the cut watermark and refuses unrelated ones', async () => {
     const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-'))
     roots.push(root)
-    await seedRecord(root, 'listed', { 'cache-test/marks': { ver: 1, seq: 4, val: { marks: ['t'] } } })
+    await seedRecord(root, 'listed', {
+      'cache-test/marks': { ver: 1, seq: SessionSeq(4), val: { marks: ['t'] } },
+    })
     const { cache } = await harness({ root })
     const id = SessionId('listed')
     // Matching header: values plus the watermark the client seeds under.
-    expect(cache.cachedSnapshot(headerOf(id))).toEqual({ asOfSeq: 4, values: { 'cache-test/marks': { marks: ['t'] } } })
+    expect(cache.cachedSnapshot(headerOf(id), SessionLogOffset(0)))
+      .toEqual({ asOfSeq: 4, values: { 'cache-test/marks': { marks: ['t'] } } })
     // A recreated id (different createdAt): the record is unrelated — no block.
-    expect(cache.cachedSnapshot(headerOf(id, 777))).toBeUndefined()
+    expect(cache.cachedSnapshot(headerOf(id, 777), SessionLogOffset(0))).toBeUndefined()
     // Unknown id: no block.
-    expect(cache.cachedSnapshot(headerOf(SessionId('never-cached')))).toBeUndefined()
+    expect(cache.cachedSnapshot(headerOf(SessionId('never-cached')), SessionLogOffset(0)))
+      .toBeUndefined()
   })
 
   it('returns undefined when the stored record is version-mismatched', async () => {
@@ -334,10 +384,14 @@ describe('SessionProjectionCache listing read', () => {
     await mkdir(dirname(path), { recursive: true })
     await writeFile(path, JSON.stringify({
       version: projectionCacheDomainSpec.version + 1,
-      record: { identity: { createdAt: 0 }, rows: { 'cache-test/marks': { ver: 1, seq: 4, val: { marks: ['old'] } } } },
+      record: {
+        identity: { createdAt: 0, isSeeded: false, inheritedEventCount: 0 },
+        rows: { 'cache-test/marks': { ver: 1, seq: 4, val: { marks: ['old'] } } },
+      },
     }))
     const { cache } = await harness({ root })
-    expect(cache.cachedSnapshot(headerOf(SessionId('all-stale')))).toBeUndefined()
+    expect(cache.cachedSnapshot(headerOf(SessionId('all-stale')), SessionLogOffset(0)))
+      .toBeUndefined()
   })
 
   it('returns undefined when every stored row is version-mismatched', async () => {
@@ -345,20 +399,31 @@ describe('SessionProjectionCache listing read', () => {
     roots.push(root)
     // A current document whose rows all fail the live unit's stateVersion:
     // the listing view is empty, so no block is served.
-    await seedRecord(root, 'row-stale', { 'cache-test/marks': { ver: 99, seq: 4, val: { marks: ['old'] } } })
+    await seedRecord(root, 'row-stale', {
+      'cache-test/marks': { ver: 99, seq: SessionSeq(4), val: { marks: ['old'] } },
+    })
     const { cache } = await harness({ root })
-    expect(cache.cachedSnapshot(headerOf(SessionId('row-stale')))).toBeUndefined()
+    expect(cache.cachedSnapshot(headerOf(SessionId('row-stale')), SessionLogOffset(0)))
+      .toBeUndefined()
   })
 
   it('binds identity on cwd too: a matching cwd serves, a moved session does not', async () => {
     const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-'))
     roots.push(root)
-    await seedRecord(root, 'homed', { 'cache-test/marks': { ver: 1, seq: 2, val: { marks: ['w'] } } }, { createdAt: 0, cwd: '/work' })
+    await seedRecord(root, 'homed', {
+      'cache-test/marks': { ver: 1, seq: SessionSeq(2), val: { marks: ['w'] } },
+    }, {
+      createdAt: 0,
+      cwd: '/work',
+      isSeeded: false,
+      inheritedEventCount: SessionLogOffset(0),
+    })
     const { cache } = await harness({ root })
     const id = SessionId('homed')
-    expect(cache.cachedSnapshot(headerOf(id, 0, '/work'))?.values['cache-test/marks']).toEqual({ marks: ['w'] })
-    expect(cache.cachedSnapshot(headerOf(id, 0, '/elsewhere'))).toBeUndefined()
-    expect(cache.cachedSnapshot(headerOf(id, 0))).toBeUndefined()
+    expect(cache.cachedSnapshot(headerOf(id, 0, '/work'), SessionLogOffset(0))?.values['cache-test/marks'])
+      .toEqual({ marks: ['w'] })
+    expect(cache.cachedSnapshot(headerOf(id, 0, '/elsewhere'), SessionLogOffset(0))).toBeUndefined()
+    expect(cache.cachedSnapshot(headerOf(id, 0), SessionLogOffset(0))).toBeUndefined()
   })
 
   it('returns undefined for a malformed record document (refold from the log on the caller side)', async () => {
@@ -368,7 +433,8 @@ describe('SessionProjectionCache listing read', () => {
     await mkdir(dirname(path), { recursive: true })
     await writeFile(path, 'not json at all')
     const { cache } = await harness({ root })
-    expect(cache.cachedSnapshot(headerOf(SessionId('malformed')))).toBeUndefined()
+    expect(cache.cachedSnapshot(headerOf(SessionId('malformed')), SessionLogOffset(0)))
+      .toBeUndefined()
   })
 })
 
@@ -376,12 +442,22 @@ describe('SessionProjectionCache cold-read seeding', () => {
   /** One session's event log: turn/start, one mark per group, turn/end. */
   const storedLog = (marks: string[][]): SessionEvent[] => {
     const events: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 } },
     ]
     for (const m of marks) {
-      events.push({ type: 'cache-test/mark', seq: events.length, time: events.length, data: { marks: m } })
+      events.push({
+        type: 'cache-test/mark',
+        seq: SessionSeq(events.length),
+        time: events.length,
+        data: { marks: m },
+      })
     }
-    events.push({ type: 'turn/end', seq: events.length, time: events.length, data: { turn: 1, reason: { kind: 'completed' } } })
+    events.push({
+      type: 'turn/end',
+      seq: SessionSeq(events.length),
+      time: events.length,
+      data: { turn: 1, reason: { kind: 'completed' } },
+    })
     return events
   }
 
@@ -391,10 +467,10 @@ describe('SessionProjectionCache cold-read seeding', () => {
     // Records land on disk before the domain opens, so the in-memory table
     // picks them up at init.
     await seedRecord(root, 'prepared-seeded', {
-      'cache-test/marks': { ver: 1, seq: 1, val: { marks: ['cached'] } },
+      'cache-test/marks': { ver: 1, seq: SessionSeq(1), val: { marks: ['cached'] } },
     })
     await seedRecord(root, 'prepared-fallback', {
-      'cache-test/marks': { ver: 1, seq: 1, val: { marks: 'malformed' } },
+      'cache-test/marks': { ver: 1, seq: SessionSeq(1), val: { marks: 'malformed' } },
     })
     const { cache } = await harness({ root })
     const events = storedLog([['fresh']])
@@ -402,7 +478,7 @@ describe('SessionProjectionCache cold-read seeding', () => {
     // A matching row hydrates the prepared Session without a persistence read.
     const seeded = headerOf(SessionId('prepared-seeded'))
     const seededSession = Session.create(seeded.id, events, seeded)
-    expect(cache.hydratePrepared(seededSession, seeded, events)).toEqual({
+    expect(cache.hydratePrepared(seededSession, events)).toEqual({
       asOfSeq: 2,
       values: { 'cache-test/marks': { marks: ['cached'] } },
     })
@@ -411,7 +487,7 @@ describe('SessionProjectionCache cold-read seeding', () => {
     // exact log so a valid Session stays readable.
     const fallback = headerOf(SessionId('prepared-fallback'))
     const fallbackSession = Session.create(fallback.id, events, fallback)
-    expect(cache.hydratePrepared(fallbackSession, fallback, events)).toEqual({
+    expect(cache.hydratePrepared(fallbackSession, events)).toEqual({
       asOfSeq: 2,
       values: { 'cache-test/marks': { marks: ['fresh'] } },
     })
@@ -419,7 +495,7 @@ describe('SessionProjectionCache cold-read seeding', () => {
     // No row at all: hydrate from init over the exact log.
     const bare = headerOf(SessionId('prepared-bare'))
     const bareSession = Session.create(bare.id, events, bare)
-    expect(cache.hydratePrepared(bareSession, bare, events)).toEqual({
+    expect(cache.hydratePrepared(bareSession, events)).toEqual({
       asOfSeq: 2,
       values: { 'cache-test/marks': { marks: ['fresh'] } },
     })
@@ -430,8 +506,12 @@ describe('SessionProjectionCache cold-read seeding', () => {
     roots.push(root)
     // A cached row covering the prefix through seq 2 (three applies folded).
     await seedRecord(root, 'cold-snap', {
-      'cache-test/count': { ver: 1, seq: 2, val: 3 },
-    }, { createdAt: 9 })
+      'cache-test/count': { ver: 1, seq: SessionSeq(2), val: 3 },
+    }, {
+      createdAt: 9,
+      isSeeded: false,
+      inheritedEventCount: SessionLogOffset(0),
+    })
     const { cache, ctx } = await harness({ root })
     const apply = vi.fn((_state: number, _event: SessionEvent) => 1)
     ctx.sessionProjections.register({
@@ -443,9 +523,9 @@ describe('SessionProjectionCache cold-read seeding', () => {
     } satisfies ProjectionDefinition<'cache-test/count', number>)
     const meta = headerOf(SessionId('cold-snap'), 9)
     const events = Array.from({ length: 5 }, (_, seq) => ({
-      type: 'cache-test/mark', seq, time: seq, data: { marks: [`m${seq}`] },
+      type: 'cache-test/mark', seq: SessionSeq(seq), time: seq, data: { marks: [`m${seq}`] },
     })) as SessionEvent[]
-    const snapshot = cache.coldSnapshot(meta, events)
+    const snapshot = cache.coldSnapshot(meta, SessionLogOffset(0), events)
     // The full log was traversed, but the fold applied only seqs 3 and 4.
     expect(apply).toHaveBeenCalledTimes(2)
     expect(apply.mock.calls.map(call => call[1].seq)).toEqual([3, 4])
@@ -459,7 +539,7 @@ describe('SessionProjectionCache cold-read seeding', () => {
     // No cached row yet: the first cold read folds from init over the full
     // log and creates the cache row (the `?? {}` seed path).
     const fresh = headerOf(SessionId('cold-fresh'), 10)
-    cache.coldSnapshot(fresh, events)
+    cache.coldSnapshot(fresh, SessionLogOffset(0), events)
     expect(apply).toHaveBeenCalledTimes(7) // 2 tail + 5 full
     await vi.waitFor(async () => {
       expect((await storedRows(root, fresh.id))?.['cache-test/count']?.seq).toBe(4)
@@ -483,7 +563,7 @@ describe('SessionProjectionCache cold-read seeding', () => {
     // fail; the cold read itself still succeeds and never throws.
     const meta = headerOf(SessionId('cold-fail'))
     await mkdir(recordPath(root, meta.id), { recursive: true })
-    expect(ctx.sessionProjectionCache.coldSnapshot(meta, [])).toBeDefined()
+    expect(ctx.sessionProjectionCache.coldSnapshot(meta, SessionLogOffset(0), [])).toBeDefined()
     // The failed write-back is fire-and-forget: poll for the warn instead of
     // assuming a fixed settle window (slow runners exceed it).
     await vi.waitFor(() => {
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index 1a7555e5c6..b740065e58 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/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/session/session-projection/README.md
-README.md: 85c4813cee8807912b1fe3abb25412408c824df6
-README.zh.md: ba2f8f71258dc86a09bcfc5c4c3b5a5b16c127ff
+README.md: 79902cca815da1ee93916ece82cf89bb3624a3a8
+README.zh.md: 749934419cfc94a83abcb59013776fbb8b55ac19
diff --git a/packages/session/session-projection/README.md b/packages/session/session-projection/README.md
index 85c4813cee..79902cca81 100644
--- a/packages/session/session-projection/README.md
+++ b/packages/session/session-projection/README.md
@@ -40,7 +40,7 @@ const definition = {
   key: 'todo',
   stateSchema: todoStateSchema,
   stateVersion: 1,
-  init: () => ({ items: [] }),
+  init: (_header, _inheritedEventCount) => ({ items: [] }),
   apply: (state, event) => event.type === 'todo/upsert'
     ? { items: event.data.items }
     : state,
@@ -51,7 +51,7 @@ const definition = {
 }
 ```
 
-`apply` must be synchronous and must return the same state reference for events that do not concern the unit — an unchanged reference means zero downstream work. The registry compares consecutive raw `wire.view` results with `Object.is`; an object or array view must reuse its reference to suppress publication across internal-only state changes, while a structurally equal new object is still a change. A state-carrying log event must carry the complete post-change state, never a bare delta.
+`init(header, inheritedEventCount)` receives both lightweight metadata and the exact fork-inherited cut; it must not infer that cut from `firstLiveSeq` or `session/end-seed`. `apply` must be synchronous and must return the same state reference for events that do not concern the unit — an unchanged reference means zero downstream work. The registry compares consecutive raw `wire.view` results with `Object.is`; an object or array view must reuse its reference to suppress publication across internal-only state changes, while a structurally equal new object is still a change. A state-carrying log event must carry the complete post-change state, never a bare delta.
 
 ### Register and read
 
@@ -64,7 +64,7 @@ const { asOfSeq, values } = ctx.sessionProjections.snapshot(session)
 
 ### Persisted checkpoints
 
-Every unit's state is checkpointed — client-visible and host-only alike — through `checkpoint(session)`, and the sibling [session-projection-cache](../session-projection-cache/README.md) persists those checkpoints so cold reads skip full log loads. `restoreFloor` and `restore` implement the read recipe (cached state plus a forward tail replay) without a live session.
+Every unit's state is checkpointed — client-visible and host-only alike — through `checkpoint(session)`, and the sibling [session-projection-cache](../session-projection-cache/README.md) persists those checkpoints so cold reads skip full log loads. Checkpoint watermarks use `SessionSeqCursor` (`-1` for an empty log), while replay starts use `SessionLogOffset`; `restoreFloor` and `restore` implement the read recipe without conflating an existing event with a log gap.
 
 -----
 
diff --git a/packages/session/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
index ba2f8f7125..749934419c 100644
--- a/packages/session/session-projection/README.zh.md
+++ b/packages/session/session-projection/README.zh.md
@@ -40,7 +40,7 @@ const definition = {
   key: 'todo',
   stateSchema: todoStateSchema,
   stateVersion: 1,
-  init: () => ({ items: [] }),
+  init: (_header, _inheritedEventCount) => ({ items: [] }),
   apply: (state, event) => event.type === 'todo/upsert'
     ? { items: event.data.items }
     : state,
@@ -51,7 +51,7 @@ const definition = {
 }
 ```
 
-`apply` 必须同步，且对与单元无关的事件必须返回同一个状态引用——引用不变意味着零下游工作。注册表用 `Object.is` 比较相邻的 `wire.view` 原始结果；对象或数组 view 若要在仅内部 state 变化时抑制发布，就必须复用引用，结构相同的新对象仍算变化。携带状态的日志事件必须携带变更后的完整状态，绝不携带裸增量。
+`init(header, inheritedEventCount)` 同时接收轻量元数据与精确的 fork 继承切点；它不得从 `firstLiveSeq` 或 `session/end-seed` 推断该切点。`apply` 必须同步，且对与单元无关的事件必须返回同一个状态引用——引用不变意味着零下游工作。注册表用 `Object.is` 比较相邻的 `wire.view` 原始结果；对象或数组 view 若要在仅内部 state 变化时抑制发布，就必须复用引用，结构相同的新对象仍算变化。携带状态的日志事件必须携带变更后的完整状态，绝不携带裸增量。
 
 ### 注册与读取
 
@@ -64,7 +64,7 @@ const { asOfSeq, values } = ctx.sessionProjections.snapshot(session)
 
 ### 持久检查点
 
-每个单元的状态都会被检查点化——client-visible 与 host-only 一视同仁——通过 `checkpoint(session)`，同级包 [session-projection-cache](../session-projection-cache/README.zh.md) 持久化这些检查点，使冷读跳过全量日志加载。`restoreFloor` 与 `restore` 在无活动会话的情况下实现读取配方（缓存状态加正向尾部回放）。
+每个单元的状态都会被检查点化——client-visible 与 host-only 一视同仁——通过 `checkpoint(session)`，同级包 [session-projection-cache](../session-projection-cache/README.zh.md) 持久化这些检查点，使冷读跳过全量日志加载。检查点水位使用 `SessionSeqCursor`（空日志为 `-1`），回放起点使用 `SessionLogOffset`；`restoreFloor` 与 `restore` 在无活动会话的情况下实现读取配方，且不会混淆已有事件与日志间隙。
 
 -----
 
diff --git a/packages/session/session-projection/src/index.ts b/packages/session/session-projection/src/index.ts
index 488cd72914..edfa4820b3 100644
--- a/packages/session/session-projection/src/index.ts
+++ b/packages/session/session-projection/src/index.ts
@@ -19,7 +19,13 @@
 
 import { Context, Service } from '@deepseek-ai/cordis'
 import type { ZodType } from 'zod'
-import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import type {
+  Session,
+  SessionEvent,
+  SessionHeader,
+  SessionSeqCursor,
+} from '@deepseek-ai/dsh-session'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -50,9 +56,10 @@ export interface ProjectionDefinition<
   /**
    * State for the empty log and its immutable Session metadata.
    * @param header - immutable metadata for the Session being projected.
+   * @param inheritedEventCount - exact fork-inherited prefix length.
    * @returns the initial state.
    */
-  init(header: SessionHeader): NoInfer<S>
+  init(header: SessionHeader, inheritedEventCount: SessionLogOffset): NoInfer<S>
   /**
    * Pure transition: previous state + one committed event → next state. A
    * unit uninterested in an event MUST return the same state reference — an
@@ -94,7 +101,7 @@ export type ProjectionChangeListener = (
   session: Session,
   key: Extract<keyof SessionProjectionMap, string>,
   value: unknown,
-  seq: number,
+  seq: SessionSeq,
 ) => void
 
 /**
@@ -104,7 +111,7 @@ export type ProjectionChangeListener = (
  */
 export interface ProjectionSnapshot {
   /** Seq of the last event the values reflect; -1 for an empty log. */
-  asOfSeq: number
+  asOfSeq: SessionSeqCursor
   /** Whole current client value per registered key. */
   values: Partial<SessionProjectionMap>
 }
@@ -121,7 +128,7 @@ export interface ProjectionCheckpointRow {
   /** The registering unit's `stateVersion` at fold time. */
   ver: number
   /** Seq of the last event folded into `val`; -1 for the empty log. */
-  seq: number
+  seq: SessionSeqCursor
   /** The unit's internal state — plain JSON per the unit contract. */
   val: unknown
 }
@@ -133,7 +140,7 @@ export type ProjectionCheckpoint = Record<string, ProjectionCheckpointRow>
 interface ErasedDefinition {
   key: string
   stateSchema: { parse(value: unknown): unknown }
-  init(header: SessionHeader): unknown
+  init(header: SessionHeader, inheritedEventCount: SessionLogOffset): unknown
   apply(state: unknown, event: SessionEvent): unknown
   wire: { viewSchema: { parse(value: unknown): unknown }; view(state: unknown): unknown } | undefined
   stateVersion: number
@@ -143,7 +150,7 @@ interface ErasedDefinition {
 interface UnitCell {
   state: unknown
   /** Seq of the last event passed through `apply` (regardless of change). */
-  observedSeq: number
+  observedSeq: SessionSeqCursor
   /** `[previousView, currentView]`; undefined slots mean no cached comparison. */
   readonly views: [unknown, unknown]
 }
@@ -166,6 +173,11 @@ interface Registration {
   refs: number
 }
 
+/** Convert a log offset to the inclusive cursor immediately before it. */
+function cursorBefore(offset: SessionLogOffset): SessionSeqCursor {
+  return offset === 0 ? -1 : SessionSeq(offset - 1)
+}
+
 /**
  * `ctx.sessionProjections`: the projection unit table and its drive. The
  * service subscribes to `session/event` once; every committed event passes
@@ -199,7 +211,7 @@ export class SessionProjectionRegistry extends Service {
       for (const registration of this.registrations.values()) {
         if (registration.cells.has(session)) continue
         registration.cells.set(session, {
-          state: registration.def.init(session.header),
+          state: registration.def.init(session.header, session.inheritedEventCount),
           observedSeq: -1,
           views: [undefined, undefined],
         })
@@ -248,7 +260,7 @@ export class SessionProjectionRegistry extends Service {
     const erased: ErasedDefinition = {
       key: definition.key,
       stateSchema: definition.stateSchema,
-      init: header => definition.init(header),
+      init: (header, inheritedEventCount) => definition.init(header, inheritedEventCount),
       apply: (state, event) => definition.apply(state as S, event),
       wire: wire === undefined
         ? undefined
@@ -336,7 +348,7 @@ export class SessionProjectionRegistry extends Service {
       const cell = this.cellFor(registration, session)
       values[registration.def.key] = this.viewCell(registration, cell)
     }
-    return { asOfSeq: session.seq - 1, values }
+    return { asOfSeq: cursorBefore(session.seq), values }
   }
 
   /**
@@ -352,7 +364,7 @@ export class SessionProjectionRegistry extends Service {
     keys?: readonly Extract<keyof SessionProjectionMap, string>[],
   ): ProjectionSnapshot | undefined {
     const values: Record<string, unknown> = {}
-    let asOfSeq: number | undefined
+    let asOfSeq: SessionSeqCursor | undefined
     const selected = keys === undefined ? undefined : new Set<string>(keys)
     for (const registration of this.registrations.values()) {
       if (registration.def.wire === undefined) continue
@@ -360,9 +372,9 @@ export class SessionProjectionRegistry extends Service {
       const cell = registration.cells.get(session)
       if (cell === undefined) continue
       values[registration.def.key] = this.viewCell(registration, cell)
-      asOfSeq = asOfSeq === undefined
-        ? cell.observedSeq
-        : Math.min(asOfSeq, cell.observedSeq)
+      if (asOfSeq === undefined || cell.observedSeq < asOfSeq) {
+        asOfSeq = cell.observedSeq
+      }
     }
     return asOfSeq === undefined ? undefined : { asOfSeq, values }
   }
@@ -410,7 +422,7 @@ export class SessionProjectionRegistry extends Service {
    *   when no unit is registered (no read needed — {@link restore} would
    *   serve empty values regardless).
    */
-  restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined {
+  restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined {
     let floor: number | undefined
     for (const registration of this.registrations.values()) {
       const row = checkpoint[registration.def.key]
@@ -419,7 +431,7 @@ export class SessionProjectionRegistry extends Service {
         : 0
       floor = floor === undefined ? need : Math.min(floor, need)
     }
-    return floor === undefined ? undefined : Math.max(floor - 1, 0)
+    return floor === undefined ? undefined : SessionLogOffset(Math.max(floor - 1, 0))
   }
 
   /**
@@ -475,6 +487,7 @@ export class SessionProjectionRegistry extends Service {
    * @param events - the stored events with `seq >= baseSeq`, in seq order.
    * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
    * @param header - immutable metadata for the Session being restored.
+   * @param inheritedEventCount - exact fork-inherited prefix length supplied to unit initialization.
    * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
    *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
    *   refreshed checkpoint rows at that cut, ready for a durable write-back.
@@ -482,11 +495,13 @@ export class SessionProjectionRegistry extends Service {
   restore(
     checkpoint: ProjectionCheckpoint,
     events: readonly SessionEvent[],
-    baseSeq: number,
+    baseSeq: SessionLogOffset,
     header: SessionHeader,
+    inheritedEventCount: SessionLogOffset,
   ):
   { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint } {
-    const endSeq = events.at(-1)?.seq ?? baseSeq - 1
+    const endSeq: SessionSeqCursor = events.at(-1)?.seq ?? cursorBefore(baseSeq)
+    const beforeBase = cursorBefore(baseSeq)
     const values: Record<string, unknown> = {}
     const refreshed: ProjectionCheckpoint = {}
     for (const registration of this.registrations.values()) {
@@ -494,7 +509,7 @@ export class SessionProjectionRegistry extends Service {
       const row = checkpoint[def.key]
       const usable = row !== undefined
         && row.ver === def.stateVersion
-        && row.seq >= baseSeq - 1
+        && row.seq >= beforeBase
         && row.seq <= endSeq
       if (!usable && baseSeq > 0) {
         throw new Error(
@@ -502,12 +517,14 @@ export class SessionProjectionRegistry extends Service {
           + 'its checkpoint row is missing, version-mismatched, or beyond the supplied log end; re-read from seq 0',
         )
       }
-      let state = usable ? def.stateSchema.parse(row.val) : def.init(header)
-      const from = usable ? row.seq : baseSeq - 1
+      let state = usable
+        ? def.stateSchema.parse(row.val)
+        : def.init(header, inheritedEventCount)
+      const from = usable ? row.seq : beforeBase
       const startIndex = from - baseSeq + 1
       for (let index = startIndex; index < events.length; index++) {
         const event = events[index]
-        const expectedSeq = baseSeq + index
+        const expectedSeq = SessionSeq(baseSeq + index)
         if (event === undefined || event.seq !== expectedSeq) {
           throw new Error(`session projection ${JSON.stringify(def.key)} cannot restore across missing seq ${String(expectedSeq)}`)
         }
@@ -536,9 +553,9 @@ export class SessionProjectionRegistry extends Service {
     session: Session,
     checkpoint: ProjectionCheckpoint,
     events: readonly SessionEvent[],
-    baseSeq: number,
+    baseSeq: SessionLogOffset,
   ): ProjectionSnapshot {
-    const endSeq = events.at(-1)?.seq ?? baseSeq - 1
+    const endSeq: SessionSeqCursor = events.at(-1)?.seq ?? cursorBefore(baseSeq)
     let complete = true
     for (const registration of this.registrations.values()) {
       const current = registration.cells.get(session)
@@ -556,7 +573,13 @@ export class SessionProjectionRegistry extends Service {
       }
       return { asOfSeq: endSeq, values }
     }
-    const restored = this.restore(checkpoint, events, baseSeq, session.header)
+    const restored = this.restore(
+      checkpoint,
+      events,
+      baseSeq,
+      session.header,
+      session.inheritedEventCount,
+    )
     for (const registration of this.registrations.values()) {
       const row = restored.checkpoint[registration.def.key]
       if (row === undefined) continue
@@ -580,9 +603,10 @@ export class SessionProjectionRegistry extends Service {
   private buildCell(
     def: ErasedDefinition,
     header: SessionHeader,
+    inheritedEventCount: SessionLogOffset,
     events: readonly SessionEvent[],
   ): UnitCell {
-    let state = def.init(header)
+    let state = def.init(header, inheritedEventCount)
     for (const event of events) state = def.apply(state, event)
     return { state, observedSeq: (events.at(-1)?.seq ?? -1), views: [undefined, undefined] }
   }
@@ -591,10 +615,15 @@ export class SessionProjectionRegistry extends Service {
   private cellFor(registration: Registration, session: Session): UnitCell {
     let cell = registration.cells.get(session)
     if (cell === undefined) {
-      cell = this.buildCell(registration.def, session.header, session.snapshotEvents())
+      cell = this.buildCell(
+        registration.def,
+        session.header,
+        session.inheritedEventCount,
+        session.snapshotEvents(),
+      )
       registration.cells.set(session, cell)
     } else {
-      this.advanceCell(registration.def, cell, session, session.seq - 1)
+      this.advanceCell(registration.def, cell, session, cursorBefore(session.seq))
     }
     return cell
   }
@@ -604,11 +633,11 @@ export class SessionProjectionRegistry extends Service {
     def: ErasedDefinition,
     cell: UnitCell,
     session: Session,
-    throughSeq: number,
+    throughSeq: SessionSeqCursor,
   ): void {
     if (cell.observedSeq >= throughSeq) return
     for (let seq = cell.observedSeq + 1; seq <= throughSeq; seq++) {
-      const event = session.eventAt(seq)
+      const event = session.eventAt(SessionSeq(seq))
       if (event === undefined || event.seq !== seq) {
         throw new Error(`session projection ${JSON.stringify(def.key)} cannot advance across missing seq ${String(seq)}`)
       }
@@ -618,7 +647,7 @@ export class SessionProjectionRegistry extends Service {
         cell.views[1] = undefined
       }
       cell.state = next
-      cell.observedSeq = seq
+      cell.observedSeq = SessionSeq(seq)
     }
   }
 
@@ -630,10 +659,20 @@ export class SessionProjectionRegistry extends Service {
       if (cell === undefined) {
         // Late build mid-stream: fold history before this event (seq = log
         // index, so the prefix slice is exact), then take the normal gate.
-        cell = this.buildCell(registration.def, session.header, session.snapshotEvents(0, event.seq))
+        cell = this.buildCell(
+          registration.def,
+          session.header,
+          session.inheritedEventCount,
+          session.snapshotEvents(SessionLogOffset(0), SessionLogOffset(event.seq)),
+        )
         registration.cells.set(session, cell)
       } else {
-        this.advanceCell(registration.def, cell, session, event.seq - 1)
+        this.advanceCell(
+          registration.def,
+          cell,
+          session,
+          event.seq === 0 ? -1 : SessionSeq(event.seq - 1),
+        )
       }
       const previousState = cell.state
       const next = registration.def.apply(previousState, event)
diff --git a/packages/session/session-projection/tests/registry.spec.ts b/packages/session/session-projection/tests/registry.spec.ts
index b5e32f41c4..91106860c4 100644
--- a/packages/session/session-projection/tests/registry.spec.ts
+++ b/packages/session/session-projection/tests/registry.spec.ts
@@ -10,8 +10,13 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { z } from 'zod'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import SessionStore, {
+  Session,
+  SessionId,
+  SessionLogOffset,
+  SessionSeq,
+} from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 
@@ -20,6 +25,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
     'test/marks': MarksState
     'test/count': number
     'test/stable-view': StableViewState
+    'test/cut': number
   }
 
   interface SessionProjectionMap {
@@ -47,6 +53,7 @@ const RESTORE_HEADER: SessionHeader = {
   version: 0,
   id: SessionId('projection-restore'),
   createdAt: 0,
+  isSeeded: false,
 }
 /** Whole-value unit: latest test/mark event wins; unrelated events return the same reference. */
 const marksUnit = (): Omit<ProjectionDefinition<'test/marks', MarksState>, 'wire'>
@@ -92,6 +99,15 @@ const stableViewUnit = (
   stateVersion: 1,
 }) satisfies ProjectionDefinition<'test/stable-view', StableViewState>
 
+/** Host-only unit whose initial state proves the exact inherited cut. */
+const cutUnit = (): ProjectionDefinition<'test/cut', number> => ({
+  key: 'test/cut',
+  stateSchema: z.number().int().nonnegative(),
+  init: (_header, inheritedEventCount) => inheritedEventCount,
+  apply: state => state,
+  stateVersion: 1,
+})
+
 async function harness(): Promise<{ ctx: Context; session: Session }> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -144,6 +160,45 @@ function sequenceName(sequence: readonly number[], prefix: string): string {
 }
 
 describe('SessionProjectionRegistry drive', () => {
+  it('supplies the exact inherited cut to live, restored, and hydrated projection initialization', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionProjectionRegistry)
+    ctx.sessionProjections.register(cutUnit())
+    const inherited: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    const session = ctx.sessions.create(SessionId('projection-cut'), {
+      seed: inherited,
+      inheritedEventCount: SessionLogOffset(inherited.length),
+      meta: { isSeeded: true },
+    })
+
+    expect(ctx.sessionProjections.stateOf(session, 'test/cut')).toBe(inherited.length)
+    const restored = ctx.sessionProjections.restore(
+      {},
+      inherited,
+      SessionLogOffset(0),
+      session.header,
+      session.inheritedEventCount,
+    )
+    expect(restored.checkpoint['test/cut']?.val).toBe(inherited.length)
+    const prepared = Session.create(
+      SessionId('projection-cut-prepared'),
+      inherited,
+      { ...session.header, id: SessionId('projection-cut-prepared') },
+      session.inheritedEventCount,
+    )
+    expect(ctx.sessionProjections.hydrate(
+      prepared,
+      {},
+      inherited,
+      SessionLogOffset(0),
+    ).asOfSeq).toBe(1)
+    expect(ctx.sessionProjections.stateOf(prepared, 'test/cut')).toBe(inherited.length)
+  })
+
   it('drives a registered unit over committed events and snapshots the current value', async () => {
     const { ctx, session } = await harness()
     ctx.sessionProjections.register(marksUnit())
@@ -175,7 +230,7 @@ describe('SessionProjectionRegistry drive', () => {
   it('notifies onChanged with the validated view and the causing seq, and skips same-reference applies', async () => {
     const { ctx, session } = await harness()
     ctx.sessionProjections.register(marksUnit())
-    const seen: { key: string; value: unknown; seq: number; sessionId: string }[] = []
+    const seen: { key: string; value: unknown; seq: SessionSeq; sessionId: string }[] = []
     ctx.sessionProjections.onChanged((changedSession, key, value, seq) => {
       seen.push({ key, value, seq, sessionId: String(changedSession.id) })
     })
@@ -516,13 +571,13 @@ describe('SessionProjectionRegistry drive', () => {
     // Lowest usable watermark is count's 5 → the anchored tail starts AT 5
     // (one below the first needed seq 6), so the read proves seq 5 still exists.
     expect(ctx.sessionProjections.restoreFloor({
-      'test/marks': { ver: 1, seq: 10, val: { marks: [] } },
-      'test/count': { ver: 1, seq: 5, val: 6 },
+      'test/marks': { ver: 1, seq: SessionSeq(10), val: { marks: [] } },
+      'test/count': { ver: 1, seq: SessionSeq(5), val: 6 },
     })).toBe(5)
     // A version-mismatched row forces that key back to a full refold.
     expect(ctx.sessionProjections.restoreFloor({
-      'test/marks': { ver: 2, seq: 10, val: { marks: [] } },
-      'test/count': { ver: 1, seq: 5, val: 6 },
+      'test/marks': { ver: 2, seq: SessionSeq(10), val: { marks: [] } },
+      'test/count': { ver: 1, seq: SessionSeq(5), val: 6 },
     })).toBe(0)
     // A fresh (-1) row still needs the whole tail from 0.
     expect(ctx.sessionProjections.restoreFloor({
@@ -536,26 +591,27 @@ describe('SessionProjectionRegistry drive', () => {
     ctx.sessionProjections.register(marksUnit())
     ctx.sessionProjections.register(countUnit())
     const tail: SessionEvent[] = [
-      { type: 'test/mark', seq: 3, time: 3, data: { marks: ['new'] } },
-      { type: 'turn/end', seq: 4, time: 4, data: { turn: 1, reason: { kind: 'completed' } } },
+      { type: 'test/mark', seq: SessionSeq(3), time: 3, data: { marks: ['new'] } },
+      { type: 'turn/end', seq: SessionSeq(4), time: 4, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
     // marks row usable (watermark 2, tail starts at 3); count row mismatched — but
     // a mismatch with baseSeq > 0 cannot silently refold: it throws for a re-read.
     expect(() => ctx.sessionProjections.restore({
-      'test/marks': { ver: 1, seq: 2, val: { marks: ['old'] } },
-      'test/count': { ver: 99, seq: 2, val: 3 },
-    }, tail, 3, RESTORE_HEADER)).toThrow(/re-read from seq 0/)
+      'test/marks': { ver: 1, seq: SessionSeq(2), val: { marks: ['old'] } },
+      'test/count': { ver: 99, seq: SessionSeq(2), val: 3 },
+    }, tail, SessionLogOffset(3), RESTORE_HEADER, SessionLogOffset(0)))
+      .toThrow(/re-read from seq 0/)
     // The full-log re-read (baseSeq 0) refolds the mismatched key from init.
     const full: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } },
-      { type: 'test/mark', seq: 1, time: 1, data: { marks: ['old'] } },
-      { type: 'test/mark', seq: 2, time: 2, data: { marks: ['old', '2'] } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 } },
+      { type: 'test/mark', seq: SessionSeq(1), time: 1, data: { marks: ['old'] } },
+      { type: 'test/mark', seq: SessionSeq(2), time: 2, data: { marks: ['old', '2'] } },
       ...tail,
     ]
     const { snapshot, checkpoint } = ctx.sessionProjections.restore({
-      'test/marks': { ver: 1, seq: 2, val: { marks: ['old', '2'] } },
-      'test/count': { ver: 99, seq: 2, val: 3 },
-    }, full, 0, RESTORE_HEADER)
+      'test/marks': { ver: 1, seq: SessionSeq(2), val: { marks: ['old', '2'] } },
+      'test/count': { ver: 99, seq: SessionSeq(2), val: 3 },
+    }, full, SessionLogOffset(0), RESTORE_HEADER, SessionLogOffset(0))
     expect(snapshot.asOfSeq).toBe(4)
     expect(snapshot.values['test/marks']).toEqual({ marks: ['new'] })
     expect('test/count' in snapshot.values).toBe(false)
@@ -569,14 +625,20 @@ describe('SessionProjectionRegistry drive', () => {
     ctx.sessionProjections.register(marksUnit())
     ctx.sessionProjections.register(countUnit())
     const rows = {
-      'test/marks': { ver: 1, seq: 4, val: { marks: ['done'] } },
-      'test/count': { ver: 1, seq: 2, val: 3 },
+      'test/marks': { ver: 1, seq: SessionSeq(4), val: { marks: ['done'] } },
+      'test/count': { ver: 1, seq: SessionSeq(2), val: 3 },
     }
     const tail: SessionEvent[] = [
-      { type: 'turn/start', seq: 3, time: 3, data: { turn: 2 } },
-      { type: 'turn/end', seq: 4, time: 4, data: { turn: 2, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(3), time: 3, data: { turn: 2 } },
+      { type: 'turn/end', seq: SessionSeq(4), time: 4, data: { turn: 2, reason: { kind: 'completed' } } },
     ]
-    const { snapshot, checkpoint } = ctx.sessionProjections.restore(rows, tail, 3, RESTORE_HEADER)
+    const { snapshot, checkpoint } = ctx.sessionProjections.restore(
+      rows,
+      tail,
+      SessionLogOffset(3),
+      RESTORE_HEADER,
+      SessionLogOffset(0),
+    )
     expect(snapshot.asOfSeq).toBe(4)
     // marks already covers the tail (watermark 4): nothing re-applied.
     expect(snapshot.values['test/marks']).toEqual({ marks: ['done'] })
@@ -586,9 +648,9 @@ describe('SessionProjectionRegistry drive', () => {
 
     // Empty tail (checkpoint is current): the cut sits at baseSeq - 1.
     const { snapshot: current, checkpoint: currentCheckpoint } = ctx.sessionProjections.restore({
-      'test/marks': { ver: 1, seq: 4, val: { marks: ['done'] } },
-      'test/count': { ver: 1, seq: 4, val: 5 },
-    }, [], 5, RESTORE_HEADER)
+      'test/marks': { ver: 1, seq: SessionSeq(4), val: { marks: ['done'] } },
+      'test/count': { ver: 1, seq: SessionSeq(4), val: 5 },
+    }, [], SessionLogOffset(5), RESTORE_HEADER, SessionLogOffset(0))
     expect(current.asOfSeq).toBe(4)
     expect('test/count' in current.values).toBe(false)
     expect(currentCheckpoint['test/count']).toEqual({ ver: 1, seq: 4, val: 5 })
@@ -599,8 +661,8 @@ describe('SessionProjectionRegistry drive', () => {
     ctx.sessionProjections.register(marksUnit())
     ctx.sessionProjections.register(countUnit())
     const values = ctx.sessionProjections.viewCheckpoint({
-      'test/marks': { ver: 1, seq: 4, val: { marks: ['stored'] } },
-      'test/count': { ver: 99, seq: 4, val: 5 }, // mismatched: absent
+      'test/marks': { ver: 1, seq: SessionSeq(4), val: { marks: ['stored'] } },
+      'test/count': { ver: 99, seq: SessionSeq(4), val: 5 }, // mismatched: absent
     })
     expect(values['test/marks']).toEqual({ marks: ['stored'] })
     expect('test/count' in values).toBe(false)
@@ -612,14 +674,20 @@ describe('SessionProjectionRegistry drive', () => {
     ctx.sessionProjections.register(marksUnit())
     ctx.sessionProjections.register(countUnit())
     const rows = {
-      'test/marks': { ver: 1, seq: 4, val: { marks: ['stored'] } },
-      'test/count': { ver: 1, seq: 4, val: 5 },
+      'test/marks': { ver: 1, seq: SessionSeq(4), val: { marks: ['stored'] } },
+      'test/count': { ver: 1, seq: SessionSeq(4), val: 5 },
     }
     expect(ctx.sessionProjections.viewCheckpoint(rows)).toEqual({
       'test/marks': { marks: ['stored'] },
     })
 
-    const restored = ctx.sessionProjections.restore(rows, [], 5, RESTORE_HEADER)
+    const restored = ctx.sessionProjections.restore(
+      rows,
+      [],
+      SessionLogOffset(5),
+      RESTORE_HEADER,
+      SessionLogOffset(0),
+    )
     expect(restored.snapshot.values).toEqual({
       'test/marks': { marks: ['stored'] },
     })
@@ -630,35 +698,59 @@ describe('SessionProjectionRegistry drive', () => {
     const { ctx } = await harness()
     ctx.sessionProjections.register(marksUnit())
     const drifted = {
-      'test/marks': { ver: 1, seq: 2, val: { marks: 'not-an-array' } },
+      'test/marks': { ver: 1, seq: SessionSeq(2), val: { marks: 'not-an-array' } },
     }
 
     expect(ctx.sessionProjections.viewCheckpoint(drifted)).toEqual({})
-    expect(() => ctx.sessionProjections.restore(drifted, [], 3, RESTORE_HEADER)).toThrow()
+    expect(() => ctx.sessionProjections.restore(
+      drifted,
+      [],
+      SessionLogOffset(3),
+      RESTORE_HEADER,
+      SessionLogOffset(0),
+    )).toThrow()
   })
 
   it('restore rejects a row claiming events past the supplied log end (shrunk log ⇒ re-read)', async () => {
     const { ctx } = await harness()
     ctx.sessionProjections.register(countUnit())
-    const rows = { 'test/count': { ver: 1, seq: 9, val: 10 } }
+    const rows = { 'test/count': { ver: 1, seq: SessionSeq(9), val: 10 } }
     // The anchored floor sits ON the watermark, so the tail read must return
     // at least seq 9 from an intact log…
     const floor = ctx.sessionProjections.restoreFloor(rows)
     expect(floor).toBe(9)
     // …an intact log serves the anchor event and the checkpoint stands as-is.
-    const anchor: SessionEvent = { type: 'turn/end', seq: 9, time: 9, data: { turn: 2, reason: { kind: 'completed' } } }
-    const anchored = ctx.sessionProjections.restore(rows, [anchor], 9, RESTORE_HEADER)
+    const anchor: SessionEvent = { type: 'turn/end', seq: SessionSeq(9), time: 9, data: { turn: 2, reason: { kind: 'completed' } } }
+    const anchored = ctx.sessionProjections.restore(
+      rows,
+      [anchor],
+      SessionLogOffset(9),
+      RESTORE_HEADER,
+      SessionLogOffset(0),
+    )
     expect(anchored.snapshot.values).toEqual({})
     expect(anchored.checkpoint['test/count']).toEqual({ ver: 1, seq: 9, val: 10 })
     // …while a log crash-repaired down to fewer events returns an empty tail:
     // the row overreaches the proven end and a tail read cannot fix this key.
-    expect(() => ctx.sessionProjections.restore(rows, [], 9, RESTORE_HEADER)).toThrow(/re-read from seq 0/)
+    expect(() => ctx.sessionProjections.restore(
+      rows,
+      [],
+      SessionLogOffset(9),
+      RESTORE_HEADER,
+      SessionLogOffset(0),
+    )).toThrow(/re-read from seq 0/)
     // The full re-read discards the overreaching row and refolds from init.
     const events: SessionEvent[] = [
-      { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } },
-      { type: 'turn/end', seq: 1, time: 1, data: { turn: 1, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 1, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
-    const { snapshot, checkpoint } = ctx.sessionProjections.restore(rows, events, 0, RESTORE_HEADER)
+    const { snapshot, checkpoint } = ctx.sessionProjections.restore(
+      rows,
+      events,
+      SessionLogOffset(0),
+      RESTORE_HEADER,
+      SessionLogOffset(0),
+    )
     expect(snapshot.asOfSeq).toBe(1)
     expect(snapshot.values).toEqual({})
     expect(checkpoint['test/count']).toEqual({ ver: 1, seq: 1, val: 2 })
diff --git a/packages/session/session-telemetry-otel/tests/otel.spec.ts b/packages/session/session-telemetry-otel/tests/otel.spec.ts
index 822203abb8..0888cf2d05 100644
--- a/packages/session/session-telemetry-otel/tests/otel.spec.ts
+++ b/packages/session/session-telemetry-otel/tests/otel.spec.ts
@@ -16,7 +16,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { getOrCreateAnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import OpenTelemetrySessionBackend, { Config, DEFAULT_TELEMETRY_MODE, SessionTelemetryMode } from '../src/index.ts'
 
 interface Capture {
@@ -325,7 +325,7 @@ describe('OpenTelemetrySessionBackend wire', () => {
     })
     ctx.emit('session/event', session, {
       type: 'feedback/record',
-      seq: session.snapshotEvents().length,
+      seq: SessionSeq(session.seq),
       time: Date.now(),
       data: { text: 'not committed' },
     })
diff --git a/packages/session/session-telemetry/src/coordinator.ts b/packages/session/session-telemetry/src/coordinator.ts
index b558cedf8a..24150051fb 100644
--- a/packages/session/session-telemetry/src/coordinator.ts
+++ b/packages/session/session-telemetry/src/coordinator.ts
@@ -15,7 +15,8 @@
  */
 
 import type { Context } from '@deepseek-ai/cordis'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionSeq as SessionSeqType, SessionSeqCursor } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SessionTelemetrySink, SessionTelemetryRecord, SessionTelemetrySeverity } from './index.ts'
 
@@ -26,7 +27,7 @@ export type SessionTelemetryCapture = 'live' | 'on-demand'
 interface ProjectedRecord {
   readonly record: SessionTelemetryRecord
   /** Ledger cursor advanced only after the backend accepts this record. */
-  readonly seq?: number
+  readonly seq?: SessionSeqType
 }
 
 /**
@@ -40,7 +41,7 @@ interface ProjectedRecord {
  * "re-hand everything". Advanced only at emit time — the cursor marks
  * handed-off, not delivered.
  */
-const handoffCursor = new WeakMap<Session, number>()
+const handoffCursor = new WeakMap<Session, SessionSeqCursor>()
 
 /**
  * Install the telemetry capture side onto a context for one backend.
@@ -135,8 +136,9 @@ export class SessionTelemetryCoordinator {
    * @param session - session whose current canonical-log prefix may be handed over.
    * @param throughSeq - optional last sequence included in this capture.
    */
-  captureSession(session: Session, throughSeq?: number): void {
-    const cursor = handoffCursor.get(session) ?? session.firstLiveSeq - 1
+  captureSession(session: Session, throughSeq?: SessionSeqType): void {
+    const cursor = handoffCursor.get(session)
+      ?? (session.firstLiveSeq === 0 ? -1 : SessionSeq(session.firstLiveSeq - 1))
     // Containment is PER EVENT: one rejected record is withheld fail-closed
     // while the rest of the historical replay proceeds.
     for (const event of session.snapshotEvents()) {
@@ -309,11 +311,11 @@ function identityOf(session: Session, event: SessionEvent): Record<string, strin
     'event.type': event.type,
     'event.seq': event.seq,
   }
-  const { cwd, parentSession, seedLength } = session.header
+  const { cwd, parentSession, isSeeded } = session.header
   if (cwd !== undefined) attributes['session.cwd'] = cwd
   if (parentSession !== undefined) attributes['session.parent_id'] = String(parentSession)
   // The durable fork boundary: a forked stream starts here, and its prefix
   // lives in the parent's stream — receivers stitch on (parent_id, seed_length).
-  if (seedLength !== undefined) attributes['session.seed_length'] = seedLength
+  if (isSeeded) attributes['session.seed_length'] = session.inheritedEventCount
   return attributes
 }
diff --git a/packages/session/session-telemetry/tests/telemetry.spec.ts b/packages/session/session-telemetry/tests/telemetry.spec.ts
index e1dc3a13b5..bf097d193f 100644
--- a/packages/session/session-telemetry/tests/telemetry.spec.ts
+++ b/packages/session/session-telemetry/tests/telemetry.spec.ts
@@ -328,7 +328,7 @@ describe('SessionTelemetryCoordinator adoption', () => {
     expect(ofResumed()).toEqual([2, 4])
   })
 
-  it('stamps session.seed_length from the header so receivers can stitch fork streams', async () => {
+  it('stamps session.seed_length from the exact Session cut so receivers can stitch fork streams', async () => {
     const backend = new FakeBackend()
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -336,7 +336,8 @@ describe('SessionTelemetryCoordinator adoption', () => {
     appendTurn(parent)
     const child = ctx.sessions.create(SessionId('stitch-child'), {
       seed: parent.snapshotEvents(),
-      meta: { parentSession: SessionId('stitch-parent'), seedLength: 2 },
+      inheritedEventCount: parent.seq,
+      meta: { parentSession: SessionId('stitch-parent'), isSeeded: true },
     })
     await ctx.plugin({
       name: 'fake-telemetry',
diff --git a/packages/session/session-title-all-prompts-llm/tests/provider.spec.ts b/packages/session/session-title-all-prompts-llm/tests/provider.spec.ts
index a16b415b72..429f1f5bd3 100644
--- a/packages/session/session-title-all-prompts-llm/tests/provider.spec.ts
+++ b/packages/session/session-title-all-prompts-llm/tests/provider.spec.ts
@@ -54,7 +54,8 @@ describe('all-messages LLM title provider', () => {
     await ctx.plugin(providerPlugin, LLM_CONFIG)
     const session = ctx.sessions.create(SessionId('all-plugin'), {
       seed: seeded.snapshotEvents(),
-      meta: { parentSession: seeded.id, seedLength: seeded.seq },
+      inheritedEventCount: seeded.seq,
+      meta: { parentSession: seeded.id, isSeeded: true },
     })
     session.append('turn/start', { turn: 2 })
     const latest = session.append('user/message', createUserMessage({
diff --git a/packages/session/session-title-llm/src/index.ts b/packages/session/session-title-llm/src/index.ts
index 04330ae9c0..c8ccadcde5 100644
--- a/packages/session/session-title-llm/src/index.ts
+++ b/packages/session/session-title-llm/src/index.ts
@@ -10,6 +10,7 @@ import { createUserMessage, BlockAssembler } from '@deepseek-ai/dsh-llm'
 import type { FinishReason, GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
 import { deadline, MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { deepFreeze } from '@deepseek-ai/dsh-util-values'
+import type { SessionSeq } from '@deepseek-ai/dsh-session'
 import {
   normalizeSessionTitle,
   SessionTitleProviderId,
@@ -27,7 +28,7 @@ export interface SessionTitleLlmRequestEventData {
   /** Registered title-provider identity responsible for the request. */
   readonly titleProvider: SessionTitleProviderId
   /** Exact human `user/message` seqs represented in `messages`. */
-  readonly messageSeqs: number[]
+  readonly messageSeqs: SessionSeq[]
   /** Exact auxiliary LLM route. */
   readonly route: SessionTitleModelProvenance
   /** Exact auxiliary system prompt. */
diff --git a/packages/session/session-title/src/index.ts b/packages/session/session-title/src/index.ts
index 4e1c1e378a..3e36f1d588 100644
--- a/packages/session/session-title/src/index.ts
+++ b/packages/session/session-title/src/index.ts
@@ -15,6 +15,7 @@ import type {
   Session,
   SessionEvent,
 } from '@deepseek-ai/dsh-session'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-session-projection'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import type {} from '@deepseek-ai/dsh-agent'
@@ -107,7 +108,7 @@ export interface SessionTitleProviderResult {
   /** Proposed title text. */
   readonly title: string
   /** Exact seqs from `request.messages` used by this result. */
-  readonly messageSeqs: readonly number[]
+  readonly messageSeqs: readonly SessionSeq[]
   /** Auxiliary LLM route, when generation used a model. */
   readonly model?: SessionTitleModelProvenance
 }
@@ -170,7 +171,7 @@ interface ProviderRegistration {
 interface PendingAutomaticWork {
   readonly registration: ProviderRegistration
   readonly revision: number
-  readonly throughSeq: number
+  readonly throughSeq: SessionSeq
 }
 
 /** Provider call currently allowed to commit for one session. */
@@ -212,14 +213,14 @@ function titleSnapshotFromState(state: TitleProjection): SessionTitleSnapshot {
 const EMPTY_TITLE_INPUT: TitleInputState = { first: null, count: 0, lastSeq: null }
 
 const sessionTitleUserMessageSchema: ZodType<SessionTitleUserMessage> = zod.object({
-  seq: zod.number().int().nonnegative(),
+  seq: zod.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
   text: zod.string(),
 }).strict()
 
 const titleInputStateSchema: ZodType<TitleInputState> = zod.object({
   first: sessionTitleUserMessageSchema.nullable(),
   count: zod.number().int().nonnegative(),
-  lastSeq: zod.number().int().nonnegative().nullable(),
+  lastSeq: zod.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq).nullable(),
 }).strict().superRefine((state, context) => {
   const empty = state.first === null && state.lastSeq === null && state.count === 0
   const populated = state.first !== null
@@ -245,7 +246,7 @@ const titleInputStateSchema: ZodType<TitleInputState> = zod.object({
  */
 function collectSessionTitleMessages(
   events: readonly SessionEvent[],
-  throughSeq?: number,
+  throughSeq?: SessionSeq,
 ): SessionTitleUserMessage[] {
   const messages: SessionTitleUserMessage[] = []
   for (const event of events) {
@@ -632,18 +633,19 @@ export class SessionTitleService extends Service {
     if (!Array.isArray(candidate.messageSeqs) || candidate.messageSeqs.length === 0) {
       throw new Error('session-title provider must identify at least one source message seq')
     }
-    const messageSeqs: number[] = []
+    const messageSeqs: SessionSeq[] = []
     const order = new Map(messages.map((message, index) => [message.seq, index]))
     let previous = -1
     for (const seq of candidate.messageSeqs as unknown[]) {
-      if (typeof seq !== 'number') {
+      if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0) {
         throw new Error('session-title provider messageSeqs must be unique, ordered seqs from the request')
       }
-      const index = order.get(seq)
-      if (!Number.isSafeInteger(seq) || seq < 0 || index === undefined || index <= previous) {
+      const sessionSeq = SessionSeq(seq)
+      const index = order.get(sessionSeq)
+      if (index === undefined || index <= previous) {
         throw new Error('session-title provider messageSeqs must be unique, ordered seqs from the request')
       }
-      messageSeqs.push(seq)
+      messageSeqs.push(sessionSeq)
       previous = index
     }
     const modelCandidate = candidate.model
diff --git a/packages/session/session-title/src/invariant.ts b/packages/session/session-title/src/invariant.ts
index 11337fbf34..e12cd6ca25 100644
--- a/packages/session/session-title/src/invariant.ts
+++ b/packages/session/session-title/src/invariant.ts
@@ -6,7 +6,8 @@
 /* jscpd:ignore-start */
 import type { Context } from '@deepseek-ai/cordis'
 import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-session-title'
 
@@ -23,18 +24,49 @@ export const inject = ['invariants']
  * relationship every appended `session/title` event must keep, whichever
  * writer produced it.
  */
+function validate(
+  session: Session,
+  event: SessionEvent<'session/title'>,
+  fail: InvariantFailure,
+): void {
+  const { source, messageSeqs } = event.data
+  if ((messageSeqs.length === 0) !== (source.kind === 'user')) {
+    const requirement = source.kind === 'user' ? 'cite no message seqs' : 'cite at least one message seq'
+    fail(`session/title event ${String(event.seq)} with source "${source.kind}" must ${requirement}; got ${String(messageSeqs.length)}`)
+  }
+  const seen = new Set<ReturnType<typeof SessionSeq>>()
+  for (const seq of messageSeqs) {
+    let checked: ReturnType<typeof SessionSeq>
+    try {
+      checked = SessionSeq(seq)
+    } catch {
+      fail(`session/title event ${String(event.seq)} has an invalid message seq ${String(seq)}`)
+    }
+    if (seen.has(checked)) {
+      fail(`session/title event ${String(event.seq)} repeats message seq ${checked}`)
+    }
+    seen.add(checked)
+    const cited = checked < event.seq ? session.eventAt(checked) : undefined
+    if (cited?.type !== 'user/message' || cited.data.source.kind !== 'user') {
+      fail(`session/title event ${String(event.seq)} message seq ${checked} must name an earlier human user/message`)
+    }
+  }
+}
+
 const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  const validateExisting = (session: Session): void => {
+    for (const event of session.snapshotEvents()) {
+      if (event.type === 'session/title') validate(session, event, fail)
+    }
+  }
+  ctx.sessions.list().forEach(validateExisting)
+  ctx.on('session/created', validateExisting, { global: true })
   // internal/dispatch interception rejects the append before publication
   // (the session/event listener would only observe the already-committed log).
   ctx.on('internal/dispatch', (_mode, eventName, args) => {
     if (eventName !== 'session/event') return
-    const [, event] = args as [unknown, SessionEvent]
-    if (event.type !== 'session/title') return
-    const { source, messageSeqs } = event.data
-    if ((messageSeqs.length === 0) !== (source.kind === 'user')) {
-      const requirement = source.kind === 'user' ? 'cite no message seqs' : 'cite at least one message seq'
-      fail(`session/title event ${String(event.seq)} with source "${source.kind}" must ${requirement}; got ${String(messageSeqs.length)}`)
-    }
+    const [session, event] = args as [Session, SessionEvent]
+    if (event.type === 'session/title') validate(session, event, fail)
   }, { global: true })
 }, { inject: ['sessions'] })
 
diff --git a/packages/session/session-title/src/types.ts b/packages/session/session-title/src/types.ts
index bdc04c3e6c..c7d913f9e3 100644
--- a/packages/session/session-title/src/types.ts
+++ b/packages/session/session-title/src/types.ts
@@ -11,6 +11,7 @@
 export {}
 
 import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { OptionalSessionSeq, SessionSeq } from '@deepseek-ai/dsh-session/types'
 
 /** Identifies one session-title provider registration. */
 export type SessionTitleProviderId = Branded<'SessionTitleProviderId'>
@@ -41,7 +42,7 @@ export interface SessionTitleEventData {
   /** Normalized non-empty title text. */
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
-  readonly messageSeqs: number[]
+  readonly messageSeqs: SessionSeq[]
   /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
@@ -49,7 +50,7 @@ export interface SessionTitleEventData {
 /** Latest folded title plus the title event's durable envelope facts. */
 export interface SessionTitleSnapshot extends SessionTitleEventData {
   /** Seq of the latest `session/title` event. */
-  readonly eventSeq: number
+  readonly eventSeq: SessionSeq
   /** Timestamp of the latest `session/title` event. */
   readonly updatedAt: number
 }
@@ -60,7 +61,7 @@ export type TitleProjection = SessionTitleSnapshot
 /** One eligible human text message exposed to title providers. */
 export interface SessionTitleUserMessage {
   /** Source `user/message` event seq. */
-  readonly seq: number
+  readonly seq: SessionSeq
   /** Exact concatenated text-block content. */
   readonly text: string
 }
@@ -72,7 +73,7 @@ export interface TitleInputState {
   /** Total eligible messages folded so far. */
   readonly count: number
   /** Seq of the newest eligible message, or null before any. */
-  readonly lastSeq: number | null
+  readonly lastSeq: OptionalSessionSeq
 }
 
 declare module '@deepseek-ai/dsh-session-projection/types' {
diff --git a/packages/session/session-title/tests/invariant.spec.ts b/packages/session/session-title/tests/invariant.spec.ts
index 75dadcf7c1..5903c63250 100644
--- a/packages/session/session-title/tests/invariant.spec.ts
+++ b/packages/session/session-title/tests/invariant.spec.ts
@@ -4,7 +4,8 @@ import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import * as SessionTitleInvariantCompanion from '@deepseek-ai/dsh-session-title/invariant'
 import InvariantRegistry, { InvariantError } from '@deepseek-ai/dsh-invariants'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
 
 async function setup(): Promise<Context> {
   const ctx = new Context()
@@ -18,8 +19,11 @@ describe('session-title source invariant', () => {
   it('accepts cited automatic titles and citation-free user renames', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create(SessionId('title-invariant-valid'))
+    const source = session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'title me' }], source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
     expect(() => {
-      session.append('session/title', { title: 'auto', messageSeqs: [1], source: { kind: 'fallback' } })
+      session.append('session/title', { title: 'auto', messageSeqs: [source.seq], source: { kind: 'fallback' } })
       session.append('session/title', { title: 'named', messageSeqs: [], source: { kind: 'user' } })
     }).not.toThrow()
   })
@@ -27,6 +31,9 @@ describe('session-title source invariant', () => {
   it('rejects a citation-free automatic title and a user rename that cites messages', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create(SessionId('title-invariant-invalid'))
+    const source = session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'title me' }], source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
     expect(() => {
       session.append('session/title', { title: 'auto', messageSeqs: [], source: { kind: 'fallback' } })
     }).toThrow(expect.objectContaining<Partial<InvariantError>>({
@@ -34,11 +41,52 @@ describe('session-title source invariant', () => {
       packageName: '@deepseek-ai/dsh-session-title',
     }))
     expect(() => {
-      session.append('session/title', { title: 'named', messageSeqs: [1], source: { kind: 'user' } })
+      session.append('session/title', { title: 'named', messageSeqs: [source.seq], source: { kind: 'user' } })
     }).toThrow(expect.objectContaining<Partial<InvariantError>>({
       code: 'INVARIANT',
       packageName: '@deepseek-ai/dsh-session-title',
     }))
-    expect(session.seq).toBe(0)
+    expect(session.seq).toBe(1)
+  })
+
+  it('requires automatic-title citations to name distinct earlier human messages', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create(SessionId('title-invariant-sources'))
+    const boundary = session.append('turn/start', { turn: 1 })
+    expect(() => session.append('session/title', {
+      title: 'wrong source', messageSeqs: [boundary.seq], source: { kind: 'fallback' },
+    })).toThrow(/must name an earlier human user\/message/)
+    expect(() => session.append('session/title', {
+      title: 'future source', messageSeqs: [SessionSeq(session.seq)], source: { kind: 'fallback' },
+    })).toThrow(/must name an earlier human user\/message/)
+    expect(() => session.append('session/title', {
+      title: 'malformed source', messageSeqs: [-1 as never], source: { kind: 'fallback' },
+    })).toThrow(/invalid message seq/)
+    const pluginMessage = session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'plugin context' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }), { surfaceOp: 'append' })
+    expect(() => session.append('session/title', {
+      title: 'plugin source', messageSeqs: [pluginMessage.seq], source: { kind: 'fallback' },
+    })).toThrow(/must name an earlier human user\/message/)
+    const source = session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'title me' }], source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    expect(() => session.append('session/title', {
+      title: 'duplicate source', messageSeqs: [source.seq, source.seq], source: { kind: 'fallback' },
+    })).toThrow(/repeats message seq/)
+  })
+
+  it('validates title relations when the companion loads after a Session', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const session = ctx.sessions.create(SessionId('title-invariant-existing'))
+    const boundary = session.append('turn/start', { turn: 1 })
+    session.append('session/title', {
+      title: 'wrong source', messageSeqs: [boundary.seq], source: { kind: 'fallback' },
+    })
+    await ctx.plugin(InvariantRegistry, { enabled: true })
+    await expect(ctx.plugin(SessionTitleInvariantCompanion).then(() => undefined))
+      .rejects.toThrow(/must name an earlier human user\/message/)
   })
 })
diff --git a/packages/session/session-title/tests/projection.spec.ts b/packages/session/session-title/tests/projection.spec.ts
index 26226b3552..df2b5f1f91 100644
--- a/packages/session/session-title/tests/projection.spec.ts
+++ b/packages/session/session-title/tests/projection.spec.ts
@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import type { Session } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import type { Session, SessionSeq as SessionSeqType } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SessionTitleService from '@deepseek-ai/dsh-session-title'
 
@@ -16,8 +16,16 @@ async function harness(withTitleService: boolean): Promise<{ ctx: Context; sessi
   return { ctx, session: ctx.sessions.create(SessionId('titled')) }
 }
 
-function appendTitle(session: Session, title: string): number {
-  return session.append('session/title', { title, messageSeqs: [1], source: { kind: 'fallback' } }).seq
+function appendTitle(session: Session, title: string): SessionSeqType {
+  const messageSeq = session.snapshotEvents().find(event =>
+    event.type === 'user/message' && event.data.source.kind === 'user')?.seq
+    ?? session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'Title source' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' }).seq
+  return session.append('session/title', {
+    title, messageSeqs: [messageSeq], source: { kind: 'fallback' },
+  }).seq
 }
 
 describe('title projection unit', () => {
@@ -30,7 +38,7 @@ describe('title projection unit', () => {
 
   it('serves the latest title last-wins and notifies the change feed with the causing seq', async () => {
     const { ctx, session } = await harness(true)
-    const changes: { key: string; value: unknown; seq: number }[] = []
+    const changes: { key: string; value: unknown; seq: SessionSeqType }[] = []
     ctx.sessionProjections.onChanged((_session, key, value, seq) => {
       changes.push({ key, value, seq })
     })
@@ -50,7 +58,7 @@ describe('title projection unit', () => {
     const { ctx } = await harness(true)
 
     expect(ctx.sessionProjections.viewCheckpoint({
-      title: { ver: 1, seq: 8, val: 'Cached title' },
+      title: { ver: 1, seq: SessionSeq(8), val: 'Cached title' },
     })).toEqual({ title: 'Cached title' })
   })
 
@@ -105,7 +113,9 @@ describe('title projection unit', () => {
         ...checkpoint,
         titleInput: { ...row!, val: state },
       }
-      expect(() => ctx.sessionProjections.restore(malformed, [], 0, session.header))
+      expect(() => ctx.sessionProjections.restore(
+        malformed, [], SessionLogOffset(0), session.header, session.inheritedEventCount,
+      ))
         .toThrow(/title input state must pair its count with first and last message seqs/)
     }
 
@@ -115,6 +125,6 @@ describe('title projection unit', () => {
         ...row!,
         val: { first: { seq: 1, text: 'first' }, count: 1, lastSeq: 1 },
       },
-    }, [], 0, session.header)).not.toThrow()
+    }, [], SessionLogOffset(0), session.header, session.inheritedEventCount)).not.toThrow()
   })
 })
diff --git a/packages/session/session-title/tests/provider.spec.ts b/packages/session/session-title/tests/provider.spec.ts
index ecd2e69ec5..d9632ea3b6 100644
--- a/packages/session/session-title/tests/provider.spec.ts
+++ b/packages/session/session-title/tests/provider.spec.ts
@@ -2,7 +2,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it, vi } from 'vitest'
 import LlmRuntime, { createUserMessage, markAgentLoopRequest } from '@deepseek-ai/dsh-llm'
 import { deepFreeze } from '@deepseek-ai/dsh-util-values'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import { turnBoundaryProjectionDefinition } from '@deepseek-ai/dsh-agent-loop'
 import SessionTitleService, {
@@ -256,7 +256,7 @@ describe('SessionTitleService Provider lifecycle', () => {
     expect(() => ctx.sessionTitle.register({
       id: SessionTitleProviderId('duplicate'),
       automatic: 'first-prompt',
-      generate: async () => ({ title: 'duplicate', messageSeqs: [0] }),
+      generate: async () => ({ title: 'duplicate', messageSeqs: [SessionSeq(0)] }),
     })).toThrow(/already registered/)
 
     const session = ctx.sessions.create(SessionId('dispose-provider'))
diff --git a/packages/session/session-title/tests/service-contracts.spec.ts b/packages/session/session-title/tests/service-contracts.spec.ts
index ce3e4997bb..c6e0dc93c3 100644
--- a/packages/session/session-title/tests/service-contracts.spec.ts
+++ b/packages/session/session-title/tests/service-contracts.spec.ts
@@ -1,7 +1,7 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { Context, type Fiber } from '@deepseek-ai/cordis'
 import { describe, expect, it, vi } from 'vitest'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SessionTitleService, {
   SessionTitleProviderId,
@@ -72,7 +72,7 @@ describe('SessionTitleService configuration and refresh boundaries', () => {
     const withProvider = await setup()
     const generate = vi.fn(async (): Promise<SessionTitleProviderResult> => ({
       title: 'unused',
-      messageSeqs: [0],
+      messageSeqs: [SessionSeq(0)],
     }))
     withProvider.sessionTitle.register({
       id: SessionTitleProviderId('empty-provider'),
@@ -362,7 +362,9 @@ describe('SessionTitleService configuration and refresh boundaries', () => {
 describe('SessionTitleService Provider validation and stale scheduling', () => {
   it('rejects malformed provider registrations before publishing them', async () => {
     const ctx = await setup()
-    const generate = async (): Promise<SessionTitleProviderResult> => ({ title: 'title', messageSeqs: [0] })
+    const generate = async (): Promise<SessionTitleProviderResult> => ({
+      title: 'title', messageSeqs: [SessionSeq(0)],
+    })
     expect(() => ctx.sessionTitle.register(null as never)).toThrow(/must be an object/)
     expect(() => ctx.sessionTitle.register('provider' as never)).toThrow(/must be an object/)
     expect(() => ctx.sessionTitle.register({
diff --git a/packages/session/session-title/tests/session-title.spec.ts b/packages/session/session-title/tests/session-title.spec.ts
index 0254ff5826..69edbb84ff 100644
--- a/packages/session/session-title/tests/session-title.spec.ts
+++ b/packages/session/session-title/tests/session-title.spec.ts
@@ -1,7 +1,7 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it } from 'vitest'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SessionTitleService, {
   SessionTitleProviderId,
@@ -147,12 +147,12 @@ describe('SessionTitleService', () => {
     const seed = Session.create(SessionId('source'))
     seed.append('session/title', {
       title: 'Earlier',
-      messageSeqs: [1],
+      messageSeqs: [SessionSeq(1)],
       source: { kind: 'fallback' },
     })
     seed.append('session/title', {
       title: 'Later',
-      messageSeqs: [1, 4],
+      messageSeqs: [SessionSeq(1), SessionSeq(4)],
       source: {
         kind: 'provider',
         provider: SessionTitleProviderId('test-provider'),
diff --git a/packages/session/session-turn-outline/src/projection.ts b/packages/session/session-turn-outline/src/projection.ts
index 68ae2bbf0c..992273e72a 100644
--- a/packages/session/session-turn-outline/src/projection.ts
+++ b/packages/session/session-turn-outline/src/projection.ts
@@ -21,7 +21,7 @@
 
 import { z } from 'zod'
 import type { ZodType } from 'zod'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import type { TurnOutlineEntry, TurnOutlineState } from './types.ts'
 
@@ -60,7 +60,7 @@ function preview(content: MessageContent, limit: number): string {
 
 const turnOutlineEntriesSchema: ZodType<readonly TurnOutlineEntry[]> = z.array(z.object({
   turn: z.number().int().nonnegative(),
-  seq: z.number().int().nonnegative(),
+  seq: z.number().int().nonnegative().transform(SessionSeq),
   prompt: z.string().max(PROMPT_PREVIEW_LIMIT),
   response: z.string().max(RESPONSE_PREVIEW_LIMIT),
 }).strict()).superRefine((turns, context) => {
diff --git a/packages/session/session-turn-outline/src/types.ts b/packages/session/session-turn-outline/src/types.ts
index 11e0b9c295..c4ccbcdab3 100644
--- a/packages/session/session-turn-outline/src/types.ts
+++ b/packages/session/session-turn-outline/src/types.ts
@@ -7,6 +7,8 @@
  * @module @deepseek-ai/dsh-session-turn-outline/types
  */
 
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
+
 export {}
 
 /** One started turn's outline facts, independent of what a client has paged in. */
@@ -14,7 +16,7 @@ export interface TurnOutlineEntry {
   /** Host-assigned turn number (the `turn/start` payload). */
   readonly turn: number
   /** The turn's `turn/start` event seq — paging a window back through this seq loads the whole turn. */
-  readonly seq: number
+  readonly seq: SessionSeq
   /** Bounded first-human-prompt preview (one rail-card line); `''` until an eligible prompt lands. */
   readonly prompt: string
   /** Bounded final-response preview (up to three rail-card lines); `''` until the turn ends with assistant text. */
diff --git a/packages/session/session-turn-outline/tests/projection.spec.ts b/packages/session/session-turn-outline/tests/projection.spec.ts
index eb22ea571d..eced03f664 100644
--- a/packages/session/session-turn-outline/tests/projection.spec.ts
+++ b/packages/session/session-turn-outline/tests/projection.spec.ts
@@ -9,10 +9,10 @@
  * regressive turn numbers) run against the exported definition directly.
  */
 
-import { describe, expect, it } from 'vitest'
+import { describe, expect, expectTypeOf, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { createAssistantMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import * as SessionTurnOutlinePlugin from '@deepseek-ai/dsh-session-turn-outline'
@@ -28,7 +28,7 @@ async function harness(withOutlinePlugin: boolean): Promise<{ ctx: Context; sess
 }
 
 /** Append one human prompt; returns its seq. */
-function appendPrompt(session: Session, text: string): number {
+function appendPrompt(session: Session, text: string): SessionSeq {
   return session.append('user/message', createUserMessage({
     content: [{ type: 'text', text }],
     source: { kind: 'user' },
@@ -47,7 +47,7 @@ function appendAssistant(session: Session, turn: number, step: number, text: str
   }, { surfaceOp: 'append' })
 }
 
-function endTurn(session: Session, turn: number): number {
+function endTurn(session: Session, turn: number): SessionSeq {
   return session.append('turn/end', { turn, reason: { kind: 'completed' } }).seq
 }
 
@@ -56,6 +56,10 @@ function outlineOf(ctx: Context, session: Session): readonly TurnOutlineEntry[]
 }
 
 describe('turn outline projection unit', () => {
+  it('exposes the turn boundary as a branded event identity', () => {
+    expectTypeOf<TurnOutlineEntry['seq']>().toEqualTypeOf<ReturnType<typeof SessionSeq>>()
+  })
+
   it('serves an empty outline before any turn starts', async () => {
     const { ctx, session } = await harness(true)
     expect(outlineOf(ctx, session)).toEqual([])
@@ -140,7 +144,7 @@ describe('turn outline projection unit', () => {
 
   it('pushes at most three times per turn: boundary, prompt, and settled response', async () => {
     const { ctx, session } = await harness(true)
-    const changes: { seq: number; last: TurnOutlineEntry | undefined }[] = []
+    const changes: { seq: SessionSeq; last: TurnOutlineEntry | undefined }[] = []
     ctx.sessionProjections.onChanged((_session, key, value, seq) => {
       if (key !== 'turnOutline') return
       changes.push({ seq, last: (value as readonly TurnOutlineEntry[]).at(-1) })
@@ -170,11 +174,11 @@ describe('turn outline projection unit', () => {
     const def = turnOutlineProjectionDefinition
     const assistant = (blocks: readonly unknown[]): SessionEvent => ({
       type: 'assistant/message',
-      seq: 9,
+      seq: SessionSeq(9),
       time: 0,
       data: { message: { content: blocks } },
     }) as unknown as SessionEvent
-    const base: TurnOutlineState = { turns: [{ turn: 1, seq: 0, prompt: 'p', response: '' }], draft: '' }
+    const base: TurnOutlineState = { turns: [{ turn: 1, seq: SessionSeq(0), prompt: 'p', response: '' }], draft: '' }
     // Non-text blocks are skipped; whitespace-heavy short blocks cross the raw
     // reading bound early, so the collapsed (short) draft still marks the
     // unread remainder with an ellipsis.
@@ -189,23 +193,23 @@ describe('turn outline projection unit', () => {
     // A draft with no entry to commit into clears itself at the boundary…
     const end = {
       type: 'turn/end',
-      seq: 11,
+      seq: SessionSeq(11),
       time: 0,
       data: { turn: 1, reason: { kind: 'completed' } },
     } as unknown as SessionEvent
     expect(def.apply({ turns: [], draft: 'orphan' }, end)).toEqual({ turns: [], draft: '' })
     // …and a re-settled identical response keeps the entries' identity.
-    const settled: TurnOutlineState = { turns: [{ turn: 1, seq: 0, prompt: 'p', response: 'done' }], draft: 'done' }
+    const settled: TurnOutlineState = { turns: [{ turn: 1, seq: SessionSeq(0), prompt: 'p', response: 'done' }], draft: 'done' }
     const recommitted = def.apply(settled, end)
     expect(recommitted.turns).toBe(settled.turns)
     expect(recommitted.draft).toBe('')
   })
 
   it('skips a boundary that does not advance the turn number (fabricated envelope)', () => {
-    const state: TurnOutlineState = { turns: [{ turn: 2, seq: 5, prompt: 'kept', response: '' }], draft: '' }
+    const state: TurnOutlineState = { turns: [{ turn: 2, seq: SessionSeq(5), prompt: 'kept', response: '' }], draft: '' }
     const regressive = {
       type: 'turn/start',
-      seq: 9,
+      seq: SessionSeq(9),
       time: 0,
       data: { turn: 2 },
     } as unknown as SessionEvent
@@ -247,7 +251,7 @@ describe('turn outline projection unit', () => {
           draft: '',
         },
       },
-    }, [], 0, session.header)).toThrow(/strictly increasing/)
+    }, [], SessionLogOffset(0), session.header, session.inheritedEventCount)).toThrow(/strictly increasing/)
     expect(() => ctx.sessionProjections.restore({
       ...checkpoint,
       turnOutline: {
@@ -260,6 +264,6 @@ describe('turn outline projection unit', () => {
           draft: '',
         },
       },
-    }, [], 0, session.header)).not.toThrow()
+    }, [], SessionLogOffset(0), session.header, session.inheritedEventCount)).not.toThrow()
   })
 })
diff --git a/packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts b/packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts
index 2f2eab801f..c2aeac1606 100644
--- a/packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts
+++ b/packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts
@@ -40,7 +40,7 @@ class PassthroughSandbox extends SandboxProvider {
 function agent(ctx: Context, cwd: string): Agent {
   const id = SessionId('persistent-bash-loader-agent')
   const scope = ctx.plugin(() => {})
-  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd })
+  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd, isSeeded: false })
   const value: Agent = {
     id,
     options: {},
diff --git a/packages/shell/tool-bash-persistent/tests/tools.spec.ts b/packages/shell/tool-bash-persistent/tests/tools.spec.ts
index 921ff1f265..97d48a4cc5 100644
--- a/packages/shell/tool-bash-persistent/tests/tools.spec.ts
+++ b/packages/shell/tool-bash-persistent/tests/tools.spec.ts
@@ -33,6 +33,7 @@ function agent(ctx: Context, cwd: string | undefined): Agent {
     version: 0,
     id,
     createdAt: 0,
+    isSeeded: false,
     ...cwd === undefined ? {} : { cwd },
   })
   const value: Agent = {
diff --git a/packages/shell/tool-bash/tests/tools.spec.ts b/packages/shell/tool-bash/tests/tools.spec.ts
index fd6bc51b16..ca8ce99c89 100644
--- a/packages/shell/tool-bash/tests/tools.spec.ts
+++ b/packages/shell/tool-bash/tests/tools.spec.ts
@@ -11,7 +11,7 @@ import ToolRuntime, { TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepse
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { turnBoundaryProjectionDefinition } from '@deepseek-ai/dsh-agent-loop'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs'
@@ -205,20 +205,37 @@ function sandboxAgent(
   ctx?: Context,
   onAppend?: (type: string) => void,
 ): Agent {
-  const events: Array<{ type: string; data?: Record<string, unknown>; seq: number }> = [{ type: 'turn/start', seq: 0, data: { turn: 1 } }]
-  if (mode !== undefined) events.push({ type: 'sandbox/mode', seq: events.length, data: { mode } })
+  const events: Array<{
+    type: string
+    seq: ReturnType<typeof SessionSeq>
+    time: number
+    data: Record<string, unknown>
+  }> = [{ type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 } }]
+  if (mode !== undefined) {
+    events.push({ type: 'sandbox/mode', seq: SessionSeq(1), time: 1, data: { mode } })
+  }
   const id = SessionId('sandbox-session')
   return {
     id,
     ...ctx === undefined ? {} : { ctx: ctx.plugin(() => {}).ctx },
     session: {
       id,
-      header: { version: 0, id, createdAt: 0 },
-      get seq() { return events.length },
-      eventAt: (seq: number) => events[seq],
-      snapshotEvents: () => events,
+      header: { version: 0, id, createdAt: 0, isSeeded: false },
+      inheritedEventCount: SessionLogOffset(0),
+      firstLiveSeq: SessionLogOffset(0),
+      get seq() { return SessionLogOffset(events.length) },
+      eventAt: (seq: ReturnType<typeof SessionSeq>) => events[seq],
+      snapshotEvents: (
+        fromSeq = SessionLogOffset(0),
+        toSeqExclusive = SessionLogOffset(events.length),
+      ) => events.slice(fromSeq, toSeqExclusive),
       append: (type: string, data: Record<string, unknown>) => {
-        const event = { type, data, seq: events.length }
+        const event = {
+          type,
+          seq: SessionSeq(events.length),
+          time: events.length,
+          data,
+        }
         events.push(event)
         onAppend?.(type)
         return event
@@ -627,11 +644,10 @@ describe('sandbox escalation through the generic task producer', () => {
     expect(prompted).not.toHaveBeenCalled()
 
     const malformed = sandboxAgent()
-    ;(malformed.session.snapshotEvents() as unknown as Array<{ type: string; data: { mode: string }; seq: number }>).push({
-      type: 'sandbox/mode',
-      data: { mode: 'unknown-mode' },
-      seq: malformed.session.seq,
-    })
+    ;(malformed.session.append as unknown as (
+      type: string,
+      data: Record<string, unknown>,
+    ) => unknown)('sandbox/mode', { mode: 'unknown-mode' })
     expect(text(await call(ctx, 'bash', escalate, malformed))).toContain('not strictly wider')
   })
 
diff --git a/packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts b/packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts
index 1ee4f0c2c5..58b05082d0 100644
--- a/packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts
+++ b/packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts
@@ -47,7 +47,7 @@ class PassthroughSandbox extends SandboxProvider {
 function agent(ctx: Context, cwd: string): Agent {
   const id = SessionId('persistent-pwsh-loader-agent')
   const scope = ctx.plugin(() => {})
-  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd })
+  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd, isSeeded: false })
   const value: Agent = {
     id,
     options: {},
diff --git a/packages/shell/tool-pwsh-persistent/tests/tools.spec.ts b/packages/shell/tool-pwsh-persistent/tests/tools.spec.ts
index 8d9c55e39c..d5d9218171 100644
--- a/packages/shell/tool-pwsh-persistent/tests/tools.spec.ts
+++ b/packages/shell/tool-pwsh-persistent/tests/tools.spec.ts
@@ -33,6 +33,7 @@ function agent(ctx: Context, cwd: string | undefined): Agent {
     version: 0,
     id,
     createdAt: 0,
+    isSeeded: false,
     ...cwd === undefined ? {} : { cwd },
   })
   const value: Agent = {
diff --git a/packages/shell/tool-pwsh/tests/tools.spec.ts b/packages/shell/tool-pwsh/tests/tools.spec.ts
index c50af1a02f..5e27e3c8e0 100644
--- a/packages/shell/tool-pwsh/tests/tools.spec.ts
+++ b/packages/shell/tool-pwsh/tests/tools.spec.ts
@@ -22,7 +22,7 @@ import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import ApprovalService from '@deepseek-ai/dsh-user-approval'
 import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
 import { ShellExecutor } from '@deepseek-ai/dsh-shell'
@@ -236,22 +236,39 @@ function sandboxAgent(
   ctx?: Context,
   onAppend?: (type: string) => void,
 ): Agent {
-  const events: Array<{ type: string; data?: Record<string, unknown>; seq?: number }> = [
-    { type: 'turn/start', seq: 0, data: { turn: 1 } },
+  const events: Array<{
+    type: string
+    seq: ReturnType<typeof SessionSeq>
+    time: number
+    data: Record<string, unknown>
+  }> = [
+    { type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 } },
   ]
-  if (mode !== undefined) events.push({ type: 'sandbox/mode', seq: 1, data: { mode } })
+  if (mode !== undefined) {
+    events.push({ type: 'sandbox/mode', seq: SessionSeq(1), time: 1, data: { mode } })
+  }
   const id = SessionId('sandbox-session')
   return {
     id,
     ...ctx === undefined ? {} : { ctx: ctx.plugin(() => {}).ctx },
     session: {
       id,
-      header: { version: 0, id, createdAt: 0 },
-      get seq() { return events.length },
-      eventAt: (seq: number) => events[seq],
-      snapshotEvents: () => events,
+      header: { version: 0, id, createdAt: 0, isSeeded: false },
+      inheritedEventCount: SessionLogOffset(0),
+      firstLiveSeq: SessionLogOffset(0),
+      get seq() { return SessionLogOffset(events.length) },
+      eventAt: (seq: ReturnType<typeof SessionSeq>) => events[seq],
+      snapshotEvents: (
+        fromSeq = SessionLogOffset(0),
+        toSeqExclusive = SessionLogOffset(events.length),
+      ) => events.slice(fromSeq, toSeqExclusive),
       append: (type: string, data: Record<string, unknown>) => {
-        const event = { type, data, seq: events.length }
+        const event = {
+          type,
+          seq: SessionSeq(events.length),
+          time: events.length,
+          data,
+        }
         events.push(event)
         onAppend?.(type)
         return event
@@ -274,8 +291,10 @@ function registerFakeAgent(ctx: Context, sessionId: string): Agent {
     ctx: scopeFiber.ctx,
     session: {
       id,
-      header: { version: 0, id, createdAt: 0 },
-      seq: 0,
+      header: { version: 0, id, createdAt: 0, isSeeded: false },
+      inheritedEventCount: SessionLogOffset(0),
+      firstLiveSeq: SessionLogOffset(0),
+      seq: SessionLogOffset(0),
       eventAt: () => undefined,
       snapshotEvents: () => [],
     },
@@ -610,11 +629,10 @@ describe('sandbox escalation through ctx.approval', () => {
     expect(prompted).not.toHaveBeenCalled()
 
     const malformed = sandboxAgent()
-    ;(malformed.session.snapshotEvents() as unknown as Array<{ type: string; data: { mode: string }; seq: number }>).push({
-      type: 'sandbox/mode',
-      data: { mode: 'unknown-mode' },
-      seq: malformed.session.seq,
-    })
+    ;(malformed.session.append as unknown as (
+      type: string,
+      data: Record<string, unknown>,
+    ) => unknown)('sandbox/mode', { mode: 'unknown-mode' })
     expect(text(await call(ctx, 'pwsh', escalate, malformed))).toContain('not strictly wider')
   })
 
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index c620afd9c5..3465cd843c 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -10,7 +10,7 @@ import z from '@deepseek-ai/schemastery'
 import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import type { UserMessage } from '@deepseek-ai/dsh-session'
+import { SessionSeq, type UserMessage } from '@deepseek-ai/dsh-session'
 import {
   escapeText,
   isModelInvocable,
@@ -362,7 +362,7 @@ function catalogHistory(agent: Agent): { visibleDigest?: string; published: bool
   const visible = new Set(agent.session.surface.nodes)
   let published = false
   for (let index = agent.session.seq - 1; index >= 0; index -= 1) {
-    const event = agent.session.eventAt(index)
+    const event = agent.session.eventAt(SessionSeq(index))
     if (event === undefined) {
       throw new Error(`skill catalog cannot read seq ${String(index)} below the current Session length`)
     }
diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts
index 7a488ba2e0..858367134a 100644
--- a/packages/skill/tool-skill/tests/tool-skill.spec.ts
+++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts
@@ -38,7 +38,7 @@ async function setup(home: string, config: toolSkill.Config = {}): Promise<Conte
 
 function agentForCwd(cwd: string): Agent {
   const id = SessionId(`tool-skill-${cwd}`)
-  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd })
+  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd, isSeeded: false })
   return {
     ctx: new Context(),
     id,
diff --git a/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts b/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
index ca2618dd7a..0219824497 100644
--- a/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
+++ b/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
@@ -86,7 +86,8 @@ describe('dsh-subagent-fork-in-process', () => {
     const child = ctx.agents.get(run.id)!
     // Only the child's own turn — no seeded parent turns.
     expect(child.session.snapshotEvents().filter(e => e.type === 'turn/end')).toHaveLength(1)
-    expect(child.session.header.seedLength).toBeUndefined()
+    expect(child.session.header.isSeeded).toBe(false)
+    expect(child.session.inheritedEventCount).toBe(0)
     await run.dispose()
   })
 
@@ -101,7 +102,8 @@ describe('dsh-subagent-fork-in-process', () => {
     const run = await start(ctx, 'fork', { prompt: [{ type: 'text', text: 'child q' }], parent })
     await run.result
     const child = ctx.agents.get(run.id)!
-    expect(child.session.header.seedLength).toBe(parentPrefixLen)
+    expect(child.session.header.isSeeded).toBe(true)
+    expect(child.session.inheritedEventCount).toBe(parentPrefixLen)
     expect(child.session.snapshotEvents().slice(0, parentPrefixLen).at(-1)?.type).toBe('turn/end')
     expect(child.session.snapshotEvents().slice(0, parentPrefixLen).filter(e => e.type === 'turn/end')).toHaveLength(2)
     await run.dispose()
@@ -126,10 +128,10 @@ describe('dsh-subagent-fork-in-process', () => {
     expect(seededUser).toBeDefined()
     // Lineage stamped.
     expect(child.session.header.parentSession).toBe(parent.session.header.id)
-    // The seed boundary is recorded on the header (= the seeded prefix length),
-    // so a reload / replay harness can tell the inherited prefix from the
-    // child's own events.
-    expect(child.session.header.seedLength).toBe(parentPrefixLen)
+    // Logical metadata records lineage while Session state retains the exact
+    // inherited cut for reload and replay.
+    expect(child.session.header.isSeeded).toBe(true)
+    expect(child.session.inheritedEventCount).toBe(parentPrefixLen)
     await run.dispose()
   })
 
diff --git a/packages/subagent/subagent-in-process-driver/src/index.ts b/packages/subagent/subagent-in-process-driver/src/index.ts
index 53fd8f3783..4ca07b8436 100644
--- a/packages/subagent/subagent-in-process-driver/src/index.ts
+++ b/packages/subagent/subagent-in-process-driver/src/index.ts
@@ -16,7 +16,8 @@ import type { Context } from '@deepseek-ai/cordis'
 import { brandString } from '@deepseek-ai/dsh-brand'
 import { foldConsumedWork } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent'
-import type { SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId, SessionLogOffset as SessionLogOffsetType, TurnEndReason } from '@deepseek-ai/dsh-session'
 import { createUserMessage, type ContentBlock } from '@deepseek-ai/dsh-llm'
 import {
   appendDelegatedPolicyOverrides,
@@ -111,7 +112,7 @@ export async function startInProcessRun(
 
   const childId = brandString<SessionId>(randomUUID())
   const seed = options.seed
-  const activationBoundary = seed?.length ?? 0
+  const activationBoundary = SessionLogOffset(seed?.length ?? 0)
 
   // Capture before the first await: a later parent switch belongs to the
   // parent's future.
@@ -132,8 +133,9 @@ export async function startInProcessRun(
 
   const handle = await parent.ctx.agents.create({
     sessionId: childId,
-    meta: childSessionMeta(parent, childDepth, activationBoundary),
+    meta: childSessionMeta(parent, childDepth, seed !== undefined),
     ...seed !== undefined ? { seed } : {},
+    ...seed === undefined ? {} : { inheritedEventCount: activationBoundary },
     agentOptions: resolveChildAgentOptions(parent, request.agentOptions, childDepth),
     signal: request.signal,
     setup,
@@ -157,7 +159,7 @@ function drivePublishedRun(
   signal: AbortSignal,
   prompt: ContentBlock[],
   childId: SessionId,
-  boundary: number,
+  boundary: SessionLogOffsetType,
   structured: StructuredAttachment | undefined,
 ): SubagentRun {
   const child = handle.agent
@@ -208,7 +210,7 @@ function drivePublishedRun(
 /** Read one settled child's result from events after its activation boundary. */
 function readResult(
   child: Agent,
-  boundary: number,
+  boundary: SessionLogOffsetType,
   cancelled: boolean,
   structured?: { captured?: { value: unknown } | undefined },
 ): SubagentResult {
diff --git a/packages/subagent/subagent-in-process-driver/tests/inheritance.spec.ts b/packages/subagent/subagent-in-process-driver/tests/inheritance.spec.ts
index e9e1a1dda2..d5f26b8558 100644
--- a/packages/subagent/subagent-in-process-driver/tests/inheritance.spec.ts
+++ b/packages/subagent/subagent-in-process-driver/tests/inheritance.spec.ts
@@ -107,7 +107,8 @@ describe('in-process policy inheritance', () => {
         { type: 'approval/policy', seq: 1, data: { policy: 'never', source: 'delegation' } },
       ])
       expect(child.session.firstLiveSeq).toBe(0)
-      expect(child.session.header.seedLength).toBeUndefined()
+      expect(child.session.header.isSeeded).toBe(false)
+      expect(child.session.inheritedEventCount).toBe(0)
       expect(ctx.sandboxPolicy.overrideOf(child.session)).toBe('read-only')
       expect(ctx.approval.overrideOf(child.session)).toBe('never')
       const request = child.session.snapshotEvents().find(
@@ -153,7 +154,8 @@ describe('in-process policy inheritance', () => {
       await run.result
       const child = run.localAgent as Agent
 
-      expect(child.session.header.seedLength).toBe(1)
+      expect(child.session.header.isSeeded).toBe(true)
+      expect(child.session.inheritedEventCount).toBe(1)
       expect(child.session.firstLiveSeq).toBe(seed.length)
       // seq 1 is the constructor's end-seed marker.
       expect(child.session.snapshotEvents().filter(event => event.type === 'sandbox/mode')).toMatchObject([
diff --git a/packages/subagent/subagent-in-process-driver/tests/subagent-in-process-driver.spec.ts b/packages/subagent/subagent-in-process-driver/tests/subagent-in-process-driver.spec.ts
index cadddf8814..df0250cf3f 100644
--- a/packages/subagent/subagent-in-process-driver/tests/subagent-in-process-driver.spec.ts
+++ b/packages/subagent/subagent-in-process-driver/tests/subagent-in-process-driver.spec.ts
@@ -206,7 +206,8 @@ describe('startInProcessRun', () => {
     const result = await run.result
     expect(text(result.output)).toBe('child answer')
     const child = ctx.agents.get(run.id)!
-    expect(child.session.header.seedLength).toBe(seed.length)
+    expect(child.session.header.isSeeded).toBe(true)
+    expect(child.session.inheritedEventCount).toBe(seed.length)
     expect(child.session.snapshotEvents().slice(0, seed.length)).toEqual(seed)
     await run.dispose()
   })
diff --git a/packages/subagent/subagent/src/child-agent.ts b/packages/subagent/subagent/src/child-agent.ts
index b03d869df0..228b9de2f2 100644
--- a/packages/subagent/subagent/src/child-agent.ts
+++ b/packages/subagent/subagent/src/child-agent.ts
@@ -132,13 +132,13 @@ export function resolveChildAgentOptions(
  * child never had.
  * @param parent - the delegating parent agent.
  * @param childDepth - the resolved delegation depth to persist.
- * @param lineageSeedLength - how many leading events came from the parent's log.
+ * @param isSeeded - whether this child inherits a parent-log prefix, including an explicitly empty one.
  * @returns the `meta` for `ctx.agents.create()`.
  */
 export function childSessionMeta(
   parent: Agent,
   childDepth: number,
-  lineageSeedLength: number,
+  isSeeded: boolean,
 ): NonNullable<CreateAgentOptions['meta']> {
   const parentHeader = parent.session.header
   const agentPreset = parent.ctx.get('agentPresets')?.composedPreset(parent.ctx)
@@ -146,12 +146,12 @@ export function childSessionMeta(
     ...parentHeader.cwd !== undefined ? { cwd: parentHeader.cwd } : {},
     ...agentPreset === undefined ? {} : { agentPreset },
     parentSession: parentHeader.id,
+    isSeeded,
     // Navigation classification only; the descriptor remains the authority
     // for mode and continuation capability.
     origin: 'subagent',
     // Durable: the recursion budget must survive persistence and resume.
     delegationDepth: childDepth,
-    ...lineageSeedLength > 0 ? { seedLength: lineageSeedLength } : {},
   }
 }
 
diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts
index 0ccf961407..2103ce2270 100644
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -32,7 +32,8 @@ import type {
 } from '@deepseek-ai/dsh-agent'
 import { ReasoningEffortId, boundContextSummary, contentHasImage, createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm'
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import type { SessionObservation, SessionQueryEngine } from '@deepseek-ai/dsh-session-query'
 import type { ToolRestriction } from '@deepseek-ai/dsh-tools'
@@ -240,6 +241,8 @@ interface MaterializeInputs {
   create?: {
     seed: readonly SessionEvent[]
     meta: NonNullable<CreateAgentOptions['meta']>
+    /** Exact parent-log prefix length inside {@link seed}. */
+    inheritedEventCount: SessionLogOffsetType
     /** Policy captured at the delegation boundary: the parent's sandbox override plus the approval pin. */
     delegatedPolicies: DelegatedPolicyOverrides
   }
@@ -460,7 +463,7 @@ export class SubagentContinuationManager {
     spec.signal.throwIfAborted()
     this.assertAdmitting(parent)
 
-    const lineageSeedLength = prepared.seed?.length ?? 0
+    const inheritedEventCount = SessionLogOffset(prepared.seed?.length ?? 0)
     const seed = seedDescriptorTurn(childId, prepared.seed, descriptor)
     const messageId = await this.locks.run(childId, async () => {
       spec.signal.throwIfAborted()
@@ -479,7 +482,12 @@ export class SubagentContinuationManager {
         childId,
         provider: spec.provider,
         parent,
-        create: { seed, meta: childSessionMeta(parent, childDepth, lineageSeedLength), delegatedPolicies },
+        create: {
+          seed,
+          meta: childSessionMeta(parent, childDepth, prepared.seed !== undefined),
+          inheritedEventCount,
+          delegatedPolicies,
+        },
         agentOptions,
         composition: { persona: request.persona, toolFilter: request.toolFilter },
         signal: spec.signal,
@@ -987,9 +995,7 @@ export class SubagentContinuationManager {
     // Fold only the child's own suffix: a fork seed replays the parent's log,
     // which may carry an ANCESTOR's descriptor when the parent is itself a
     // continuable child.
-    const descriptor = foldSubagentDescriptor(
-      source.events.slice(source.header.seedLength ?? 0),
-    )
+    const descriptor = foldSubagentDescriptor(source.events.slice(source.inheritedEventCount))
     if (descriptor === undefined || descriptor.mode !== 'continuable') {
       throw new SubagentError(
         `subagent "${childId}" has no supported continuation state and cannot be resumed; choose a different target`,
@@ -1143,6 +1149,7 @@ export class SubagentContinuationManager {
         sessionId: childId,
         meta: create.meta,
         seed: create.seed,
+        inheritedEventCount: create.inheritedEventCount,
         agentOptions: inputs.agentOptions,
         signal: inputs.signal,
         setup,
diff --git a/packages/subagent/subagent/src/lifecycle.ts b/packages/subagent/subagent/src/lifecycle.ts
index 2f4e6d5392..ba2db8e62c 100644
--- a/packages/subagent/subagent/src/lifecycle.ts
+++ b/packages/subagent/subagent/src/lifecycle.ts
@@ -19,7 +19,8 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { foldConsumedWork } from '@deepseek-ai/dsh-agent'
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
 import { finalAssistantOutput } from './assistant-output.ts'
 import { SubagentRunId } from './types.ts'
 import type { SubagentResult, SubagentRun, SubagentRunEndInfo, SubagentRunInfo } from './types.ts'
@@ -182,7 +183,7 @@ export function createActivationObserver(
   // A cold resume replays earlier turns, so this epoch's telemetry must come
   // from the suffix it actually produced — never the whole session, which
   // would report a previous epoch's answer when this one opened no turn.
-  let boundary = 0
+  let boundary: SessionLogOffsetType = SessionLogOffset(0)
   // Assigned by `capture()`, which the disposal path always runs before
   // `settle()`; a resident epoch therefore always has its facts by then.
   let captured: ActivationTerminal = { stopReason: 'completed' }
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index 6935067e50..1d2c58ba6d 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -4,9 +4,10 @@
  * corpus; each child's mode/label is the registered `subagent` projection
  * unit's value, resolved
  * down a three-rung ladder: the registry's watermark cache for a live child,
- * a durable projection-cache row when it serves an own-suffix identity (the
- * seq gate), and one shared Session observation otherwise, validated against
- * the enumerated lifecycle. The projection fold is the single classification
+ * an unseeded durable projection-cache row, and one shared Session observation
+ * otherwise. A seeded header deliberately lacks its exact inherited cut, so
+ * it takes the body-bearing observation path before classifying an identity.
+ * The projection fold is the single classification
  * authority — this module parses no descriptor
  * itself. Absent persistence, enumeration is live-only: a cold child is
  * unreachable for resume anyway, so its absence is capability absence, not an
@@ -17,6 +18,7 @@
  */
 
 import type { Context } from '@deepseek-ai/cordis'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { Session, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionProjectionRegistry } from '@deepseek-ai/dsh-session-projection'
 import type { SessionProjectionCache } from '@deepseek-ai/dsh-session-projection-cache'
@@ -67,8 +69,8 @@ interface PositionedCandidate {
  * live-preferred merge of `ctx.sessions` and optional session persistence,
  * serving each identity from the `subagent` projection unit: the registry's
  * watermark snapshot for a live child; for a cold one, a durable
- * projection-cache read when it serves an own-suffix identity (the seq gate),
- * else one bounded-concurrency shared Session observation.
+ * projection-cache read for an unseeded lifecycle, else one bounded-concurrency
+ * shared Session observation carrying the exact inherited cut.
  * @see SubagentRuntime.listChildren for the public cancellation and failure contract.
  * @param ctx - context carrying the session store, the projection registry,
  *   optional persistence, and the optional projection cache.
@@ -220,7 +222,7 @@ async function resolveCandidateRows(
     // The unit's serializable no-value sentinel is `null`; `undefined` can
     // only mean the key was dropped at a JSON boundary. Both are no value.
     if (identity === undefined || identity === null
-      || identity.seq < (candidate.header.seedLength ?? 0)) return
+      || !candidate.live.isOwnSeq(identity.seq)) return
     rows[index] = childRow(childId, identity, 'running', subagentParents.has(childId))
   })
 
@@ -285,9 +287,8 @@ function compareCorpusRecords(a: CorpusRecord, b: CorpusRecord): number {
 }
 
 /**
- * Resolve one cold candidate down the remaining ladder: a durable
- * projection-cache row when it serves an own-suffix identity (the seq gate),
- * otherwise one shared Session observation. An absent or transiently failed
+ * Resolve one cold candidate down the remaining ladder: an unseeded durable
+ * projection-cache row, otherwise one shared Session observation. An absent or transiently failed
  * observation is one `unavailable` row retried on the next listing; an observation
  * source naming another lifecycle, and a
  * settled log the fold cannot identify — or that makes any registered unit
@@ -301,25 +302,25 @@ async function resolveColdIdentity(
   signal: AbortSignal | undefined,
 ): Promise<SubagentListEntry> {
   const childId = header.id
-  if (cache !== undefined) {
+  // A header deliberately exposes only whether a fork cut exists, not its
+  // integer. An unseeded lifecycle has the exact cut 0 and may use the cache;
+  // a seeded lifecycle must read the body before an identity seq can be
+  // classified as inherited or owned.
+  if (cache !== undefined && !header.isSeeded) {
     let cached: SubagentIdentityProjection | null | undefined
     try {
-      cached = cache.cachedSnapshot(header, ['subagent'])?.values.subagent
+      cached = cache.cachedSnapshot(header, SessionLogOffset(0), ['subagent'])?.values.subagent
     } catch {
       // Unlike the preparation fold below, a throwing cache read renders no
       // verdict: the cache is derived data, so its damage (a poisoned stored
       // row of ANY unit) silently falls through to the authoritative re-fold.
       cached = undefined
     }
-    // A child's OWN descriptor is immutable once appended, so a cached
-    // identity is final only when the seq gate proves it was folded from the
-    // own suffix: a creation-window checkpoint may instead carry a fork
-    // seed's replayed ANCESTOR descriptor (seq below `seedLength`), which
-    // must not outrank the re-fold. Everything else also falls through to
-    // preparation: an absent key (a cut before any descriptor) and the
-    // `null` sentinel, whose verdict belongs to the authoritative re-fold,
-    // not to a derived row.
-    if (cached !== undefined && cached !== null && cached.seq >= (header.seedLength ?? 0)) {
+    // An unseeded child's descriptor is owned at every valid seq. Everything
+    // else falls through to preparation: an absent key and the `null`
+    // sentinel, whose verdict belongs to the authoritative re-fold, not to a
+    // derived row.
+    if (cached !== undefined && cached !== null) {
       return childRow(childId, cached, 'inactive', hasChildren)
     }
   }
@@ -352,7 +353,7 @@ async function resolveColdIdentity(
   }
   const identity = ownedObservation.projections?.values.subagent
   if (identity === undefined || identity === null
-    || identity.seq < (header.seedLength ?? 0)) {
+    || identity.seq < ownedObservation.inheritedEventCount) {
     return { kind: 'diagnostic', id: childId, reason: 'corrupt' }
   }
   return childRow(childId, identity, 'inactive', hasChildren)
@@ -386,7 +387,7 @@ function childRow(
 
 /** Immutable header fields that distinguish one session lifecycle from another under the same id. */
 const LIFECYCLE_WITNESS_KEYS = [
-  'version', 'id', 'createdAt', 'cwd', 'parentSession', 'seedLength', 'delegationDepth',
+  'version', 'id', 'createdAt', 'cwd', 'parentSession', 'isSeeded', 'delegationDepth',
   'origin', 'agentPreset',
 ] as const
 
diff --git a/packages/subagent/subagent/src/projection-types.ts b/packages/subagent/subagent/src/projection-types.ts
index 046c32e91d..bf31d8b0aa 100644
--- a/packages/subagent/subagent/src/projection-types.ts
+++ b/packages/subagent/subagent/src/projection-types.ts
@@ -4,6 +4,8 @@
  * @module @deepseek-ai/dsh-subagent/projection-types
  */
 
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
+
 /** Durable active-turn timing for one descriptor-backed child session. */
 export interface SubagentTimingProjection {
   /** Milliseconds accumulated across completed turns after the child's own descriptor. */
@@ -31,11 +33,11 @@ export type SubagentIdentityProjection =
     label?: string
     /**
      * Seq of the `subagent/descriptor` event this identity was folded from.
-     * `seq >= header.seedLength` proves the identity comes from the child's
+     * `session.isOwnSeq(seq)` proves the identity comes from the child's
      * OWN log suffix — where a descriptor is immutable once appended — and
      * not from a fork seed's replayed ancestor descriptor.
      */
-    seq: number
+    seq: SessionSeq
   }
   | {
     /** A resumable conversation. */
@@ -43,7 +45,7 @@ export type SubagentIdentityProjection =
     /** Durable creation label from the child's descriptor. */
     label: string
     /** Seq of the folded descriptor event; see the one-shot arm for the own-suffix proof. */
-    seq: number
+    seq: SessionSeq
   }
 
 declare module '@deepseek-ai/dsh-session-projection/types' {
diff --git a/packages/subagent/subagent/src/projection.ts b/packages/subagent/subagent/src/projection.ts
index c225f71f75..6a7367d369 100644
--- a/packages/subagent/subagent/src/projection.ts
+++ b/packages/subagent/subagent/src/projection.ts
@@ -6,6 +6,7 @@
  */
 
 import { z } from 'zod'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { foldSubagentDescriptor } from './descriptor.ts'
@@ -119,12 +120,12 @@ const identityValueSchema = z.discriminatedUnion('mode', [
   z.object({
     mode: z.literal('one-shot'),
     label: z.string().optional(),
-    seq: z.number().int().nonnegative(),
+    seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
   }).strict(),
   z.object({
     mode: z.literal('continuable'),
     label: z.string(),
-    seq: z.number().int().nonnegative(),
+    seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
   }).strict(),
 ]) as unknown as z.ZodType<SubagentIdentityProjection>
 
diff --git a/packages/subagent/subagent/tests/continuation-inheritance.spec.ts b/packages/subagent/subagent/tests/continuation-inheritance.spec.ts
index 15ee9c2b96..97b05c98af 100644
--- a/packages/subagent/subagent/tests/continuation-inheritance.spec.ts
+++ b/packages/subagent/subagent/tests/continuation-inheritance.spec.ts
@@ -166,7 +166,8 @@ describe('continuable policy inheritance', () => {
     await waitNoActivation(ctx, started.childId)
 
     const loaded = await ctx.sessionPersistence.load(started.childId)
-    expect(loaded.meta.seedLength).toBeGreaterThan(0)
+    expect(loaded.meta.isSeeded).toBe(true)
+    expect(loaded.inheritedEventCount).toBeGreaterThan(0)
     expect(policyEvents(loaded.events)).toMatchObject([
       { type: 'approval/policy', data: { policy: 'never', source: 'delegation' } },
     ])
@@ -238,7 +239,8 @@ describe('continuable policy inheritance', () => {
     await waitNoActivation(ctx, started.childId)
 
     const loaded = await ctx.sessionPersistence.load(started.childId)
-    expect(loaded.meta.seedLength).toBeGreaterThan(0)
+    expect(loaded.meta.isSeeded).toBe(true)
+    expect(loaded.inheritedEventCount).toBeGreaterThan(0)
     expect(loaded.events.filter(event => event.type === 'sandbox/mode')).toMatchObject([
       { data: { mode: 'workspace-write' } },
       { data: { mode: 'read-only', source: 'delegation' } },
diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts
index 904ee91180..851720f228 100644
--- a/packages/subagent/subagent/tests/continuation.spec.ts
+++ b/packages/subagent/subagent/tests/continuation.spec.ts
@@ -513,7 +513,8 @@ describe('SubagentRuntime.startContinuable', () => {
     // rather than restarting at 1, so the replayed child log stays balanced.
     expect(descriptorIndex).toBeGreaterThanOrEqual(0)
     expect(childTurn?.type === 'turn/start' && childTurn.data.turn).toBe(2)
-    expect(loaded.meta.seedLength).toBeGreaterThan(0)
+    expect(loaded.meta.isSeeded).toBe(true)
+    expect(loaded.inheritedEventCount).toBeGreaterThan(0)
   })
 
   it('records the declared persona in the descriptor and reapplies it on cold resume', async () => {
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index 31109f1396..54d34f8c95 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -7,7 +7,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import type { SessionObservation } from '@deepseek-ai/dsh-session-query'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
@@ -103,14 +103,16 @@ async function authorChild(
   id: string,
   header: Partial<SessionHeader>,
   events: SessionEvent[],
+  inheritedEventCount = SessionLogOffset(0),
 ): Promise<SessionId> {
   const sessionId = SessionId(id)
   await ctx.sessionPersistence.create({
     version: SESSION_FORMAT_VERSION,
     id: sessionId,
     createdAt: 1,
+    isSeeded: false,
     ...header,
-  })
+  }, header.isSeeded === true ? inheritedEventCount : undefined)
   await ctx.sessionPersistence.append(sessionId, events)
   return sessionId
 }
@@ -277,6 +279,7 @@ describe('SubagentRuntime.listChildren', () => {
       version: SESSION_FORMAT_VERSION,
       id: coldParent,
       createdAt: 1,
+      isSeeded: false,
     })
     await ctx.sessionPersistence.append(coldParent, [
       { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
@@ -448,11 +451,11 @@ describe('SubagentRuntime.listChildren', () => {
     const events = childEvents(descriptorPayload('twice'))
     events.splice(3, 0, {
       type: 'subagent/descriptor',
-      seq: 3,
+      seq: SessionSeq(3),
       time: 3,
       data: descriptorPayload('twice again'),
     } as SessionEvent)
-    events[4] = { ...events[4]!, seq: 4 }
+    events[4] = { ...events[4]!, seq: SessionSeq(4) }
     const doubled = await authorChild(ctx, '00000000-0000-4000-8000-00000000dupe', {
       parentSession: parent.id,
       origin: 'subagent',
@@ -501,11 +504,11 @@ describe('SubagentRuntime.listChildren', () => {
     const events = childEvents(descriptorPayload('was valid'))
     events.splice(3, 0, {
       type: 'subagent/descriptor',
-      seq: 3,
+      seq: SessionSeq(3),
       time: 3,
       data: { version: SUBAGENT_DESCRIPTOR_VERSION, mode: 'continuable', provider: 7 },
     } as SessionEvent)
-    events[4] = { ...events[4]!, seq: 4 }
+    events[4] = { ...events[4]!, seq: SessionSeq(4) }
     const invalidated = await authorChild(ctx, '00000000-0000-4000-8000-00000000ad01', {
       parentSession: parent.id,
       origin: 'subagent',
@@ -521,12 +524,12 @@ describe('SubagentRuntime.listChildren', () => {
       parentSession: parent.id,
       origin: 'subagent',
     }, childEvents(descriptorPayload('disk label')))
-    // seq 2 >= seedLength 0: the cached identity provably comes from the
-    // child's own suffix, so it is final and the log is never re-read — the
+    // The unseeded child's cut is exactly 0, so its cached identity is final
+    // and the log is never re-read — the
     // divergent label proves the row, not the log, produced the entry.
     ctx.sessionProjectionCache.cachedSnapshot = () => ({
-      asOfSeq: 2,
-      values: { subagent: { mode: 'continuable', label: 'cached own', seq: 2 } },
+      asOfSeq: SessionSeq(2),
+      values: { subagent: { mode: 'continuable', label: 'cached own', seq: SessionSeq(2) } },
     })
     const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
@@ -549,14 +552,14 @@ describe('SubagentRuntime.listChildren', () => {
     ] as SessionEvent[]
     const forkChild = await authorChild(ctx, '00000000-0000-4000-8000-00000000ae02', {
       parentSession: parent.id,
-      seedLength: seed.length,
+      isSeeded: true,
       origin: 'subagent',
-    }, events)
-    // A creation-window checkpoint carried the ANCESTOR identity: its seq 2
-    // fails the own-suffix gate (< seedLength 4), so preparation rules.
+    }, events, SessionLogOffset(seed.length))
+    // A seeded header does not expose the integer cut, so a misleading cached
+    // ANCESTOR identity is bypassed and authoritative preparation rules.
     ctx.sessionProjectionCache.cachedSnapshot = () => ({
-      asOfSeq: 2,
-      values: { subagent: { mode: 'continuable', label: 'ancestor label', seq: 2 } },
+      asOfSeq: SessionSeq(2),
+      values: { subagent: { mode: 'continuable', label: 'ancestor label', seq: SessionSeq(2) } },
     })
     const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
@@ -572,7 +575,7 @@ describe('SubagentRuntime.listChildren', () => {
     ['createdAt', (meta: SessionHeader): SessionHeader => ({ ...meta, createdAt: meta.createdAt + 1 })],
     ['cwd', (meta: SessionHeader): SessionHeader => ({ ...meta, cwd: '/elsewhere' })],
     ['parentSession', (meta: SessionHeader): SessionHeader => ({ ...meta, parentSession: SessionId('another-parent') })],
-    ['seedLength', (meta: SessionHeader): SessionHeader => ({ ...meta, seedLength: (meta.seedLength ?? 0) + 1 })],
+    ['isSeeded', (meta: SessionHeader): SessionHeader => ({ ...meta, isSeeded: !meta.isSeeded })],
     ['delegationDepth', (meta: SessionHeader): SessionHeader => ({ ...meta, delegationDepth: (meta.delegationDepth ?? 0) + 1 })],
   ] as const)('diagnoses an inspection returning another lifecycle (%s) as corrupt', async (_field, mutate) => {
     const { ctx, parent } = await setup([textResponse('done')])
@@ -603,7 +606,7 @@ describe('SubagentRuntime.listChildren', () => {
       origin: 'subagent',
     }, childEvents(descriptorPayload('actually valid')))
     // A stale cached sentinel must not out-rank the authoritative re-fold.
-    ctx.sessionProjectionCache.cachedSnapshot = () => ({ asOfSeq: 0, values: { subagent: null } })
+    ctx.sessionProjectionCache.cachedSnapshot = () => ({ asOfSeq: SessionSeq(0), values: { subagent: null } })
     const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
       kind: 'child', id: healthy, label: 'actually valid', mode: 'continuable',
@@ -663,9 +666,9 @@ describe('SubagentRuntime.listChildren', () => {
     const seed = childEvents(descriptorPayload('ancestor label'))
     const forkChild = await authorChild(ctx, '00000000-0000-4000-8000-0000000000f0', {
       parentSession: parent.id,
-      seedLength: seed.length,
+      isSeeded: true,
       origin: 'subagent',
-    }, seed)
+    }, seed, SessionLogOffset(seed.length))
     const entries = await ctx.subagents.listChildren(parent.id)
     expect(entries).toEqual([{ kind: 'diagnostic', id: forkChild, reason: 'corrupt' }])
   })
@@ -786,14 +789,14 @@ describe('SubagentRuntime.listChildren', () => {
     const compactedEvents = childEvents(descriptorPayload('twin child'))
     compactedEvents.push({
       type: 'user/message',
-      seq: 4,
+      seq: SessionSeq(4),
       time: 5,
       data: createUserMessage({
         content: [{ type: 'text', text: 'summary of everything' }],
         source: { kind: 'plugin', plugin: 'compact' },
       }),
-      surfaceOp: { op: 'replace', start: 1, end: 1 },
-      sourceEventSeqs: [1],
+      surfaceOp: { op: 'replace', start: SessionSeq(1), end: SessionSeq(1) },
+      sourceEventSeqs: [SessionSeq(1)],
     })
     const compacted = await authorChild(ctx, '00000000-0000-4000-8000-00000000c1de', {
       parentSession: parent.id,
@@ -874,7 +877,7 @@ describe('SubagentRuntime.listChildren', () => {
     // points; both writes are fail-soft asynchronous, so wait for the row.
     const header = (await ctx.sessionPersistence.list()).find(meta => meta.id === childId)
     await vi.waitFor(() => {
-      expect(ctx.sessionProjectionCache.cachedSnapshot(header!)?.values.subagent).toBeDefined()
+      expect(ctx.sessionProjectionCache.cachedSnapshot(header!, SessionLogOffset(0))?.values.subagent).toBeDefined()
     }, { timeout: 5_000 })
     const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
@@ -900,7 +903,7 @@ describe('SubagentRuntime.listChildren', () => {
     expect(inspect).toHaveBeenCalledTimes(1)
     // A stored row whose cut predates the descriptor: the subagent key is
     // absent from the served values, and preparation still rules.
-    ctx.sessionProjectionCache.cachedSnapshot = () => ({ asOfSeq: 0, values: {} })
+    ctx.sessionProjectionCache.cachedSnapshot = () => ({ asOfSeq: SessionSeq(0), values: {} })
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual(expected)
     expect(inspect).toHaveBeenCalledTimes(2)
   })
diff --git a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
index b719c1e205..082dbde76e 100644
--- a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
@@ -154,9 +154,8 @@ describe('dsh-tool-subagent-control', () => {
     const loaded = await ctx.sessionPersistence.load(started.childId)
     const promptIndex = loaded.events.findIndex(event => event.type === 'user/message'
       && event.data.content.some(block => block.type === 'text' && block.text === 'fork task'))
-    const seedLength = loaded.meta.seedLength
-    if (seedLength === undefined) throw new Error('expected a forked Session seed')
-    expect(promptIndex).toBeGreaterThanOrEqual(seedLength)
+    expect(loaded.meta.isSeeded).toBe(true)
+    expect(promptIndex).toBeGreaterThanOrEqual(loaded.inheritedEventCount)
     const prompt = loaded.events[promptIndex]
     if (prompt?.type !== 'user/message') throw new Error('expected the initial fork task')
     const texts = prompt.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index 4516dafacc..03b56a3c9d 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -16,6 +16,7 @@ import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent'
 import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import {
   assertSubagentMaxDepth,
   parentAgentOptionsForDelegation,
@@ -616,7 +617,7 @@ export function apply(ctx: Context, config: Config): void {
 
   const selectForAgent = (agent: NonNullable<Context['agent']>): ModelSelectionPolicy | undefined => {
     const freshSession = agent.session.firstLiveSeq === 0
-      && agent.session.eventAt(0)?.type !== 'session/end-seed'
+      && agent.session.eventAt(SessionSeq(0))?.type !== 'session/end-seed'
     let allowedModels = subagentModelSelectionPolicy(ctx.sessionProjections, agent.session)
     if (allowedModels === undefined) {
       const parentId = agent.session.header.origin === 'subagent'
diff --git a/packages/terminal/terminal-bash/tests/index.spec.ts b/packages/terminal/terminal-bash/tests/index.spec.ts
index 4799709b3f..a3edc02058 100644
--- a/packages/terminal/terminal-bash/tests/index.spec.ts
+++ b/packages/terminal/terminal-bash/tests/index.spec.ts
@@ -50,7 +50,9 @@ function config(): ResolvedConfig {
 
 function agent(ctx: Context, cwd?: string): Agent {
   const id = SessionId('agent')
-  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0, ...cwd === undefined ? {} : { cwd } })
+  const session = Session.create(id, undefined, {
+    version: 0, id, createdAt: 0, isSeeded: false, ...cwd === undefined ? {} : { cwd },
+  })
   return {
     id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
     status: 'idle',
diff --git a/packages/test-support/llm-replay/src/index.ts b/packages/test-support/llm-replay/src/index.ts
index bea88ebfce..7be893cc95 100644
--- a/packages/test-support/llm-replay/src/index.ts
+++ b/packages/test-support/llm-replay/src/index.ts
@@ -12,7 +12,8 @@ import { delimiter as pathDelimiter } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-compaction'
 import type {} from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
-import { decodeSeqRanges, decodeStorageRecord, type SessionEvent } from '@deepseek-ai/dsh-session'
+import { decodeSeqRanges, decodeStorageRecord, SessionLogOffset, type SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
 import type {
   ContentBlock,
   GenerateOptions,
@@ -180,7 +181,7 @@ export interface SessionScript {
  */
 export function parseSessionLog(text: string): SessionEvent[] {
   const events: SessionEvent[] = []
-  let nextSeq = 0
+  let nextSeq: SessionLogOffsetType = SessionLogOffset(0)
   let headerSkipped = false
   // The JSONL backend guarantees line 0 is the session header. Projected
   // fixtures omit event envelopes; synthesize them while decoding so callers
@@ -218,7 +219,7 @@ export function parseSessionLog(text: string): SessionEvent[] {
       throw new Error(`session snapshot line ${index + 1}: ${detail}`, { cause: error })
     }
     events.push(...decoded)
-    nextSeq += decoded.length
+    nextSeq = SessionLogOffset(nextSeq + decoded.length)
   }
   return events
 }
@@ -227,15 +228,19 @@ export function parseSessionLog(text: string): SessionEvent[] {
  * Read replay identity, ordering, and fork-seed facts from the JSONL header.
  *
  * @param text - the raw `.jsonl` file contents (only the header line is read).
- * @returns the header's `id`, `createdAt`, and `seedLength`, defaulted when absent.
+ * @returns the header's `id`, `createdAt`, and inherited-event count, defaulted when absent.
  */
-export function parseSessionHeader(text: string): { id: string; createdAt: number; seedLength: number } {
+export function parseSessionHeader(text: string): {
+  id: string
+  createdAt: number
+  inheritedEventCount: SessionLogOffsetType
+} {
   const firstLine = text.split('\n').find(line => line.trim().length > 0) ?? '{}'
   const parsed = JSON.parse(firstLine) as { id?: unknown; createdAt?: unknown; seedLength?: unknown }
   return {
     id: typeof parsed.id === 'string' ? parsed.id : '',
     createdAt: typeof parsed.createdAt === 'number' ? parsed.createdAt : 0,
-    seedLength: typeof parsed.seedLength === 'number' ? parsed.seedLength : 0,
+    inheritedEventCount: SessionLogOffset(typeof parsed.seedLength === 'number' ? parsed.seedLength : 0),
   }
 }
 
@@ -606,7 +611,7 @@ function deriveScriptFromFile(file: string): ReplayEntry[] {
 
 /**
  * Load the primary and child scripts in bind order. Child derivation begins at
- * `seedLength` so inherited parent chunks are never replayed as child calls.
+ * the v0 header's inherited-event cut so parent chunks are never replayed as child calls.
  *
  * @param config - the fixture paths: the primary log plus any recorded child logs.
  * @returns the primary script first, then the child scripts in bind order.
@@ -631,7 +636,7 @@ export function loadSessionScripts(config: ReplayConfig): SessionScript[] {
     const header = parseSessionHeader(text)
     // Derive the child's script from its own events only — events AT OR after the seed
     // boundary.
-    const ownEvents = parseSessionLog(text).slice(header.seedLength)
+    const ownEvents = parseSessionLog(text).slice(header.inheritedEventCount)
     children.push({
       recordedId: header.id,
       createdAt: header.createdAt,
diff --git a/packages/test-support/llm-replay/tests/llm-replay.spec.ts b/packages/test-support/llm-replay/tests/llm-replay.spec.ts
index 6cdf8c4c7e..8f2a6dd059 100644
--- a/packages/test-support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/test-support/llm-replay/tests/llm-replay.spec.ts
@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { CompactionId } from '@deepseek-ai/dsh-compaction'
 import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
@@ -59,7 +60,7 @@ function sessionJsonl(events: SessionEvent[], header?: { id?: string; createdAt?
 }
 
 /** A SessionEvent of type assistant/chunk for (turn, step). */
-function chunkEvent(seq: number, turn: number, step: number, chunk: StreamChunk): SessionEvent {
+function chunkEvent(seq: SessionSeq, turn: number, step: number, chunk: StreamChunk): SessionEvent {
   return { type: 'assistant/chunk', seq, time: 0, data: { turn, step, chunk } }
 }
 
@@ -70,7 +71,7 @@ let file: string
 function writeSession(filename: string, header: { id: string; createdAt: number }, calls: StreamChunk[][]): string {
   let seq = 1
   const events: SessionEvent[] = []
-  calls.forEach((chunks, step) => { for (const c of chunks) events.push(chunkEvent(seq++, 1, step + 1, c)) })
+  calls.forEach((chunks, step) => { for (const c of chunks) events.push(chunkEvent(SessionSeq(seq++), 1, step + 1, c)) })
   const path = join(dir, filename)
   writeFileSync(path, sessionJsonl(events, header), 'utf8')
   return path
@@ -93,20 +94,20 @@ async function drain(iter: AsyncIterable<StreamChunk>): Promise<StreamChunk[]> {
 
 describe('parseSessionLog', () => {
   it('skips the header line and parses each event', () => {
-    const events = [chunkEvent(1, 1, 1, TEXT_CHUNKS[0] as StreamChunk)]
+    const events = [chunkEvent(SessionSeq(1), 1, 1, TEXT_CHUNKS[0] as StreamChunk)]
     expect(parseSessionLog(sessionJsonl(events))).toEqual(events)
   })
 
   it('ignores blank lines', () => {
     const header = JSON.stringify({ type: 'session', version: 0, id: 's1', createdAt: 0 })
-    const ev = chunkEvent(1, 1, 1, TEXT_CHUNKS[0] as StreamChunk)
+    const ev = chunkEvent(SessionSeq(1), 1, 1, TEXT_CHUNKS[0] as StreamChunk)
     expect(parseSessionLog(`${header}\n\n${JSON.stringify(ev)}\n\n`)).toEqual([ev])
   })
 
   it('expands range-encoded source provenance', () => {
     const header = JSON.stringify({ type: 'session', version: 0, id: 's1', createdAt: 0 })
     const event = {
-      ...chunkEvent(4, 1, 1, TEXT_CHUNKS[0] as StreamChunk),
+      ...chunkEvent(SessionSeq(4), 1, 1, TEXT_CHUNKS[0] as StreamChunk),
       sourceEventSeqs: [[1, 3], 5],
     }
     expect(parseSessionLog(`${header}\n${JSON.stringify(event)}\n`)).toEqual([{
@@ -118,7 +119,7 @@ describe('parseSessionLog', () => {
   it('reports malformed range provenance with its source line', () => {
     const header = JSON.stringify({ type: 'session', version: 0, id: 's1', createdAt: 0 })
     const event = {
-      ...chunkEvent(4, 1, 1, TEXT_CHUNKS[0] as StreamChunk),
+      ...chunkEvent(SessionSeq(4), 1, 1, TEXT_CHUNKS[0] as StreamChunk),
       sourceEventSeqs: [[3, 1]],
     }
     expect(() => parseSessionLog(`${header}\n${JSON.stringify(event)}\n`))
@@ -138,9 +139,9 @@ describe('parseSessionLog', () => {
       data: { turn: 1, step: 1, index: 0, dt: [0, 0], texts: ['a', 'b', 'c'] },
     })
     expect(parseSessionLog(`${header}\n${row}\n`)).toEqual([
-      chunkEvent(1, 1, 1, { type: 'text-delta', index: 0, text: 'a' }),
-      chunkEvent(2, 1, 1, { type: 'text-delta', index: 0, text: 'b' }),
-      chunkEvent(3, 1, 1, { type: 'text-delta', index: 0, text: 'c' }),
+      chunkEvent(SessionSeq(1), 1, 1, { type: 'text-delta', index: 0, text: 'a' }),
+      chunkEvent(SessionSeq(2), 1, 1, { type: 'text-delta', index: 0, text: 'b' }),
+      chunkEvent(SessionSeq(3), 1, 1, { type: 'text-delta', index: 0, text: 'c' }),
     ])
   })
 
@@ -153,15 +154,15 @@ describe('parseSessionLog', () => {
     })
     expect(parseSessionLog(`${header}\n${ordinary}\n${packed}\n`)).toEqual([
       { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } },
-      chunkEvent(1, 1, 1, { type: 'text-delta', index: 0, text: 'a' }),
-      { ...chunkEvent(2, 1, 1, { type: 'text-delta', index: 0, text: 'b' }), time: 3 },
+      chunkEvent(SessionSeq(1), 1, 1, { type: 'text-delta', index: 0, text: 'a' }),
+      { ...chunkEvent(SessionSeq(2), 1, 1, { type: 'text-delta', index: 0, text: 'b' }), time: 3 },
     ])
   })
 })
 
 describe('deriveReplayScript', () => {
   it('groups one finished assistant/chunk stream into one replay entry', () => {
-    const events: SessionEvent[] = TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))
+    const events: SessionEvent[] = TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))
     expect(deriveReplayScript(events)).toEqual([{ kind: 'chunks', chunks: TEXT_CHUNKS }])
   })
 
@@ -172,8 +173,8 @@ describe('deriveReplayScript', () => {
     ]
     let seq = 1
     const events: SessionEvent[] = [
-      ...failed.map(chunk => chunkEvent(seq++, 1, 1, chunk)),
-      ...TEXT_CHUNKS.map(chunk => chunkEvent(seq++, 1, 1, chunk)),
+      ...failed.map(chunk => chunkEvent(SessionSeq(seq++), 1, 1, chunk)),
+      ...TEXT_CHUNKS.map(chunk => chunkEvent(SessionSeq(seq++), 1, 1, chunk)),
     ]
     expect(deriveReplayScript(events)).toEqual([
       { kind: 'chunks', chunks: failed },
@@ -190,8 +191,8 @@ describe('deriveReplayScript', () => {
     ]
     let seq = 1
     const events: SessionEvent[] = [
-      ...callA.map(c => chunkEvent(seq++, 1, 1, c)),
-      ...callB.map(c => chunkEvent(seq++, 1, 2, c)), // same turn, next step
+      ...callA.map(c => chunkEvent(SessionSeq(seq++), 1, 1, c)),
+      ...callB.map(c => chunkEvent(SessionSeq(seq++), 1, 2, c)), // same turn, next step
     ]
     expect(deriveReplayScript(events)).toEqual([
       { kind: 'chunks', chunks: callA },
@@ -202,8 +203,8 @@ describe('deriveReplayScript', () => {
   it('separates calls across turns too', () => {
     let seq = 1
     const events: SessionEvent[] = [
-      ...TEXT_CHUNKS.map(c => chunkEvent(seq++, 1, 1, c)),
-      ...TEXT_CHUNKS.map(c => chunkEvent(seq++, 2, 1, c)), // new turn, step resets to 1
+      ...TEXT_CHUNKS.map(c => chunkEvent(SessionSeq(seq++), 1, 1, c)),
+      ...TEXT_CHUNKS.map(c => chunkEvent(SessionSeq(seq++), 2, 1, c)), // new turn, step resets to 1
     ]
     expect(deriveReplayScript(events)).toHaveLength(2)
   })
@@ -211,9 +212,9 @@ describe('deriveReplayScript', () => {
   it('ignores non-assistant/chunk events', () => {
     let seq = 1
     const events: SessionEvent[] = [
-      { type: 'turn/start', seq: seq++, time: 0, data: { turn: 1 } },
-      ...TEXT_CHUNKS.map(c => chunkEvent(seq++, 1, 1, c)),
-      { type: 'turn/end', seq: seq++, time: 0, data: { turn: 1, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(seq++), time: 0, data: { turn: 1 } },
+      ...TEXT_CHUNKS.map(c => chunkEvent(SessionSeq(seq++), 1, 1, c)),
+      { type: 'turn/end', seq: SessionSeq(seq++), time: 0, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
     expect(deriveReplayScript(events)).toEqual([{ kind: 'chunks', chunks: TEXT_CHUNKS }])
   })
@@ -227,7 +228,7 @@ describe('deriveReplayScript', () => {
       { type: 'block-start', index: 0, blockType: 'text' },
       { type: 'finish', reason: { kind: 'error', failure: { message: 'boom', code: 'X' } } },
     ]
-    const events = errChunks.map((c, i) => chunkEvent(i + 1, 1, 1, c))
+    const events = errChunks.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))
     expect(deriveReplayScript(events)).toEqual([{ kind: 'chunks', chunks: errChunks }])
   })
 
@@ -246,31 +247,31 @@ describe('deriveReplayScript', () => {
     ]
     let seq = 1
     const events: SessionEvent[] = [
-      ...overflow.map(chunk => chunkEvent(seq++, 1, 2, chunk)),
+      ...overflow.map(chunk => chunkEvent(SessionSeq(seq++), 1, 2, chunk)),
       {
         type: 'compaction/start',
-        seq: seq++,
+        seq: SessionSeq(seq++),
         time: 0,
         data: { compactionId: COMPACTION_ID, turn: 1 },
       },
       {
         type: 'compaction/summary',
-        seq: seq++,
+        seq: SessionSeq(seq++),
         time: 0,
         data: {
           compactionId: COMPACTION_ID,
           summary: rawOutput,
           rawOutput,
           llmStreamCall: true,
-          shadowedRange: { start: 1, end: 1 },
-          shadowedSeqs: [1],
+          shadowedRange: { start: SessionSeq(1), end: SessionSeq(1) },
+          shadowedSeqs: [SessionSeq(1)],
           shadowedTokenCount: 20,
           provider: 'mock',
           model: 'mock',
           usage,
         },
       },
-      ...TEXT_CHUNKS.map(chunk => chunkEvent(seq++, 1, 2, chunk)),
+      ...TEXT_CHUNKS.map(chunk => chunkEvent(SessionSeq(seq++), 1, 2, chunk)),
     ]
 
     expect(deriveReplayScript(events)).toEqual([
@@ -283,13 +284,13 @@ describe('deriveReplayScript', () => {
   it('does not infer an LLM call from compaction/summary without raw output', () => {
     const event: SessionEvent<'compaction/summary'> = {
       type: 'compaction/summary',
-      seq: 1,
+      seq: SessionSeq(1),
       time: 0,
       data: {
         compactionId: COMPACTION_ID,
         summary: [{ type: 'text', text: 'template result' }],
-        shadowedRange: { start: 1, end: 1 },
-        shadowedSeqs: [1],
+        shadowedRange: { start: SessionSeq(1), end: SessionSeq(1) },
+        shadowedSeqs: [SessionSeq(1)],
         shadowedTokenCount: 20,
         provider: 'template',
         model: 'template',
@@ -303,14 +304,14 @@ describe('deriveReplayScript', () => {
     const block = { type: 'text' as const, text: 'remote summary' }
     const event: SessionEvent<'compaction/summary'> = {
       type: 'compaction/summary',
-      seq: 1,
+      seq: SessionSeq(1),
       time: 0,
       data: {
         compactionId: COMPACTION_ID,
         summary: [block],
         rawOutput: [block],
-        shadowedRange: { start: 1, end: 1 },
-        shadowedSeqs: [1],
+        shadowedRange: { start: SessionSeq(1), end: SessionSeq(1) },
+        shadowedSeqs: [SessionSeq(1)],
         shadowedTokenCount: 20,
         provider: 'remote',
         model: 'remote',
@@ -348,15 +349,15 @@ describe('deriveReplayScript', () => {
     const block = { type: 'text' as const, text: 'summary without usage' }
     const event: SessionEvent<'compaction/summary'> = {
       type: 'compaction/summary',
-      seq: 1,
+      seq: SessionSeq(1),
       time: 0,
       data: {
         compactionId: COMPACTION_ID,
         summary: [block],
         rawOutput: [block],
         llmStreamCall: true,
-        shadowedRange: { start: 1, end: 1 },
-        shadowedSeqs: [1],
+        shadowedRange: { start: SessionSeq(1), end: SessionSeq(1) },
+        shadowedSeqs: [SessionSeq(1)],
         shadowedTokenCount: 20,
         provider: 'mock',
         model: 'mock',
@@ -376,40 +377,40 @@ describe('deriveReplayScript', () => {
   it('throws on a group that lacks a terminal finish chunk (a thrown stream)', () => {
     // A thrown stream(): prefix chunks logged, then turn/end (error reason), NO finish.
     const events: SessionEvent[] = [
-      chunkEvent(1, 1, 1, { type: 'block-start', index: 0, blockType: 'text' }),
-      chunkEvent(2, 1, 1, { type: 'text-delta', index: 0, text: 'par' }),
-      { type: 'turn/end', seq: 3, time: 0, data: { turn: 1, reason: { kind: 'error', error: { message: 'x', code: 'UNKNOWN' } } } },
+      chunkEvent(SessionSeq(1), 1, 1, { type: 'block-start', index: 0, blockType: 'text' }),
+      chunkEvent(SessionSeq(2), 1, 1, { type: 'text-delta', index: 0, text: 'par' }),
+      { type: 'turn/end', seq: SessionSeq(3), time: 0, data: { turn: 1, reason: { kind: 'error', error: { message: 'x', code: 'UNKNOWN' } } } },
     ]
     expect(() => deriveReplayScript(events)).toThrow(/without a finish chunk.*replay\.override\.json/s)
   })
 
   it('names the offending (turn, step) when a group is incomplete', () => {
     const events: SessionEvent[] = [
-      chunkEvent(1, 2, 3, { type: 'block-start', index: 0, blockType: 'text' }),
+      chunkEvent(SessionSeq(1), 2, 3, { type: 'block-start', index: 0, blockType: 'text' }),
     ]
     expect(() => deriveReplayScript(events)).toThrow(/2\/3/)
   })
 
   it('rejects an unfinished call before consuming chunks from a new step', () => {
     const events: SessionEvent[] = [
-      chunkEvent(1, 1, 1, { type: 'block-start', index: 0, blockType: 'text' }),
-      chunkEvent(2, 1, 2, { type: 'finish', reason: { kind: 'stop' } }),
+      chunkEvent(SessionSeq(1), 1, 1, { type: 'block-start', index: 0, blockType: 'text' }),
+      chunkEvent(SessionSeq(2), 1, 2, { type: 'finish', reason: { kind: 'stop' } }),
     ]
     expect(() => deriveReplayScript(events)).toThrow(/model call 1\/1 ended without a finish chunk/)
   })
 
   it('rejects an unfinished call at a compact summary boundary', () => {
     const events: SessionEvent[] = [
-      chunkEvent(1, 1, 1, { type: 'block-start', index: 0, blockType: 'text' }),
+      chunkEvent(SessionSeq(1), 1, 1, { type: 'block-start', index: 0, blockType: 'text' }),
       {
         type: 'compaction/summary',
-        seq: 2,
+        seq: SessionSeq(2),
         time: 0,
         data: {
           compactionId: COMPACTION_ID,
           summary: [{ type: 'text', text: 'external checkpoint' }],
-          shadowedRange: { start: 1, end: 1 },
-          shadowedSeqs: [1],
+          shadowedRange: { start: SessionSeq(1), end: SessionSeq(1) },
+          shadowedSeqs: [SessionSeq(1)],
           shadowedTokenCount: 20,
           provider: 'external',
           model: 'external',
@@ -423,7 +424,7 @@ describe('deriveReplayScript', () => {
 
 describe('loadReplayScript', () => {
   it('derives from the session JSONL when no override is present', () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))), 'utf8')
     expect(loadReplayScript({ file })).toEqual([{ kind: 'chunks', chunks: TEXT_CHUNKS }])
   })
 
@@ -436,7 +437,7 @@ describe('loadReplayScript', () => {
   })
 
   it('falls back to the JSONL when the override path is set but absent', () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))), 'utf8')
     expect(loadReplayScript({ file, overrideFile: join(dir, 'nope.json') }))
       .toEqual([{ kind: 'chunks', chunks: TEXT_CHUNKS }])
   })
@@ -460,8 +461,8 @@ describe('loadReplayScript', () => {
     ]
     let seq = 1
     writeFileSync(file, sessionJsonl([
-      ...TEXT_CHUNKS.map(c => chunkEvent(seq++, 1, 1, c)),
-      ...callB.map(c => chunkEvent(seq++, 1, 2, c)),
+      ...TEXT_CHUNKS.map(c => chunkEvent(SessionSeq(seq++), 1, 1, c)),
+      ...callB.map(c => chunkEvent(SessionSeq(seq++), 1, 2, c)),
     ]), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
     writeFileSync(overrideFile, JSON.stringify({
@@ -474,7 +475,7 @@ describe('loadReplayScript', () => {
   })
 
   it('patches form: at == derived length appends (the retry-attempt slot)', () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
     writeFileSync(overrideFile, JSON.stringify({
       patches: [
@@ -489,7 +490,7 @@ describe('loadReplayScript', () => {
   })
 
   it('patches form: an out-of-range index fails loud with the derived length', () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
     writeFileSync(overrideFile, JSON.stringify({ patches: [{ at: 2, entry: { kind: 'hang' } }] }), 'utf8')
     expect(() => loadReplayScript({ file, overrideFile })).toThrow(/patch index 2 out of range.*1 call/s)
@@ -521,7 +522,7 @@ describe('loadReplayScript', () => {
   })
 
   it('rejects duplicate patch indexes instead of silently taking the last one', () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
     writeFileSync(overrideFile, JSON.stringify({
       patches: [
@@ -538,7 +539,7 @@ describe('installLlmReplay (through the real LlmRuntime)', () => {
     let seq = 1
     const events: SessionEvent[] = []
     calls.forEach((chunks, step) => {
-      for (const c of chunks) events.push(chunkEvent(seq++, 1, step + 1, c))
+      for (const c of chunks) events.push(chunkEvent(SessionSeq(seq++), 1, step + 1, c))
     })
     writeFileSync(file, sessionJsonl(events), 'utf8')
   }
@@ -1038,7 +1039,7 @@ describe('installLlmReplay (through the real LlmRuntime)', () => {
     writeLog(TEXT_CHUNKS)
     const childFile = join(dir, 'session.1.jsonl')
     writeFileSync(childFile, sessionJsonl(
-      TEXT_CHUNKS.map((chunk, i) => chunkEvent(i + 1, 1, 1, chunk)),
+      TEXT_CHUNKS.map((chunk, i) => chunkEvent(SessionSeq(i + 1), 1, 1, chunk)),
       { id: 'child', createdAt: 10 },
     ), 'utf8')
     const ctx = new Context()
@@ -1051,22 +1052,27 @@ describe('installLlmReplay (through the real LlmRuntime)', () => {
 })
 
 describe('parseSessionHeader', () => {
-  it('reads id, createdAt, and seedLength off the header line', () => {
+  it('reads id, createdAt, and the inherited event count off the v0 header line', () => {
     expect(parseSessionHeader(sessionJsonl([], { id: 'abc', createdAt: 42 })))
-      .toEqual({ id: 'abc', createdAt: 42, seedLength: 0 })
+      .toEqual({ id: 'abc', createdAt: 42, inheritedEventCount: 0 })
   })
 
-  it('reads a non-zero seedLength (a fork child header)', () => {
+  it('reads a non-zero v0 seedLength as the inherited event count', () => {
     expect(parseSessionHeader('{"type":"session","version":0,"id":"child","createdAt":7,"seedLength":4}\n'))
-      .toEqual({ id: 'child', createdAt: 7, seedLength: 4 })
+      .toEqual({ id: 'child', createdAt: 7, inheritedEventCount: 4 })
   })
 
-  it('falls back to id="" / createdAt=0 / seedLength=0 when the header lacks them', () => {
-    expect(parseSessionHeader('{"type":"session","version":0}\n')).toEqual({ id: '', createdAt: 0, seedLength: 0 })
+  it('falls back to id="" / createdAt=0 / inheritedEventCount=0 when the header lacks them', () => {
+    expect(parseSessionHeader('{"type":"session","version":0}\n')).toEqual({ id: '', createdAt: 0, inheritedEventCount: 0 })
   })
 
   it('falls back on an empty buffer (no header line)', () => {
-    expect(parseSessionHeader('')).toEqual({ id: '', createdAt: 0, seedLength: 0 })
+    expect(parseSessionHeader('')).toEqual({ id: '', createdAt: 0, inheritedEventCount: 0 })
+  })
+
+  it.each([-1, 0.5, Number.MAX_SAFE_INTEGER + 1])('rejects invalid v0 seedLength %s', (seedLength) => {
+    expect(() => parseSessionHeader(JSON.stringify({ type: 'session', version: 0, seedLength })))
+      .toThrow(/SessionLogOffset/)
   })
 })
 
@@ -1105,10 +1111,10 @@ describe('loadSessionScripts', () => {
     // The child fixture: 2 seeded parent events (a chunk + its finish) then the
     // child's own turn. seedLength = 2 marks where the inherited prefix ends.
     const childEvents: SessionEvent[] = [
-      chunkEvent(0, 1, 1, parentChunk),
-      chunkEvent(1, 1, 1, { type: 'finish', reason: { kind: 'stop' } }),
-      chunkEvent(2, 2, 1, childChunks[0]!),
-      chunkEvent(3, 2, 1, childChunks[1]!),
+      chunkEvent(SessionSeq(0), 1, 1, parentChunk),
+      chunkEvent(SessionSeq(1), 1, 1, { type: 'finish', reason: { kind: 'stop' } }),
+      chunkEvent(SessionSeq(2), 2, 1, childChunks[0]!),
+      chunkEvent(SessionSeq(3), 2, 1, childChunks[1]!),
     ]
     const childPath = join(dir, 'session.1.jsonl')
     writeFileSync(childPath, sessionJsonl(childEvents, { id: 'child', createdAt: 200, seedLength: 2 }), 'utf8')
@@ -1335,7 +1341,7 @@ describe('apply (the plugin entry)', () => {
   })
 
   it('installs replay and its catalog from explicit config', async () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmRuntime)
     apply(ctx, {
@@ -1352,7 +1358,7 @@ describe('apply (the plugin entry)', () => {
   })
 
   it('declares flat image request pricing only for models that configure it', async () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmRuntime)
     installLlmReplay(ctx, {
@@ -1426,7 +1432,7 @@ describe('apply (the plugin entry)', () => {
   })
 
   it('uses only the file when no override path is configured or in the env', async () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c))), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c))), 'utf8')
     process.env.DSH_SNAPSHOT_FILE = file
     delete process.env.DSH_SNAPSHOT_OVERRIDE
     const ctx = new Context()
@@ -1455,9 +1461,9 @@ describe('apply (the plugin entry)', () => {
       { type: 'text-delta', index: 0, text: 'kid' },
       { type: 'finish', reason: { kind: 'stop' } },
     ]
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c)), { id: 'p', createdAt: 1 }), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c)), { id: 'p', createdAt: 1 }), 'utf8')
     const childFile = join(dir, 'session.1.jsonl')
-    writeFileSync(childFile, sessionJsonl(childSecond.map((c, i) => chunkEvent(i + 1, 1, 1, c)), { id: 'c', createdAt: 2 }), 'utf8')
+    writeFileSync(childFile, sessionJsonl(childSecond.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c)), { id: 'c', createdAt: 2 }), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmRuntime)
     apply(ctx, { file, childFiles: [childFile] })
@@ -1473,9 +1479,9 @@ describe('apply (the plugin entry)', () => {
       { type: 'text-delta', index: 0, text: 'env-kid' },
       { type: 'finish', reason: { kind: 'stop' } },
     ]
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c)), { id: 'p', createdAt: 1 }), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c)), { id: 'p', createdAt: 1 }), 'utf8')
     const childFile = join(dir, 'session.1.jsonl')
-    writeFileSync(childFile, sessionJsonl(childChunks.map((c, i) => chunkEvent(i + 1, 1, 1, c)), { id: 'c', createdAt: 2 }), 'utf8')
+    writeFileSync(childFile, sessionJsonl(childChunks.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c)), { id: 'c', createdAt: 2 }), 'utf8')
     process.env.DSH_SNAPSHOT_FILE = file
     process.env.DSH_SNAPSHOT_CHILD_FILES = childFile // single entry, no delimiter needed
     const ctx = new Context()
@@ -1488,7 +1494,7 @@ describe('apply (the plugin entry)', () => {
   })
 
   it('ignores an empty $DSH_SNAPSHOT_CHILD_FILES (single-session)', async () => {
-    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(i + 1, 1, 1, c)), { id: 'p', createdAt: 1 }), 'utf8')
+    writeFileSync(file, sessionJsonl(TEXT_CHUNKS.map((c, i) => chunkEvent(SessionSeq(i + 1), 1, 1, c)), { id: 'p', createdAt: 1 }), 'utf8')
     process.env.DSH_SNAPSHOT_FILE = file
     process.env.DSH_SNAPSHOT_CHILD_FILES = ''
     const ctx = new Context()
diff --git a/packages/test-support/session-snapshot/src/normalize.ts b/packages/test-support/session-snapshot/src/normalize.ts
index 8073e9430b..6e8903bf2a 100644
--- a/packages/test-support/session-snapshot/src/normalize.ts
+++ b/packages/test-support/session-snapshot/src/normalize.ts
@@ -10,6 +10,8 @@ import {
   decodeSeqRanges,
   decodeStorageRecord,
   packChunkRuns,
+  SessionLogOffset,
+  SessionSeq,
   type SessionEvent,
 } from '@deepseek-ai/dsh-session'
 import { redactSessionSnapshotIds } from './identity.ts'
@@ -385,16 +387,16 @@ function repackSessionSnapshot(rawLog: string): string {
   const lines = rawLog.split('\n').filter(line => line.trim().length > 0)
   const header = lines.shift() as string
 
-  let nextSeq = 0
+  let nextSeq = SessionLogOffset(0)
   const events = lines.flatMap((line) => {
     const record = JSON.parse(line) as Record<string, unknown>
     if (isPackedFixtureRow(record)) {
       const decoded = decodeStorageRecord({ ...record, seq0: nextSeq, time0: 0 })
-      nextSeq += decoded.length
+      nextSeq = SessionLogOffset(nextSeq + decoded.length)
       return decoded
     }
-    const event = { ...record, seq: nextSeq, time: 0 } as SessionEvent
-    nextSeq += 1
+    const event = { ...record, seq: SessionSeq(nextSeq), time: 0 } as SessionEvent
+    nextSeq = SessionLogOffset(nextSeq + 1)
     return [event]
   })
   const body = packChunkRuns(events).map((stored) => {
diff --git a/packages/todo/tool-todo/tests/invariant.spec.ts b/packages/todo/tool-todo/tests/invariant.spec.ts
index c8f52e7c80..4b41b6a301 100644
--- a/packages/todo/tool-todo/tests/invariant.spec.ts
+++ b/packages/todo/tool-todo/tests/invariant.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
 import ToolRuntime from '@deepseek-ai/dsh-tools'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as TodoInvariant from '@deepseek-ai/dsh-tool-todo/invariant'
@@ -100,13 +100,13 @@ describe('todo snapshot invariants', () => {
   it('validates seeded sessions announced after companion installation', async () => {
     const ctx = await setup()
     const valid = ctx.sessions.create(SessionId('todo-seeded-valid'), { seed: [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-      { type: 'todo/write', seq: 1, time: 2, data: { todos: [] } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'todo/write', seq: SessionSeq(1), time: 2, data: { todos: [] } },
     ] })
     expect(() => valid.append('todo/write', { todos: [] })).not.toThrow()
 
     expect(() => ctx.sessions.create(SessionId('todo-seeded-invalid'), { seed: [
-      { type: 'todo/write', seq: 0, time: 1, data: { todos: [] } },
+      { type: 'todo/write', seq: SessionSeq(0), time: 1, data: { todos: [] } },
     ] })).toThrow(/outside any open turn/)
   })
 
diff --git a/packages/todo/tool-todo/tests/tool-todo.spec.ts b/packages/todo/tool-todo/tests/tool-todo.spec.ts
index c54f710c33..a3d60f5b63 100644
--- a/packages/todo/tool-todo/tests/tool-todo.spec.ts
+++ b/packages/todo/tool-todo/tests/tool-todo.spec.ts
@@ -5,7 +5,7 @@ import { createUserMessage, ToolCallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime from '@deepseek-ai/dsh-tools'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { TodoItem } from '@deepseek-ai/dsh-tool-todo'
 import { type Agent } from '@deepseek-ai/dsh-agent'
 
@@ -297,7 +297,7 @@ describe('todo/write event', () => {
 
     expect(replayed.snapshotEvents().findLast(e => e.type === 'todo/write')!.data.todos)
       .toEqual([{ content: 'only', status: 'completed' }])
-    expect(replayed.snapshotEvents(0, original.seq)).toEqual(original.snapshotEvents())
+    expect(replayed.snapshotEvents(SessionLogOffset(0), original.seq)).toEqual(original.snapshotEvents())
     expect(replayed.firstLiveSeq).toBe(original.seq)
   })
 })
diff --git a/packages/typert/generator/tests/schema-emitter.spec.ts b/packages/typert/generator/tests/schema-emitter.spec.ts
index 16ac97b7ca..fcc6faa175 100644
--- a/packages/typert/generator/tests/schema-emitter.spec.ts
+++ b/packages/typert/generator/tests/schema-emitter.spec.ts
@@ -500,6 +500,40 @@ describe('SchemaEmitter supported projection matrix', () => {
     expect(schema.safeParse(1).success).toBe(false)
   })
 
+  it('erases a unique-symbol numeric brand to its wire number', async () => {
+    const nominal = declaration('NominalNumber', 'alias', {
+      typeParameters: [{ id: 'nominal-number:brand', name: 'Brand', const: false }],
+      type: 'nominal-number:intersection',
+    })
+    const symbolMember = {
+      ...property('[TOKEN]', 'nominal-number:brand-reference', { readonly: true }),
+      computed: 'symbol',
+    } as const
+    const schema = await loadSchema(emit([
+      {
+        id: 'root',
+        kind: 'reference',
+        name: 'NominalNumber',
+        target: { kind: 'declaration', symbol: 'NominalNumber' },
+        arguments: ['brand'],
+      },
+      { id: 'brand', kind: 'literal', value: 'Fixture', text: "'Fixture'" },
+      { id: 'nominal-number:intersection', kind: 'intersection', types: ['number', 'nominal-number:marker'] },
+      keyword('number', 'number'),
+      { id: 'nominal-number:marker', kind: 'object', members: [symbolMember] },
+      {
+        id: 'nominal-number:brand-reference',
+        kind: 'reference',
+        name: 'Brand',
+        target: { kind: 'type-parameter', parameter: 'nominal-number:brand' },
+        arguments: [],
+      },
+    ], undefined, [nominal]))
+
+    expect(schema.safeParse(7).success).toBe(true)
+    expect(schema.safeParse('7').success).toBe(false)
+  })
+
   it('classifies every TypeNode kind and executes every supported kind', () => {
     const expected = Object.entries(ZOD_NODE_SUPPORT)
       .filter(([, support]) => support === 'supported')
diff --git a/packages/util/brand/README.i18n.yaml b/packages/util/brand/README.i18n.yaml
index 3b16704f15..77c442b474 100644
--- a/packages/util/brand/README.i18n.yaml
+++ b/packages/util/brand/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/util/brand/README.md
-README.md: f539cd66bd390ef0d92ff07cc54a26f39f2e3780
-README.zh.md: 4f9b113ceede7e963e43eb47dba6a96950abfcb4
+README.md: f9bcea11d223645a9bb1d2194a129f353220c684
+README.zh.md: be9d8f828e05655b41b054a11221e382c90ef58b
diff --git a/packages/util/brand/README.md b/packages/util/brand/README.md
index f539cd66bd..f9bcea11d2 100644
--- a/packages/util/brand/README.md
+++ b/packages/util/brand/README.md
@@ -1,5 +1,5 @@
 ---
-description: "Nominal string types and stateless constructors for packages that own identifiers crossing package boundaries."
+description: "Nominal string and number types with stateless constructors for packages that own confusable domain values."
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-brand` makes structurally identical strings non-interchangeable at the type level: a `SessionId` cannot be passed where a `ToolCallId` is expected even though both are plain strings at runtime. `brandString<T>()` applies a nominal brand to one domain-owned string without shared runtime state and lets capability packages own their concrete id types without importing an unrelated capability.
+`dsh-brand` makes structurally identical strings or numbers non-interchangeable at the type level: a `SessionId` cannot be passed where a `ToolCallId` is expected, and an event sequence cannot be passed where a log offset is required. `brandString<T>()` and `brandNumber<T>()` apply nominal brands without shared runtime state, so owning packages can define domain types without importing an unrelated capability.
 
 ## Table of Contents
 
@@ -23,7 +23,7 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
-Brand the ids a package owns when they cross a package boundary and could plausibly be confused with another package's ids; not every string needs a brand. A branded id is a contract for TypeScript callers: it only ever enters the functions that expect it, and an id from another package is rejected at compile time.
+Brand a domain value when it crosses a package boundary and could plausibly be confused with another value represented by the same primitive; not every string or number needs a brand. A branded value is a contract for TypeScript callers: it enters only functions that expect its domain, and a different brand is rejected at compile time.
 
 ### Branding a string
 
@@ -39,9 +39,23 @@ const sessionId = brandString<SessionId>('session-1')
 
 `brandString()` changes only the static type and performs no runtime validation. Validate domain grammar before calling it when the owning type has one. Once branded, the id compares, logs, serializes to JSON, and crosses the wire as an ordinary string.
 
+### Branding a number
+
+Declare a numeric brand in its owning package and apply it only after that package admits the number:
+
+```ts
+import { brandNumber, type BrandedNumber } from '@deepseek-ai/dsh-brand'
+
+export type SessionSeq = BrandedNumber<'SessionSeq'>
+
+const seq = brandNumber<SessionSeq>(7)
+```
+
+`brandNumber()` returns the original number and performs no validation. The owning package validates requirements such as non-negative safe-integer range before branding. Comparison, arithmetic, logging, JSON serialization, and wire transport retain ordinary number behavior; arithmetic produces an unbranded number that the owner must admit again before it re-enters the domain.
+
 ### When to brand
 
-Brand ids that cross package boundaries and could plausibly be confused — `ToolCallId` in `dsh-llm`, the shared agent/session `SessionId` in `dsh-session`, `JobId` in `dsh-jobs`, `LspProviderId` in `dsh-lsp`. Strings that never leave their owning package do not need this abstraction.
+Brand values that cross package boundaries and could plausibly be confused — `ToolCallId` in `dsh-llm`, the shared agent/session `SessionId` in `dsh-session`, `JobId` in `dsh-jobs`, and `SessionSeq` versus `SessionLogOffset` in `dsh-session`. Values that stay local or cannot be confused do not need this abstraction.
 
 -----
 
@@ -51,18 +65,18 @@ Brand ids that cross package boundaries and could plausibly be confused — `Too
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-The primitive is one intersection type: `string & { readonly [BRAND]: B }`, where `BRAND` is a module-private `unique symbol`.
+The package defines two intersection types, `string & { readonly [BRAND]: B }` and `number & { readonly [BRAND]: B }`, where `BRAND` is a module-private `unique symbol`.
 
 ### Source map
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Branded string type and its stateless constructor |
+| [`src/index.ts`](src/index.ts) | Branded string and number types with stateless constructors |
 | — | No runtime invariant companion is published; this pure utility owns no event stream or mutable runtime data; its value algebra is enforced by unit tests. |
 
 ### How values stay portable
 
-The private symbol never exists at runtime: TypeScript erases it, so branded values have no tag or prototype. `brandString()` returns its input unchanged. Separate installed copies therefore produce interchangeable values without sharing a registry or constructor identity.
+The private symbol never exists at runtime: TypeScript erases it, so branded values have no tag or prototype. `brandString()` and `brandNumber()` return their inputs unchanged. Separate installed copies therefore produce interchangeable values without sharing a registry or constructor identity.
 
 ### Why it stays dependency-free
 
@@ -75,7 +89,7 @@ Keeping these helpers in their own package means `dsh-jobs` can brand `JobId` wi
 <a id="further-exploration"></a>
 ## Further Exploration
 
-Read these pages when you need the ids this primitive brands or the type conventions around it.
+Read these pages when you need the values these primitives brand or the type conventions around them.
 
 - [Core subsystem](../../../docs/subsystems/core.md) — where the shared `SessionId` brand and the type rules are documented.
 - [LSP subsystem](../../../docs/subsystems/lsp.md) — `LspProviderId`, a branded provider id built on this primitive.
diff --git a/packages/util/brand/README.zh.md b/packages/util/brand/README.zh.md
index 4f9b113cee..be9d8f828e 100644
--- a/packages/util/brand/README.zh.md
+++ b/packages/util/brand/README.zh.md
@@ -1,5 +1,5 @@
 ---
-description: "供拥有跨包标识符的包使用的名义字符串类型与无状态构造函数。"
+description: "供拥有易混淆领域值的包使用的名义字符串与数字类型及无状态构造函数。"
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-`dsh-brand` 让结构相同的字符串在类型层面不可互换：即使 `SessionId` 与 `ToolCallId` 在运行时都是普通字符串，前者也无法传给期望后者的位置。`brandString<T>()` 为领域拥有的字符串应用名义品牌且不持有共享运行时状态，让能力包可以拥有自己的具体 id 类型，而无需导入不相关的能力。
+`dsh-brand` 让结构相同的字符串或数字在类型层面不可互换：`SessionId` 无法传给期望 `ToolCallId` 的位置，事件序号也无法传给需要日志偏移量的位置。`brandString<T>()` 与 `brandNumber<T>()` 在不持有共享运行时状态的情况下应用名义品牌，让所属包可以定义领域类型，而无需导入不相关的能力。
 
 ## 目录
 
@@ -23,7 +23,7 @@ kind: "package-library"
 <a id="use-this-package"></a>
 ## 使用本包
 
-当包拥有的 id 跨越包边界、并可能与其他包的 id 混淆时，为其添加品牌；并非每个字符串都需要品牌。品牌化 id 是给 TypeScript 调用方的约定：它只会进入期望它的函数，来自其他包的 id 会在编译期被拒绝。
+当领域值跨越包边界，并可能与使用同一原语表示的另一个值混淆时，为其添加品牌；并非每个字符串或数字都需要品牌。品牌化值是给 TypeScript 调用方的约定：它只会进入期望该领域的函数，不同品牌会在编译期被拒绝。
 
 ### 为字符串添加品牌
 
@@ -39,9 +39,23 @@ const sessionId = brandString<SessionId>('session-1')
 
 `brandString()` 只改变静态类型，不执行运行时校验。所属类型若有领域文法，应在调用前完成校验。添加品牌后，该 id 与普通字符串一样比较、记录日志、序列化为 JSON 和跨 wire 传输。
 
+### 为数字添加品牌
+
+在所属包中声明数字品牌，并且仅在该包准入数字之后应用品牌：
+
+```ts
+import { brandNumber, type BrandedNumber } from '@deepseek-ai/dsh-brand'
+
+export type SessionSeq = BrandedNumber<'SessionSeq'>
+
+const seq = brandNumber<SessionSeq>(7)
+```
+
+`brandNumber()` 原样返回数字，不执行校验。所属包会在添加品牌前校验非负安全整数范围等要求。比较、算术、日志、JSON 序列化与 wire 传输保留普通数字行为；算术会产生未品牌化数字，所属包必须重新准入该数字，才能让它再次进入领域。
+
 ### 何时添加品牌
 
-为跨包边界且可能被混淆的 id 添加品牌——`dsh-llm` 中的 `ToolCallId`、`dsh-session` 中共享的 agent/会话 `SessionId`、`dsh-jobs` 中的 `JobId`、`dsh-lsp` 中的 `LspProviderId`。从不离开所属包的字符串不需要这种抽象。
+为跨包边界且可能被混淆的值添加品牌——`dsh-llm` 中的 `ToolCallId`、`dsh-session` 中共享的 agent/会话 `SessionId`、`dsh-jobs` 中的 `JobId`，以及 `dsh-session` 中的 `SessionSeq` 与 `SessionLogOffset`。保持局部或无法混淆的值不需要这种抽象。
 
 -----
 
@@ -51,18 +65,18 @@ const sessionId = brandString<SessionId>('session-1')
 <details>
 <summary>实现细节——点击展开</summary>
 
-该原语是一个交叉类型：`string & { readonly [BRAND]: B }`，其中 `BRAND` 是模块私有的 `unique symbol`。
+该包定义两个交叉类型：`string & { readonly [BRAND]: B }` 与 `number & { readonly [BRAND]: B }`，其中 `BRAND` 是模块私有的 `unique symbol`。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 品牌化字符串类型及其无状态构造函数 |
+| [`src/index.ts`](src/index.ts) | 品牌化字符串与数字类型及其无状态构造函数 |
 | — | 不发布运行时不变量伴生入口；擦除由编译器保证。 |
 
 ### 值为何可移植
 
-私有 symbol 在运行时不存在：TypeScript 会将其擦除，因此品牌化值没有标签或 prototype。`brandString()` 原样返回输入。因此，彼此独立安装的副本无需共享注册表或 constructor identity，也会生成可互换的值。
+私有 symbol 在运行时不存在：TypeScript 会将其擦除，因此品牌化值没有标签或 prototype。`brandString()` 与 `brandNumber()` 都原样返回输入。因此，彼此独立安装的副本无需共享注册表或 constructor identity，也会生成可互换的值。
 
 ### 为何保持无依赖
 
@@ -75,7 +89,7 @@ const sessionId = brandString<SessionId>('session-1')
 <a id="further-exploration"></a>
 ## 进一步探索
 
-当你需要本原语所品牌化的 id 或围绕它的类型约定时，阅读以下页面。
+当你需要这些原语所品牌化的值或围绕它们的类型约定时，阅读以下页面。
 
 - [核心子系统](../../../docs/subsystems/core.zh.md)——共享 `SessionId` 品牌与类型规则的记录位置。
 - [LSP 子系统](../../../docs/subsystems/lsp.zh.md)——构建在本原语之上的品牌化提供方 id `LspProviderId`。
diff --git a/packages/util/brand/package.json b/packages/util/brand/package.json
index 5a77c4810e..b6d049357b 100644
--- a/packages/util/brand/package.json
+++ b/packages/util/brand/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-brand",
-  "description": "Stateless branded-string primitives for the DeepSeek Harness",
+  "description": "Stateless branded primitive types for the DeepSeek Harness",
   "version": "0.1.2-alpha.3",
   "publishConfig": {
     "access": "public"
diff --git a/packages/util/brand/src/index.ts b/packages/util/brand/src/index.ts
index 68f3d857d8..7f89f3eddc 100644
--- a/packages/util/brand/src/index.ts
+++ b/packages/util/brand/src/index.ts
@@ -1,12 +1,12 @@
 /**
- * Duplicate-install-safe nominal string helpers.
+ * Duplicate-install-safe nominal primitive helpers.
  *
- * A brand makes structurally-identical strings non-interchangeable at the type
- * level: a `SessionId` cannot be passed where a `ToolCallId` is expected, even
- * though both are plain strings at runtime. Comparison, logging, and
- * serialization all behave as ordinary strings.
+ * A brand makes structurally identical strings or numbers non-interchangeable
+ * at the type level: a `SessionId` cannot be passed where a `ToolCallId` is
+ * expected, and an event sequence cannot be passed as a log offset. Comparison,
+ * logging, and serialization retain the underlying primitive behavior.
  *
- * This package owns no concrete id and keeps no runtime identity or mutable
+ * This package owns no concrete domain value and keeps no runtime identity or mutable
  * state, so independently installed copies produce interchangeable values.
  *
  * @module @deepseek-ai/dsh-brand
@@ -17,6 +17,9 @@ declare const BRAND: unique symbol
 /** A string carrying a compile-time-only brand `B`. */
 export type Branded<B extends string> = string & { readonly [BRAND]: B }
 
+/** A number carrying a compile-time-only brand `B`. */
+export type BrandedNumber<B extends string> = number & { readonly [BRAND]: B }
+
 /**
  * Apply a compile-time string brand without changing the value.
  * @param value - string admitted by the domain that owns the target brand.
@@ -25,3 +28,12 @@ export type Branded<B extends string> = string & { readonly [BRAND]: B }
 export function brandString<T extends Branded<string>>(value: string | T): T {
   return value as T
 }
+
+/**
+ * Apply a compile-time number brand without changing the value.
+ * @param value - number admitted by the domain that owns the target brand.
+ * @returns the same number with the requested compile-time brand.
+ */
+export function brandNumber<T extends BrandedNumber<string>>(value: number | T): T {
+  return value as T
+}
diff --git a/packages/util/brand/tests/brand.spec.ts b/packages/util/brand/tests/brand.spec.ts
new file mode 100644
index 0000000000..96f2665cc8
--- /dev/null
+++ b/packages/util/brand/tests/brand.spec.ts
@@ -0,0 +1,13 @@
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { brandNumber, type BrandedNumber } from '../src/index.ts'
+
+type EventOrdinal = BrandedNumber<'EventOrdinal'>
+
+describe('numeric brands', () => {
+  it('brands a number without changing its runtime value', () => {
+    const value = brandNumber<EventOrdinal>(7)
+
+    expect(value).toBe(7)
+    expectTypeOf(value).toEqualTypeOf<EventOrdinal>()
+  })
+})
diff --git a/packages/workflow/tool-ralph/tests/integration.spec.ts b/packages/workflow/tool-ralph/tests/integration.spec.ts
index 67f29d29fd..6d14949aba 100644
--- a/packages/workflow/tool-ralph/tests/integration.spec.ts
+++ b/packages/workflow/tool-ralph/tests/integration.spec.ts
@@ -101,7 +101,8 @@ describe('dsh-tool-ralph over the real spawn and worker-thread stack', () => {
     for (const child of children) {
       expect(child.session.header.cwd).toBe('/tmp/ralph-shared-workspace')
       expect(child.session.header.parentSession).toBe(parent.session.header.id)
-      expect(child.session.header.seedLength).toBeUndefined()
+      expect(child.session.header.isSeeded).toBe(false)
+      expect(child.session.inheritedEventCount).toBe(0)
       expect(ctx.agents.get(child.id)).toBeUndefined()
     }
 
diff --git a/packages/workspace/workspace/tests/workspace.spec.ts b/packages/workspace/workspace/tests/workspace.spec.ts
index 22900c7649..49348cea2a 100644
--- a/packages/workspace/workspace/tests/workspace.spec.ts
+++ b/packages/workspace/workspace/tests/workspace.spec.ts
@@ -23,6 +23,7 @@ const header = (id: string, cwd?: string, createdAt = 0): SessionHeader => ({
   version: 0,
   id: SessionId(id),
   createdAt,
+  isSeeded: false,
   ...(cwd === undefined ? {} : { cwd }),
 })
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index da090f24c2..4521b1bbf4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -7062,6 +7062,9 @@ importers:
       '@deepseek-ai/dsh-brand':
         specifier: workspace:^
         version: link:../../util/brand
+      '@deepseek-ai/dsh-util-values':
+        specifier: workspace:^
+        version: link:../../util/values
       '@deepseek-ai/schemastery':
         specifier: link:../../../vendor/schemastery
         version: link:../../../vendor/schemastery
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index a6fa86fe40..e0f068e0d7 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -317,6 +317,10 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SessionForkRequest: 'session.md',
   SessionForkValue: 'session.md',
   SessionId: 'core.md',
+  SessionLogOffset: 'session.md',
+  SessionSeq: 'session.md',
+  SessionSeqCursor: 'session.md',
+  OptionalSessionSeq: 'session.md',
   SessionListRequest: 'session.md',
   SessionListValue: 'session.md',
   ModelCatalog: 'session.md',
@@ -408,6 +412,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   PrepareSessionOptions: 'persistence.md',
   SessionHeader: 'persistence.md',
   SessionInspection: 'persistence.md',
+  SessionEventSuffix: 'persistence.md',
   BorrowedSessionSource: 'persistence.md',
   SessionLocation: 'persistence.md',
   SessionPreparation: 'persistence.md',
diff --git a/scripts/session-fixture-layout.spec.ts b/scripts/session-fixture-layout.spec.ts
index ddff386615..ca1fdfbf4f 100644
--- a/scripts/session-fixture-layout.spec.ts
+++ b/scripts/session-fixture-layout.spec.ts
@@ -1,6 +1,6 @@
 import { resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
-import { type SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session'
 import { parseSessionLog } from '@deepseek-ai/dsh-llm-replay'
 import {
   canonicalSessionFixture,
@@ -14,7 +14,7 @@ const root = resolve(import.meta.dirname, '..')
 function chunkRun(): SessionEvent[] {
   return Array.from({ length: 4 }, (_, index) => ({
     type: 'assistant/chunk',
-    seq: index,
+    seq: SessionSeq(index),
     time: 10 + index,
     data: {
       turn: 1,
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index df432dd3b5..7def55bbee 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -469,6 +469,26 @@
       "symbol": "RequestContext",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/subsystems/session.md",
+      "symbol": "SessionSeq",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/session.md",
+      "symbol": "SessionLogOffset",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/session.md",
+      "symbol": "SessionSeqCursor",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/session.md",
+      "symbol": "OptionalSessionSeq",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/subsystems/todo.md",
       "symbol": "TodoItem",
@@ -556,11 +576,21 @@
       "source": "packages/core/session/src/preparation.ts",
       "projection": "public-api"
     },
+    {
+      "doc": "docs/subsystems/persistence.md",
+      "symbol": "SessionStorageMetadata",
+      "source": "packages/session/session-persistence/src/index.ts"
+    },
     {
       "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionInspection",
       "source": "packages/session/session-persistence/src/index.ts"
     },
+    {
+      "doc": "docs/subsystems/persistence.md",
+      "symbol": "SessionEventSuffix",
+      "source": "packages/session/session-persistence/src/index.ts"
+    },
     {
       "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionLocation",

From c11c3f98ad8d26bdbe9ae7c543e14cfa4cb1d412 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 01:50:27 +0800
Subject: [PATCH 07/37] docs(ui-deliverables): record CSS overflow policy

---
 ...6-07-31-web-workspace-file-links.i18n.yaml |  4 +--
 .../2026-07-31-web-workspace-file-links.md    |  6 ++---
 .../2026-07-31-web-workspace-file-links.zh.md |  6 ++---
 ...6-09-01-css-produced-file-layout.i18n.yaml |  6 +++++
 .../2026-09-01-css-produced-file-layout.md    | 27 +++++++++++++++++++
 .../2026-09-01-css-produced-file-layout.zh.md | 27 +++++++++++++++++++
 .../client/ui-deliverables/README.i18n.yaml   |  4 +--
 packages/client/ui-deliverables/README.md     |  4 +--
 packages/client/ui-deliverables/README.zh.md  |  4 +--
 9 files changed, 74 insertions(+), 14 deletions(-)
 create mode 100644 .agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.i18n.yaml
 create mode 100644 .agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.md
 create mode 100644 .agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.zh.md

diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index 5a5c329383..e8023fd069 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: ddc093e1ce5e646f6b96f1517b2a26c9e10fe423
-2026-07-31-web-workspace-file-links.zh.md: f463de969bab7a47145abbbd46363b8807bcc673
+2026-07-31-web-workspace-file-links.md: 944d7bef9b83eb34895c5f74e511600a713d786b
+2026-07-31-web-workspace-file-links.zh.md: 71f0051204e0cb8b65995fc88a9edb230db8f5be
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index ddc093e1ce..944d7bef9b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -14,7 +14,7 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 
 ## Decision
 
-**A finished turn ends with the files it produced.** The row is its own plugin, `@deepseek-ai/dsh-client-ui-deliverables`, registered into the `conversation.chat.turnTail` hole the chat view renders between a closing message's body and its IconActions — ui-conversation owns the hole and the owner currency (nodes, closing seq, `openFile`), the plugin owns every policy. `producedForClosing` reads the paths off the mutation tools' own follow-along `locations` — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a turn's output is listed whether or not the closing message named it, and a new mutation tool joins by declaring what it does rather than by being added to a list. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row. The single-line lane measures its chips and localized remainder, then shows the largest prefix that fits (up to six) plus `+ N files`. One cordis.yml line composes the surface in or out; the unregistered hole renders nothing.
+**A finished turn ends with the files it produced.** The row is its own plugin, `@deepseek-ai/dsh-client-ui-deliverables`, registered into the `conversation.chat.turnTail` hole the chat view renders between a closing message's body and its IconActions — ui-conversation owns the hole and the owner currency (nodes, closing seq, `openFile`), the plugin owns every policy. `producedForClosing` reads the paths off the mutation tools' own follow-along `locations` — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a turn's output is listed whether or not the closing message named it, and a new mutation tool joins by declaring what it does rather than by being added to a list. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row. CSS container-width bands select a prefix of up to six paths and its matching `+ N files` label, while flexbox shrinks and ellipsizes the visible basenames; the component performs no JavaScript layout observation ([decision](../simplification/2026-09-01-css-produced-file-layout.md)). One cordis.yml line composes the surface in or out; the unregistered hole renders nothing.
 
 **The path link reads as a link.** Underlined at rest, not only on hover. This is the smaller half of the diff and the larger half of the fix.
 
@@ -28,9 +28,9 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 - **Same-origin HTTP serving without isolation** — measurably unsafe, and recorded so nobody retries it: a document served beside `/api` drove `settings.describe` to a `200` with full data and `session.list` to 35 KB of every session's transcript, from a page that need not be agent-authored at all (a read row makes every file in a cloned repository openable).
 - **`Content-Security-Policy: sandbox` over that same-origin serving** — closes the hole by taking the document's origin away, which measurably breaks the pages this feature exists to show: the reported artifact throws `SecurityError` on load, and because an uncaught exception aborts the rest of its `<script>`, every listener declared after that line — theme toggle, mobile menu, model tabs — never binds. Two of the four artifacts in the reporting user's workspace were dead pages under it, and they still rendered perfectly, so the breakage was invisible.
 - **Linkifying paths in the assistant's closing message** — the shape a user asks for ("put the link at the end"), but it makes rendering depend on the model spelling a path recognizably. The tool calls already carry `locations` as structured fact, so the produced-files row consumes that instead.
-- **Horizontal chip scrolling** — keeps every file in the DOM but makes the hidden tail undiscoverable, adds a nested horizontal gesture to the transcript, and provides no exact account of what is out of view. One measured line with a stable remainder preserves the answer's vertical rhythm and keeps the omission explicit.
+- **Horizontal chip scrolling** — keeps every file in the DOM but makes the hidden tail undiscoverable, adds a nested horizontal gesture to the transcript, and provides no exact account of what is out of view. A non-scrolling CSS lane with a width-selected visible prefix preserves the answer's vertical rhythm and keeps the omission explicit.
 - **An embedded WebView in the desktop shell** — the strongest isolation available, since the preview then runs in a container the product owns rather than in the user's browser. It belongs to the desktop shell's own design, not to this surface, and is recorded here as the direction a future preview capability should take.
 
 ## Consequences
 
-Every existing file affordance changed at once: write, edit, read, and the generic single-file card all reach `openFile`, so the link fix and browser preference apply without per-row changes. The assembled Web test covers overflow geometry and a one-click Host handoff without launching a native application. A produced `file://` document cannot `fetch` its own siblings (while `<script src>`, `<img>`, and CSS `@import` work), the one capability HTTP serving had that this does not. Remote clients keep the chips but omit the folder action; the full path remains in each chip's `title`. Markdown still opens in the platform's `.md` application; in-product rendering is separate work.
+Every existing file affordance changed at once: write, edit, read, and the generic single-file card all reach `openFile`, so the link fix and browser preference apply without per-row changes. The assembled Web test covers single-line CSS overflow and a one-click Host handoff without launching a native application. A produced `file://` document cannot `fetch` its own siblings (while `<script src>`, `<img>`, and CSS `@import` work), the one capability HTTP serving had that this does not. Remote clients keep the chips but omit the folder action; the full path remains in each chip's `title`. Markdown still opens in the platform's `.md` application; in-product rendering is separate work.
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index f463de969b..71f0051204 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-**完成的一轮以它产出的文件收尾。** 该行是独立插件 `@deepseek-ai/dsh-client-ui-deliverables`，注册进 chat 视图在收尾消息正文与其 IconActions 之间渲染的 `conversation.chat.turnTail` 空位——ui-conversation 拥有空位与 owner 通货（节点、收尾 seq、`openFile`），插件拥有全部策略。`producedForClosing` 从改写工具自身的跟随文件 `locations` 中读出路径——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。单行 lane 会测量 chip 和本地化剩余计数，再显示能放下的最大前缀（至多六个）及 `+ N 个文件`。cordis.yml 中的一行即可把该交互面组合进来或去掉；未注册的空位什么也不渲染。
+**完成的一轮以它产出的文件收尾。** 该行是独立插件 `@deepseek-ai/dsh-client-ui-deliverables`，注册进 chat 视图在收尾消息正文与其 IconActions 之间渲染的 `conversation.chat.turnTail` 空位——ui-conversation 拥有空位与 owner 通货（节点、收尾 seq、`openFile`），插件拥有全部策略。`producedForClosing` 从改写工具自身的跟随文件 `locations` 中读出路径——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。CSS 容器宽度档位会选择前六条路径中的一个前缀及其匹配的 `+ N 个文件` 标签，flexbox 则收缩可见的 basename 并用 ellipsis 省略；组件不执行 JavaScript 布局观察（[决策](../simplification/2026-09-01-css-produced-file-layout.zh.md)）。cordis.yml 中的一行即可把该交互面组合进来或去掉；未注册的空位什么也不渲染。
 
 **路径链接读得出是链接。** 静止状态下就带下划线，而不只在悬停时。这是本次改动中更小的那一半，却是修复中更大的那一半。
 
@@ -28,9 +28,9 @@ Status: implemented
 - **同源 HTTP 提供且不加隔离**——经实测不安全，记录在此以免有人重试：与 `/api` 并排提供的文档把 `settings.describe` 打到 `200` 并拿到完整数据，把 `session.list` 打到包含所有会话 transcript 的 35 KB，而这个页面根本不必由 agent 撰写（一条 read 行就让 clone 下来的仓库里任何文件变得可打开）。
 - **在那套同源提供之上加 `Content-Security-Policy: sandbox`**——它以剥夺文档的源来堵住这个洞，而这经实测会破坏本功能存在的意义所在的那类页面：所报告的产物在加载时抛 `SecurityError`，又因为未捕获异常会中止其 `<script>` 的其余部分，该行之后声明的所有监听器——主题切换、移动端菜单、模型 tabs——统统不会绑定。报告者工作区里四份产物有两份在它之下是死页面，而且它们渲染得完美无缺，所以这种破坏是看不见的。
 - **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（「在结尾附上链接」），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它。
-- **让文件 chip 横向滚动**——这样会把每个文件都留在 DOM 中，却使隐藏的尾部难以发现，在 transcript 内增加一层横向手势，也无法精确说明视口外还有什么。经过测量的一行和稳定的剩余计数既保留回答的纵向节奏，也明确呈现省略量。
+- **让文件 chip 横向滚动**——这样会把每个文件都留在 DOM 中，却使隐藏的尾部难以发现，在 transcript 内增加一层横向手势，也无法精确说明视口外还有什么。不滚动的 CSS 单行与按宽度选择的可见前缀既保留回答的纵向节奏，也明确呈现省略量。
 - **桌面端外壳中的内嵌 WebView**——可得到的最强隔离，因为那时预览跑在产品自己拥有的容器里，而不是用户的浏览器里。它属于桌面端外壳自身的设计，而非本交互面，记录在此作为未来预览能力应走的方向。
 
 ## 后果
 
-现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接修复与浏览器优先策略无需逐行改动。组装层 Web 测试覆盖溢出几何和单次点击的 Host 交接，且不会启动原生应用。产出的 `file://` 文档无法 `fetch` 同级文件（但 `<script src>`、`<img>` 和 CSS `@import` 可用），这是 HTTP 提供曾有、而此处没有的能力。远程客户端保留 chip，但省略文件夹操作；每个 chip 的 `title` 仍保留完整路径。Markdown 仍由平台的 `.md` 应用打开；产品内渲染属于另一项工作。
+现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接修复与浏览器优先策略无需逐行改动。组装层 Web 测试覆盖单行 CSS 溢出和单次点击的 Host 交接，且不会启动原生应用。产出的 `file://` 文档无法 `fetch` 同级文件（但 `<script src>`、`<img>` 和 CSS `@import` 可用），这是 HTTP 提供曾有、而此处没有的能力。远程客户端保留 chip，但省略文件夹操作；每个 chip 的 `title` 仍保留完整路径。Markdown 仍由平台的 `.md` 应用打开；产品内渲染属于另一项工作。
diff --git a/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.i18n.yaml b/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.i18n.yaml
new file mode 100644
index 0000000000..b26eb6c30b
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.md
+2026-09-01-css-produced-file-layout.md: fce7d70b21b05db8970fb249927c36f87abc6b23
+2026-09-01-css-produced-file-layout.zh.md: bc8ad941dbe33af3acc629f0da50e79c4a0954da
diff --git a/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.md b/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.md
new file mode 100644
index 0000000000..fce7d70b21
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.md
@@ -0,0 +1,27 @@
+# Agent Note: replace produced-file probes with CSS width bands
+
+Status: implemented
+
+English | [中文](2026-09-01-css-produced-file-layout.zh.md)
+
+## Problem
+
+The produced-files row duplicated every candidate chip in a hidden probe tree, synchronously read computed styles and element geometry in a layout effect, and repeated those reads whenever the row or a probe resized. That machinery existed only to choose how many labels fit on one line. Its forced layout work cost more than exact width-dependent chip counts were worth.
+
+The produced-file discovery and Host-opening behavior remain owned by [opening a produced file from the web UI](../feature/2026-07-31-web-workspace-file-links.md). This decision changes only how that row handles limited horizontal space.
+
+## Decision
+
+The produced-files row is an inline-size query container. CSS width bands hide trailing chips from the six-file prefix and select the corresponding pre-rendered localized remainder label. The flex row performs the actual shrinking, and each basename uses CSS ellipsis while the selected remainder label keeps its intrinsic width. `ProducedFiles` has no resize observer, layout effect, layout state, duplicate chip probes, computed-style lookup, or element-geometry read.
+
+The row keeps its chip maximum and gap as local CSS custom properties. Each width band corresponds to that budget and reveals one matching remainder label when paths are omitted, so `+ N files` remains accurate for the CSS-selected prefix. The same selected label controls whether the existing Host-gated **Show in folder** action is visible.
+
+## Alternatives considered
+
+- **Observe only the row and estimate from its width** — this removes content measurement but still creates one observer and width-driven React state per mounted result row even though CSS already receives the same width.
+- **Always render six chips and let flexbox shrink them** — this removes all sizing logic but can reduce six filenames to nearly empty targets on a narrow conversation column. CSS width bands retain useful labels without runtime observation.
+- **Wrap or horizontally scroll every chip** — wrapping changes the turn's vertical rhythm, while horizontal scrolling makes the tail hard to discover. The fixed cap keeps the row bounded without either interaction.
+
+## Consequences
+
+Mounting and resizing the row performs no JavaScript layout work. Because fixed width bands ignore actual text widths and localized remainder widths, they may show one more or fewer chip than exact measurement would; flex shrinking and clipping preserve the single-line layout, and the selected `+ N files` label still counts every omitted path. Rendered files preserve their full path in the accessible name and `title`. Each row carries at most six short remainder spans, of which CSS exposes zero or one. The assembled browser test verifies responsive omission, one-line layout, and the absence of horizontal overflow.
diff --git a/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.zh.md b/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.zh.md
new file mode 100644
index 0000000000..bc8ad941db
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.zh.md
@@ -0,0 +1,27 @@
+# Agent Note: 以 CSS 宽度档位替代产出文件探针
+
+Status: implemented
+
+[English](2026-09-01-css-produced-file-layout.md) | 中文
+
+## 问题
+
+产出文件行会在隐藏探针树中复制每个候选 chip，在 layout effect 中同步读取计算样式和元素几何，并在该行或任一探针改变尺寸时重复读取。这套机制只用于决定一行能容纳多少标签，其强制布局工作不值得用来换取随宽度精确变化的 chip 数量。
+
+产出文件发现与 Host 打开行为仍由[从 web UI 打开产出的文件](../feature/2026-07-31-web-workspace-file-links.zh.md)所有。本决策只改变该行处理有限横向空间的方式。
+
+## 决策
+
+产出文件行是一个 inline-size 查询容器。CSS 宽度档位会隐藏六文件前缀尾部的 chip，并选择对应的预渲染本地化剩余计数标签。flex 行负责实际收缩，各 basename 由 CSS 以 ellipsis 省略，而选中的剩余计数标签保持自身宽度。`ProducedFiles` 不含 resize observer、layout effect、布局 state、重复 chip 探针、计算样式查询或元素几何读取。
+
+该行以局部 CSS 自定义属性保存 chip 最大宽度与间距。每个宽度档位对应这份预算，并在省略路径时显示一个匹配的剩余计数标签，因此 `+ N 个文件` 对 CSS 选中的前缀保持准确。同一个选中标签控制现有 Host 能力约束下的**在文件夹中显示**动作是否可见。
+
+## 考虑过的替代方案
+
+- **只观察该行并根据其宽度估算**——这会删除内容测量，却仍会为每个已挂载结果行创建一个 observer 和宽度驱动的 React state，而 CSS 已经获得同一份宽度。
+- **始终渲染六个 chip 并让 flexbox 收缩**——这会删除全部尺寸逻辑，却可能在狭窄会话列中把六个文件名压缩成近乎空白的点击目标。CSS 宽度档位无需运行时观察即可保留有用标签。
+- **换行或横向滚动全部 chip**——换行会改变轮次的纵向节奏，横向滚动则使尾部难以发现。固定上限无需这两种交互即可约束该行。
+
+## 后果
+
+该行挂载与改变尺寸时不执行 JavaScript 布局工作。由于固定宽度档位忽略实际文本宽度与本地化剩余计数宽度，它可能比精确测量多显示或少显示一个 chip；flex 收缩与裁切会保持单行，选中的 `+ N 个文件` 标签仍准确统计全部未展示路径。已渲染文件在无障碍名称与 `title` 中保留完整路径。每行至多携带六个短剩余计数 span，其中 CSS 展示零个或一个。组装层浏览器测试验证响应式省略、单行布局与无横向溢出。
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index ee98f91817..3ccef63ed5 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/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/client/ui-deliverables/README.md
-README.md: ac56ae782ac13664fdfb32c51ea07e2f8f9818d7
-README.zh.md: 1aefe0d3c94f3d1c93c193426fd3d21b50359c75
+README.md: b228106848549dcddcde84be07c47392dc92a9db
+README.zh.md: 0a9d5207fe3c09b89ac34592f04c7eeaeed9b59a
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index ac56ae782a..b228106848 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -25,11 +25,11 @@ This package renders the deliverables row a finished turn ends with — the file
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount this plugin alongside `ui-conversation`; a finished turn then ends with the produced-files row between the closing message's body and its action footer. Each chip opens the file through the Host opener, with relative paths resolved against the session cwd; when the row first appears, it queries `session.canOpenWorkspacePath()`, and a **Show in folder** action opens the session workspace only when the page is loopback and that query succeeds with `true`.
+Mount this plugin alongside `ui-conversation`; a finished turn then ends with the produced-files row between the closing message's body and its action footer. Each chip opens the file through the Host opener, with relative paths resolved against the session cwd; when the row first appears, it queries `session.canOpenWorkspacePath()`, and an omitted-file **Show in folder** action opens the session workspace only when the page is loopback and that query succeeds with `true`.
 
 ### The row
 
-The row shows the largest leading prefix that fits — up to six chips, basename text with the full path as the title — reserving the exact localized `+ N files` width, so the remainder stays visible without wrapping or horizontal scrolling.
+The row uses CSS container-width bands to show a responsive prefix of up to six file chips. Flexbox shrinks and ellipsizes basename text, while CSS selects the matching localized `+ N files` label for omitted paths; the full path remains available as the title, and the row performs no JavaScript layout observation or horizontal scrolling.
 
 ### Inline-code links
 
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index 1aefe0d3c9..0a9d5207fe 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -25,11 +25,11 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-与 `ui-conversation` 一起挂载本插件；已完成轮次随即以产出文件行收尾，位于收尾消息正文与其动作页脚之间。每个标签项经 Host 打开器打开文件，相对路径按会话 cwd 解析；该行首次显示时会查询 `session.canOpenWorkspacePath()`，只有页面为 loopback 且查询成功返回 `true` 时，**在文件夹中显示**动作才会打开会话工作区。
+与 `ui-conversation` 一起挂载本插件；已完成轮次随即以产出文件行收尾，位于收尾消息正文与其动作页脚之间。每个标签项经 Host 打开器打开文件，相对路径按会话 cwd 解析；该行首次显示时会查询 `session.canOpenWorkspacePath()`，有文件被省略、页面为 loopback 且查询成功返回 `true` 时，**在文件夹中显示**动作才会打开会话工作区。
 
 ### 该行
 
-该行展示能放下的最大前缀——至多六个标签项，文本为文件名、完整路径作为 `title`——并为本地化后的精确 `+ N 个文件` 宽度预留空间，因此剩余计数始终可见，既不换行也不横向滚动。
+该行通过 CSS 容器宽度档位响应式展示至多六个文件标签项。Flexbox 负责收缩文件名并用 ellipsis 省略，CSS 为未展示路径选择匹配的本地化 `+ N 个文件` 标签；完整路径仍保留在 `title` 中，该行不执行 JavaScript 布局观察，也不提供横向滚动。
 
 ### 行内代码链接
 

From e5bbee893b1f6614689f6c7bd11b575df7755bd8 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 01:51:13 +0800
Subject: [PATCH 08/37] perf(ui-deliverables): move overflow sizing to CSS

---
 apps/web/tests/produced-files.e2e.ts          |  20 ++-
 .../src/client/ProducedFiles.module.css       | 159 ++++++++++++++----
 .../src/client/ProducedFiles.tsx              | 136 ++++-----------
 .../tests/produced-files.client.spec.tsx      |  85 +---------
 4 files changed, 181 insertions(+), 219 deletions(-)

diff --git a/apps/web/tests/produced-files.e2e.ts b/apps/web/tests/produced-files.e2e.ts
index 5494a934e3..d13f258728 100644
--- a/apps/web/tests/produced-files.e2e.ts
+++ b/apps/web/tests/produced-files.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenario: the single-line produced-files summary a finished turn
 // ends with. Cold-seeds ten writes (zero model calls), then verifies the real
-// assembled lane keeps a precise +N and a capability-gated folder handoff.
+// assembled lane adapts from a coarse width budget and keeps a capability-gated folder handoff.
 // The folder request is intercepted so one real browser click can exercise
 // the full client carrier without launching a native application in CI.
 import { fileURLToPath } from 'node:url'
@@ -20,7 +20,7 @@ const OVERLAY = fileURLToPath(new URL('./produced-files.overlay.yml', import.met
 const SEED_ID = 'produced-files-web-e2e'
 const DONE = 'PRODUCED_FILES_DONE'
 
-/** Short leading names plus a long third name make the narrow lane deterministically show two. */
+/** Ten varied names exercise estimated prefix selection and CSS shrinking. */
 const PRODUCED = [
   '关于我.md',
   'index.html',
@@ -116,7 +116,7 @@ describe('web e2e: a finished turn ends with the files it produced', () => {
     page = await newEnglishPage(browser)
     // Keep the responsive sidebar available while selecting the cold seed;
     // the assertion itself narrows the conversation after navigation.
-    await page.setViewportSize({ width: 1280, height: 900 })
+    await page.setViewportSize({ width: 1800, height: 900 })
     tripwire = watchConsole(page)
     await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
@@ -127,7 +127,7 @@ describe('web e2e: a finished turn ends with the files it produced', () => {
     await scaffold?.close()
   })
 
-  it.skipIf(MODE === 'record')('keeps a narrow ten-file summary on one line with +8 and a folder action', async () => {
+  it.skipIf(MODE === 'record')('adapts a ten-file summary without leaving one line', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-produced-files'))
     const groupRow = page.locator('[role="treeitem"]').first()
     await groupRow.waitFor({ timeout: 15_000 })
@@ -137,14 +137,18 @@ describe('web e2e: a finished turn ends with the files it produced', () => {
     await sessionRow.click()
 
     await expect.poll(() => page.getByText(DONE, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
-    await page.setViewportSize({ width: 780, height: 900 })
     const row = page.locator('[data-produced-files-row]')
     await row.waitFor({ timeout: 15_000 })
     const chips = row.getByRole('button')
-    await expect.poll(() => chips.count()).toBe(2)
+    await expect.poll(() => chips.count()).toBe(6)
+    await expect.poll(() => row.getByText('+ 4 files', { exact: true }).isVisible()).toBe(true)
+
+    await page.setViewportSize({ width: 780, height: 900 })
+    await expect.poll(() => chips.count()).toBe(5)
     expect(await chips.nth(0).innerText()).toBe('关于我.md')
     expect(await chips.nth(1).innerText()).toBe('index.html')
-    expect(await row.getByText('+ 8 files', { exact: true }).count()).toBe(1)
+    expect(await chips.nth(4).innerText()).toBe('app.ts')
+    await expect.poll(() => row.getByText('+ 5 files', { exact: true }).isVisible()).toBe(true)
     const showFolder = page.getByRole('button', { name: 'Show in folder', exact: true })
     expect(await showFolder.count()).toBe(1)
     expect(await page.getByText('Produced', { exact: true }).count()).toBe(1)
@@ -163,7 +167,7 @@ describe('web e2e: a finished turn ends with the files it produced', () => {
       openPath.mockRestore()
     }
 
-    const tops = await row.locator(':scope > *').evaluateAll(elements =>
+    const tops = await row.locator(':scope > *:visible').evaluateAll(elements =>
       elements.map(element => element.getBoundingClientRect().top))
     expect(new Set(tops.map(top => Math.round(top))).size).toBe(1)
     const geometry = await row.evaluate(element => ({
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.module.css b/packages/client/ui-deliverables/src/client/ProducedFiles.module.css
index fe7b4eec1c..d89862c36e 100644
--- a/packages/client/ui-deliverables/src/client/ProducedFiles.module.css
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.module.css
@@ -1,13 +1,10 @@
-/* Turn-tail produced-files summary: one measured chip lane plus an optional
-   native-folder action below it. */
+/* Turn-tail produced-files summary with an optional native-folder action. */
 
 .root {
-  position: relative;
   display: grid;
   grid-template-columns: max-content minmax(0, 1fr);
-  align-items: center;
+  align-items: start;
   column-gap: 8px;
-  row-gap: 6px;
   margin-top: 16px;
   font-size: 13px;
   line-height: 22px;
@@ -19,22 +16,33 @@
   color: var(--dsw-alias-label-tertiary);
 }
 
-.row {
+.lane {
+  --produced-file-chip-max: 96px;
+  --produced-file-gap: 8px;
+
   grid-column: 2;
   grid-row: 1;
+  display: grid;
+  row-gap: 6px;
+  min-width: 0;
+  container-type: inline-size;
+}
+
+.row {
   display: flex;
   flex-wrap: nowrap;
   align-items: center;
-  gap: 8px;
+  gap: var(--produced-file-gap);
   min-width: 0;
   overflow: hidden;
 }
 
-/* One produced file. A link by behavior (it opens the file), a chip by shape:
-   full paths are long, while the measured lane stays on one row. */
+/* File names yield space to one another while the remainder stays readable. */
 .file {
-  flex: 0 0 auto;
-  max-width: 320px;
+  box-sizing: border-box;
+  flex: 0 1 auto;
+  min-width: 0;
+  max-width: var(--produced-file-chip-max);
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
@@ -62,13 +70,120 @@
 /* Overflow count: the row never silently drops files it did not show. */
 .more {
   flex: 0 0 auto;
+  display: none;
   white-space: nowrap;
   color: var(--dsw-alias-label-tertiary);
 }
 
+.more[data-shown='6'] {
+  display: inline;
+}
+
+.showFolder {
+  display: none;
+}
+
+.lane:has(.more[data-shown='6']) > .showFolder {
+  display: block;
+}
+
+/* Each band budgets 96px per chip, 8px gaps, and 64px for the remainder. */
+@container (max-width: 687px) {
+  .file:nth-of-type(6),
+  .more[data-shown='6'] {
+    display: none;
+  }
+
+  .more[data-shown='5'] {
+    display: inline;
+  }
+
+  .showFolder {
+    display: none;
+  }
+
+  .lane:has(.more[data-shown='5']) > .showFolder {
+    display: block;
+  }
+}
+
+@container (max-width: 583px) {
+  .file:nth-of-type(5),
+  .more[data-shown='5'] {
+    display: none;
+  }
+
+  .more[data-shown='4'] {
+    display: inline;
+  }
+
+  .showFolder {
+    display: none;
+  }
+
+  .lane:has(.more[data-shown='4']) > .showFolder {
+    display: block;
+  }
+}
+
+@container (max-width: 479px) {
+  .file:nth-of-type(4),
+  .more[data-shown='4'] {
+    display: none;
+  }
+
+  .more[data-shown='3'] {
+    display: inline;
+  }
+
+  .showFolder {
+    display: none;
+  }
+
+  .lane:has(.more[data-shown='3']) > .showFolder {
+    display: block;
+  }
+}
+
+@container (max-width: 375px) {
+  .file:nth-of-type(3),
+  .more[data-shown='3'] {
+    display: none;
+  }
+
+  .more[data-shown='2'] {
+    display: inline;
+  }
+
+  .showFolder {
+    display: none;
+  }
+
+  .lane:has(.more[data-shown='2']) > .showFolder {
+    display: block;
+  }
+}
+
+@container (max-width: 271px) {
+  .file:nth-of-type(2),
+  .more[data-shown='2'] {
+    display: none;
+  }
+
+  .more[data-shown='1'] {
+    display: inline;
+  }
+
+  .showFolder {
+    display: none;
+  }
+
+  .lane:has(.more[data-shown='1']) > .showFolder {
+    display: block;
+  }
+}
+
 .showFolder {
-  grid-column: 2;
-  grid-row: 2;
   justify-self: start;
   margin: 0;
   padding: 0 2px;
@@ -85,21 +200,3 @@
   color: var(--dsw-alias-label-secondary);
   text-decoration: underline;
 }
-
-/* Exact browser-native probes for every candidate shown count. They share the
-   visible styles but never affect layout, accessibility, or scroll width. */
-.measure {
-  position: absolute;
-  width: 0;
-  height: 0;
-  overflow: hidden;
-  visibility: hidden;
-  pointer-events: none;
-  contain: strict;
-}
-
-.probe {
-  position: absolute;
-  inset: 0 auto auto 0;
-  width: max-content;
-}
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
index b3f0f04c0a..d54dc729fb 100644
--- a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
@@ -1,44 +1,13 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useEffect } from 'react'
 import type { HostObservable, InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { basename } from './turn-deliverables.ts'
 import type { NS } from './locales.ts'
 import css from './ProducedFiles.module.css'
 
-/** At most six chips compete for the one-line summary; every other path stays counted. */
+/** Maximum number of file chips rendered before the remainder counter. */
 const SHOWN_LIMIT = 6
 
-/**
- * Select the largest prefix whose measured chips and exact remainder fit.
- * @param available - usable width of the one-line file lane.
- * @param gap - computed flex gap between adjacent visible items.
- * @param chipWidths - measured widths for the candidate file chips.
- * @param moreWidthsByShown - exact localized remainder width for each shown count.
- * @returns Number of leading chips to render.
- */
-export function fitProducedFiles(
-  available: number,
-  gap: number,
-  chipWidths: readonly number[],
-  moreWidthsByShown: readonly (number | undefined)[],
-): number {
-  if (available <= 0) return chipWidths.length
-  const prefix = [0]
-  let prefixWidth = 0
-  for (const width of chipWidths) {
-    prefixWidth += width
-    prefix.push(prefixWidth)
-  }
-  let largestFit = 0
-  for (const [shown, width] of prefix.entries()) {
-    const more = moreWidthsByShown[shown]
-    const items = shown + (more === undefined ? 0 : 1)
-    const needed = width + (more ?? 0) + Math.max(0, items - 1) * gap
-    if (needed <= available) largestFit = shown
-  }
-  return largestFit
-}
-
 /** Registration-side Host capability facts. */
 export interface ProducedFilesInjected {
   /** Whether the browser itself is connected over loopback. */
@@ -71,81 +40,46 @@ export function ProducedFiles({
   useEffect(() => { ensureWorkspacePathOpen() }, [ensureWorkspacePathOpen])
   const hostCanOpenPath = useWorkspacePathOpen(available => available === true)
   const canOpenPath = isLoopback && hostCanOpenPath
-  const limit = Math.min(paths.length, SHOWN_LIMIT)
-  const [shownCount, setShownCount] = useState(limit)
-  const rowRef = useRef<HTMLDivElement>(null)
-  const chipProbes = useRef<Array<HTMLButtonElement | null>>([])
-  const moreProbe = useRef<HTMLSpanElement>(null)
-
-  useLayoutEffect(() => {
-    const row = rowRef.current
-    const remainderProbe = moreProbe.current
-    /* v8 ignore next -- React attaches both refs before the layout effect runs. */
-    if (row === null || remainderProbe === null) return
-    const measure = (): void => {
-      const styles = getComputedStyle(row)
-      const gap = Number.parseFloat(styles.columnGap || styles.gap) || 0
-      // React attaches every still-mounted callback ref before layout effects run.
-      const activeChipProbes = chipProbes.current.slice(0, limit) as HTMLButtonElement[]
-      const chips = activeChipProbes.map(probe => probe.getBoundingClientRect().width)
-      const more = Array.from({ length: limit + 1 }, (_, candidate) => {
-        if (paths.length === candidate) return undefined
-        remainderProbe.textContent = moreLabel(t, paths.length - candidate)
-        return remainderProbe.getBoundingClientRect().width
-      })
-      setShownCount(fitProducedFiles(row.clientWidth, gap, chips, more))
-    }
-    measure()
-    if (typeof ResizeObserver === 'undefined') return
-    const observer = new ResizeObserver(measure)
-    observer.observe(row)
-    for (const probe of [...chipProbes.current, moreProbe.current]) {
-      if (probe !== null) observer.observe(probe)
-    }
-    return () => { observer.disconnect() }
-  }, [limit, paths, t])
-
-  const visibleCount = Math.min(shownCount, limit)
-  const shown = paths.slice(0, visibleCount)
-  const hidden = paths.length - shown.length
+  const shown = paths.slice(0, SHOWN_LIMIT)
   return (
     <div className={css.root}>
       <span className={css.label}>{t('produced.label')}</span>
-      <div ref={rowRef} className={css.row} data-produced-files-row>
-        {shown.map(path => (
+      <div className={css.lane}>
+        <div className={css.row} data-produced-files-row>
+          {shown.map(path => (
+            <button
+              key={path}
+              type="button"
+              className={css.file}
+              // The full path is the disambiguator when two turns produce files
+              // that share a basename; the chip itself stays short.
+              title={path}
+              aria-label={t('produced.open', { name: path })}
+              onClick={() => { openFile(path) }}
+            >
+              {basename(path)}
+            </button>
+          ))}
+          {shown.map((_, index) => {
+            const shownCount = index + 1
+            const remainder = paths.length - shownCount
+            if (remainder <= 0) return null
+            return (
+              <span key={shownCount} className={css.more} data-shown={shownCount}>
+                {moreLabel(t, remainder)}
+              </span>
+            )
+          })}
+        </div>
+        {paths.length > 1 && canOpenPath && (
           <button
-            key={path}
             type="button"
-            className={css.file}
-            // The full path is the disambiguator when two turns produce files
-            // that share a basename; the chip itself stays short.
-            title={path}
-            aria-label={t('produced.open', { name: path })}
-            onClick={() => { openFile(path) }}
+            className={css.showFolder}
+            onClick={() => { openFile('.') }}
           >
-            {basename(path)}
+            {t('produced.showInFolder')}
           </button>
-        ))}
-        {hidden > 0 && <span className={css.more}>{moreLabel(t, hidden)}</span>}
-      </div>
-      {hidden > 0 && canOpenPath && (
-        <button type="button" className={css.showFolder} onClick={() => { openFile('.') }}>
-          {t('produced.showInFolder')}
-        </button>
-      )}
-      <div className={css.measure} aria-hidden="true">
-        {paths.slice(0, limit).map((path, index) => (
-          <button
-            key={path}
-            ref={(node) => { chipProbes.current[index] = node }}
-            type="button"
-            tabIndex={-1}
-            className={`${css.file} ${css.probe}`}
-          >
-            {basename(path)}
-          </button>
-        ))}
-        <span ref={moreProbe} className={`${css.more} ${css.probe}`} />
+        )}
       </div>
     </div>
   )
diff --git a/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
index 8d45f9b7d5..5e78ccba63 100644
--- a/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
@@ -6,7 +6,7 @@
  * (HMR safety) against the real SlotRegistry.
  */
 import { Context } from '@deepseek-ai/cordis'
-import { act, cleanup, fireEvent, render, within } from '@testing-library/react'
+import { cleanup, fireEvent, render, within } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionLiveEventEntry } from '@deepseek-ai/dsh-api-session-controller/client'
 import {
@@ -21,9 +21,7 @@ import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
 import { apply as applyLocale, inject as localeInject } from '@deepseek-ai/dsh-client-locale/client'
 import type { ChatFileMentions, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { makeTranslate, RemoteError, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
-import {
-  fitProducedFiles, ProducedFiles, type ProducedFilesInjected, type ProducedFilesProps,
-} from '../src/client/ProducedFiles.tsx'
+import { ProducedFiles, type ProducedFilesInjected, type ProducedFilesProps } from '../src/client/ProducedFiles.tsx'
 import {
   basename, deliverablesDefinition, producedFileMentions, producedForClosing, selectProducedFiles,
   type DeliverablesTurnData,
@@ -32,17 +30,10 @@ import { apply, inject } from '../src/client/index.ts'
 import { en, zh } from '../src/client/locales.ts'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 
-const originalClientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'clientWidth')
-
 afterEach(() => {
   cleanup()
   vi.restoreAllMocks()
   vi.unstubAllGlobals()
-  if (originalClientWidth === undefined) {
-    delete (HTMLElement.prototype as { clientWidth?: number }).clientWidth
-  } else {
-    Object.defineProperty(HTMLElement.prototype, 'clientWidth', originalClientWidth)
-  }
 })
 
 class TestTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
@@ -410,48 +401,9 @@ describe('ProducedFiles row', () => {
     }
   }
 
-  it('selects the largest prefix using the exact remainder width', () => {
-    expect(fitProducedFiles(230, 8, [70, 60, 60], [55, 55, 55, 55])).toBe(2)
-    expect(fitProducedFiles(145, 8, [70, 60, 60], [55, 55, 55, 55])).toBe(1)
-    expect(fitProducedFiles(300, 8, [70, 60, 60], [55, 55, 55, 55])).toBe(3)
-    // A zero-width lane is a pre-layout test/hidden state, not evidence that
-    // every chip overflowed; keep the bounded initial prefix until measured.
-    expect(fitProducedFiles(0, 8, [70, 60], [60, 50, undefined])).toBe(2)
-    expect(fitProducedFiles(128, 8, [60, 60], [70, 50, undefined])).toBe(2)
-    // Candidate-specific suffix widths matter at the 10 -> 9 digit boundary.
-    expect(fitProducedFiles(126, 8, [60], [70, 50])).toBe(1)
-    expect(fitProducedFiles(20, 8, [60], [70, 50])).toBe(0)
-  })
-
-  it('keeps one measured line, updates on resize, and opens a file or the workspace folder', () => {
-    const paths = ['deep/a.html', 'b.css', 'c.ts', 'd.ts', 'e.ts', 'f.ts', 'g.ts']
+  it('renders the bounded CSS candidates and opens a file or the workspace folder', () => {
+    const paths = ['deep/a.html', 'b.css', 'c.ts', 'd.ts', 'e.ts', 'f.ts', 'g.ts', 'h.ts']
     const openFile = vi.fn<(path: string) => void>()
-    let available = 226
-    let resize: ResizeObserverCallback | undefined
-    const disconnect = vi.fn()
-    const observeNode = vi.fn<(target: Element) => void>()
-    vi.stubGlobal('ResizeObserver', class {
-      constructor(callback: ResizeObserverCallback) { resize = callback }
-      observe(target: Element): void {
-        expect(target).toBeInstanceOf(Element)
-        observeNode(target)
-      }
-      disconnect(): void { disconnect() }
-    })
-    Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
-      configurable: true,
-      get(this: HTMLElement) { return this.hasAttribute('data-produced-files-row') ? available : 0 },
-    })
-    const rect = (width: number): DOMRect => ({
-      x: 0, y: 0, width, height: 22, top: 0, right: width, bottom: 22, left: 0,
-      toJSON: () => ({}),
-    })
-    const bounds = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect')
-      .mockImplementation(function getProbeRect(this: HTMLElement) {
-        if (this.closest('[aria-hidden="true"]') === null) return rect(0)
-        if (this.tagName !== 'BUTTON') return rect(60)
-        return rect(this.textContent === 'a.html' || this.textContent === 'b.css' ? 50 : 100)
-      })
 
     const view = render(
       <ProducedFiles matched={paths} openFile={openFile} {...capability(true)} t={t} />,
@@ -459,9 +411,8 @@ describe('ProducedFiles row', () => {
     expect(view.getByText('产物')).toBeTruthy()
     const row = view.container.querySelector('[data-produced-files-row]')
     if (!(row instanceof HTMLElement)) throw new Error('produced row missing')
-    // The third probe is 100px: two chips plus the remainder fit, three do not.
-    expect(within(row).getAllByRole('button')).toHaveLength(2)
-    expect(within(row).getByText('+ 5 个文件')).toBeTruthy()
+    expect(within(row).getAllByRole('button')).toHaveLength(6)
+    expect(within(row).getByText('+ 2 个文件')).toBeTruthy()
     const chip = view.getByRole('button', { name: '打开 deep/a.html' })
     expect(chip.textContent).toBe('a.html')
     expect(chip.getAttribute('title')).toBe('deep/a.html')
@@ -472,30 +423,6 @@ describe('ProducedFiles row', () => {
     const showFolder = view.getByRole('button', { name: '在文件夹中显示' })
     fireEvent.click(showFolder)
     expect(openFile).toHaveBeenLastCalledWith('.')
-
-    available = 150
-    act(() => { resize?.([], {} as ResizeObserver) })
-    expect(within(row).getAllByRole('button')).toHaveLength(1)
-    expect(within(row).getByText('+ 6 个文件')).toBeTruthy()
-
-    // A missing/unsupported computed gap falls back to zero rather than NaN.
-    vi.stubGlobal('getComputedStyle', () => ({ columnGap: '', gap: '' } as CSSStyleDeclaration))
-    available = 165
-    act(() => { resize?.([], {} as ResizeObserver) })
-    expect(within(row).getAllByRole('button')).toHaveLength(2)
-
-    // Ref callbacks leave nulls in the probe arrays when the candidate set
-    // shrinks; the replacement observer must skip those stale slots.
-    observeNode.mockClear()
-    view.rerender(
-      <ProducedFiles matched={paths.slice(0, 1)} openFile={openFile} {...capability(true)} t={t} />,
-    )
-    expect(within(row).getAllByRole('button')).toHaveLength(1)
-    expect(observeNode).toHaveBeenCalledTimes(3)
-
-    view.unmount()
-    expect(disconnect).toHaveBeenCalledTimes(2)
-    bounds.mockRestore()
   })
 
   it('keeps the folder action absent without overflow or a local native opener', () => {

From 203e2440ac380e9da75f7a903b74972b86ecc1eb Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 15:53:40 +0800
Subject: [PATCH 09/37] perf(ui-chat): move reasoning tail alignment to CSS

---
 .../src/client/chat/ReasoningRow.module.css   | 17 ++++++-
 .../ui-chat/src/client/chat/ReasoningRow.tsx  | 16 ++----
 .../chat/use-throttled-visual-update.ts       | 40 ---------------
 .../tests/reasoning-row.client.spec.tsx       | 51 +++----------------
 4 files changed, 28 insertions(+), 96 deletions(-)
 delete mode 100644 packages/client/ui-chat/src/client/chat/use-throttled-visual-update.ts

diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css b/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
index 2d7cbe8f07..50056b0d0c 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
@@ -60,11 +60,26 @@
   color: var(--dsw-alias-label-tertiary);
   font-size: var(--dsh-content-font-size-secondary, 13px);
   line-height: calc(20px + var(--dsh-content-font-delta-secondary, 0px));
-  text-overflow: ellipsis;
   white-space: nowrap;
 }
 
+.summaryText {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
 .summary[data-follow-end] {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.summary[data-follow-end] .summaryText {
+  flex: 0 0 auto;
+  width: max-content;
+  min-width: 100%;
+  overflow: visible;
+  text-align: start;
   text-overflow: clip;
 }
 
diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
index 1f5fba56b8..b3a6e2a9b7 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
@@ -1,8 +1,7 @@
 /** Assistant reasoning disclosure, independent of Tool-call presentation. */
-import { useEffect, useRef, useState } from 'react'
+import { useState } from 'react'
 import { DisclosureRow, IconThinkOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { useThrottledVisualUpdate } from './use-throttled-visual-update.ts'
 import a11yCss from './accessibility.module.css'
 import css from './ReasoningRow.module.css'
 
@@ -26,16 +25,7 @@ function latestLine(text: string): string {
  */
 export function ReasoningRow({ text, running, t }: { text: string; running: boolean; t: ChatViewSlotProps['t'] }) {
   const [expanded, setExpanded] = useState(false)
-  const summaryRef = useRef<HTMLSpanElement>(null)
   const summary = running ? latestLine(text) : firstLine(text)
-  const scheduleSummaryScroll = useThrottledVisualUpdate(() => {
-    const element = summaryRef.current
-    if (element === null) return
-    element.scrollLeft = running ? element.scrollWidth - element.clientWidth : 0
-  })
-  useEffect(() => {
-    scheduleSummaryScroll()
-  }, [running, scheduleSummaryScroll, summary])
 
   return (
     <div className={css.root} data-variant="think" data-state={running ? 'running' : 'ok'}>
@@ -54,7 +44,9 @@ export function ReasoningRow({ text, running, t }: { text: string; running: bool
         collapsedContent={(
           <>
             <span className={css.separator} aria-hidden />
-            <span ref={summaryRef} className={css.summary} data-follow-end={running || undefined}>{summary}</span>
+            <span className={css.summary} data-follow-end={running || undefined}>
+              <span className={css.summaryText}>{summary}</span>
+            </span>
           </>
         )}
       >
diff --git a/packages/client/ui-chat/src/client/chat/use-throttled-visual-update.ts b/packages/client/ui-chat/src/client/chat/use-throttled-visual-update.ts
deleted file mode 100644
index 8fec1832d1..0000000000
--- a/packages/client/ui-chat/src/client/chat/use-throttled-visual-update.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-/** Frame-throttled scheduling for non-essential visual alignment. */
-import { useCallback, useLayoutEffect, useRef } from 'react'
-
-const DEFAULT_INTERVAL_FRAMES = 3
-
-/**
- * Return a stable scheduler that coalesces visual updates over a frame interval.
- * @param update - DOM alignment to run after the throttle interval.
- * @param intervalFrames - frames to wait before applying the latest alignment.
- * @returns a stable function that schedules the latest update.
- */
-export function useThrottledVisualUpdate(
-  update: () => void,
-  intervalFrames = DEFAULT_INTERVAL_FRAMES,
-): () => void {
-  const updateRef = useRef(update)
-  updateRef.current = update
-  const pendingFrameRef = useRef<number | null>(null)
-
-  useLayoutEffect(() => () => {
-    if (pendingFrameRef.current === null) return
-    cancelAnimationFrame(pendingFrameRef.current)
-    pendingFrameRef.current = null
-  }, [])
-
-  return useCallback(() => {
-    if (pendingFrameRef.current !== null) return
-    let remainingFrames = intervalFrames
-    const advance = (): void => {
-      remainingFrames -= 1
-      if (remainingFrames > 0) {
-        pendingFrameRef.current = requestAnimationFrame(advance)
-        return
-      }
-      pendingFrameRef.current = null
-      updateRef.current()
-    }
-    pendingFrameRef.current = requestAnimationFrame(advance)
-  }, [intervalFrames])
-}
diff --git a/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx b/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
index 3867d2a14c..4b32f77119 100644
--- a/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
+++ b/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
@@ -1,46 +1,20 @@
 // @vitest-environment jsdom
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { zh } from '../src/client/locale.ts'
 import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
 
-let nextAnimationFrameId = 1
-let animationFrames = new Map<number, FrameRequestCallback>()
-
-function flushAnimationFrames(count: number): void {
-  for (let index = 0; index < count; index += 1) {
-    const callbacks = [...animationFrames.values()]
-    animationFrames.clear()
-    for (const callback of callbacks) callback(index)
-  }
-}
-
-beforeEach(() => {
-  nextAnimationFrameId = 1
-  animationFrames = new Map()
-  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
-    const id = nextAnimationFrameId
-    nextAnimationFrameId += 1
-    animationFrames.set(id, callback)
-    return id
-  })
-  vi.stubGlobal('cancelAnimationFrame', (id: number) => {
-    animationFrames.delete(id)
-  })
-})
-
 afterEach(() => {
   cleanup()
-  vi.unstubAllGlobals()
 })
 
 const t = makeTranslate(zh, commonZh)
 const renderMessageImages: AssistantMarkdownProps['renderMessageImages'] = () => null
 
 describe('ReasoningRow', () => {
-  it('follows the latest streaming line, scrolls to its end, then restores the settled first line', () => {
+  it('follows the latest streaming line, then restores the settled first line', () => {
     const view = render(
       <AssistantMarkdown
         t={t}
@@ -50,11 +24,8 @@ describe('ReasoningRow', () => {
       />,
     )
     expect(view.getByText('运行中')).toBeTruthy()
-    const summary = view.getByText('Newest reasoning tokens')
-    Object.defineProperties(summary, {
-      scrollWidth: { configurable: true, value: 300 },
-      clientWidth: { configurable: true, value: 100 },
-    })
+    expect(view.getByText('Newest reasoning tokens').parentElement?.getAttribute('data-follow-end'))
+      .toBe('true')
 
     view.rerender(
       <AssistantMarkdown
@@ -64,12 +35,8 @@ describe('ReasoningRow', () => {
         renderMessageImages={renderMessageImages}
       />,
     )
-    expect(summary.scrollLeft).toBe(0)
-    flushAnimationFrames(2)
-    expect(summary.scrollLeft).toBe(0)
-    flushAnimationFrames(1)
-    expect(summary.scrollLeft).toBe(200)
-    expect(summary.getAttribute('data-follow-end')).toBe('true')
+    expect(view.getByText('Newest reasoning tokens keep arriving').parentElement
+      ?.getAttribute('data-follow-end')).toBe('true')
 
     view.rerender(
       <AssistantMarkdown
@@ -79,11 +46,9 @@ describe('ReasoningRow', () => {
         renderMessageImages={renderMessageImages}
       />,
     )
-    flushAnimationFrames(3)
-    expect(view.getByText('Inspect the session')).toBeTruthy()
+    const settledSummary = view.getByText('Inspect the session')
     expect(view.queryByText('运行中')).toBeNull()
-    expect(summary.scrollLeft).toBe(0)
-    expect(summary.hasAttribute('data-follow-end')).toBe(false)
+    expect(settledSummary.parentElement?.hasAttribute('data-follow-end')).toBe(false)
   })
 
   it('expands from either Think or the reasoning summary', () => {

From 81431381d68fea3c5adf505aa1c2942286f50a68 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 15:54:53 +0800
Subject: [PATCH 10/37] perf(conversation): reuse unchanged location
 projections

---
 .../client/conversation-nodes/assistant.ts    | 24 +++++--
 .../client/conversation-nodes/turn-process.ts | 67 +++++++++++++++----
 .../client/conversation-nodes/turn-tail.ts    |  5 +-
 ...nversation-node-definitions.client.spec.ts | 30 +++++++++
 .../src/client/contract/conversation.ts       |  5 +-
 .../src/client/conversation/assembler.ts      | 10 +--
 .../conversation-assembler.client.spec.ts     | 46 +++++++++++++
 .../src/client/turn-deliverables.ts           | 13 ++--
 8 files changed, 169 insertions(+), 31 deletions(-)

diff --git a/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts b/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts
index a6a460f0ea..0b23226cde 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts
@@ -364,6 +364,13 @@ function projectAssistant(context: ConversationNodeContext<AssistantState>): Ass
   }
 }
 
+function publishedAssistantData(
+  context: ConversationNodeContext<AssistantState>,
+): Readonly<AssistantChatData> | undefined {
+  const location = context.start?.location ?? context.matches.at(-1)?.location
+  return location?.kind === 'step' ? location.step.data.get('assistant-step') : undefined
+}
+
 /** Per-step Assistant streaming/final/interruption Definition. */
 export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
   kind: 'assistant-step',
@@ -427,16 +434,19 @@ export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
     }
   },
   buildViewNode: (context) => {
-    const projected = projectAssistant(context)
-    if (projected === undefined) return null
-    if (projected.settled === undefined && !projected.visible) {
-      const state = context.state ?? fallbackState(context)
-      if (state === undefined) return null
+    const state = context.state ?? fallbackState(context)
+    if (state === undefined) return null
+    const data = publishedAssistantData(context)
+    if (data === undefined) return null
+    const settled = data.finalNode
+    const visible = settled === undefined ? state.visibleBlocks > 0 : hasVisibleContent(data.blocks)
+    if (settled === undefined && !visible) {
       const current = context.current.get('chat')
       if (!state.hidden || current === undefined || current === null) return null
     }
-    return chatNode(context, 'assistant-step', projected.anchorSeq, projected.data, {
-      visibility: projected.settled?.interrupted === true || projected.visible ? 'visible' : 'hidden',
+    const anchorSeq = settled?.seq ?? state.firstVisibleSeq ?? context.matches[0]?.event.seq ?? 0
+    return chatNode(context, 'assistant-step', anchorSeq, data, {
+      visibility: settled?.interrupted === true || visible ? 'visible' : 'hidden',
     })
   },
 }
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-process.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-process.ts
index fd04874615..bacd360a57 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/turn-process.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-process.ts
@@ -7,7 +7,7 @@ import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
 import type {} from '@deepseek-ai/dsh-tools/types'
 import { hasAssistantReplyContent } from '../contract/assistant-content.ts'
-import type { AssistantChatData, FinalAssistantChatData } from '../contract/chat-nodes.ts'
+import type { AssistantChatData, ChatNode, FinalAssistantChatData } from '../contract/chat-nodes.ts'
 import {
   decodeTurnProcess, encodeTurnProcess, isSubagentDelegationTool,
   type TurnProcessSignature, type TurnProcessSpec,
@@ -34,6 +34,8 @@ interface TurnProcessState {
   readonly assistantStartByStep: ReadonlyMap<number, number>
   readonly messageCountByStep: ReadonlyMap<number, number>
   readonly otherStartSeq?: number
+  readonly controlAnchorSeq?: number
+  readonly messageCount: number
   readonly toolCallCount: number
   readonly subagentCount: number
 }
@@ -109,6 +111,7 @@ function fallbackState(context: ConversationNodeContext<TurnProcessState>): Turn
     turn,
     assistantStartByStep: new Map(),
     messageCountByStep: new Map(),
+    messageCount: 0,
     toolCallCount: 0,
     subagentCount: 0,
   }
@@ -130,15 +133,12 @@ function latestAnswer(turn: TurnLocation): Readonly<FinalAssistantChatData> | nu
 }
 
 function processSpec(state: TurnProcessState, turn: TurnLocation): TurnProcessSpec | null {
-  const controlAnchorSeq = Math.min(
-    state.otherStartSeq ?? Number.POSITIVE_INFINITY,
-    ...state.assistantStartByStep.values(),
-  )
-  if (!Number.isFinite(controlAnchorSeq)) return null
+  const controlAnchorSeq = state.controlAnchorSeq
+  if (controlAnchorSeq === undefined) return null
   const answer = latestAnswer(turn)
   const counts = {
     messageCount: answer === null
-      ? [...state.messageCountByStep.values()].reduce((total, count) => total + count, 0)
+      ? state.messageCount
       : [...state.messageCountByStep]
         .filter(([step]) => step < answer.step)
         .reduce((total, [, count]) => total + count, 0),
@@ -185,7 +185,7 @@ function updateProcessState(state: TurnProcessState, event: ConversationEvent):
     && hasAssistantReplyContent(toAssistantBlocks(event.data.message.content))) {
     const messageCountByStep = new Map(current.messageCountByStep)
     messageCountByStep.set(event.data.step, (messageCountByStep.get(event.data.step) ?? 0) + 1)
-    current = { ...current, messageCountByStep }
+    current = { ...current, messageCountByStep, messageCount: current.messageCount + 1 }
   }
   if (event.type === 'tool/call') {
     const subagent = isSubagentDelegationTool(event.data.name)
@@ -198,12 +198,22 @@ function updateProcessState(state: TurnProcessState, event: ConversationEvent):
   const evidence = processEvidence(event)
   if (evidence === undefined) return current
   if (evidence.kind === 'other') {
-    return current.otherStartSeq === undefined ? { ...current, otherStartSeq: evidence.seq } : current
+    return current.otherStartSeq === undefined
+      ? {
+        ...current,
+        otherStartSeq: evidence.seq,
+        controlAnchorSeq: Math.min(current.controlAnchorSeq ?? Number.POSITIVE_INFINITY, evidence.seq),
+      }
+      : current
   }
   if (current.assistantStartByStep.has(evidence.step)) return current
   const assistantStartByStep = new Map(current.assistantStartByStep)
   assistantStartByStep.set(evidence.step, evidence.seq)
-  return { ...current, assistantStartByStep }
+  return {
+    ...current,
+    assistantStartByStep,
+    controlAnchorSeq: Math.min(current.controlAnchorSeq ?? Number.POSITIVE_INFINITY, evidence.seq),
+  }
 }
 
 /** Turn-scoped process range and answer-boundary Definition. */
@@ -233,6 +243,7 @@ export const turnProcessDefinition: ConversationNodeDefinition<TurnProcessState>
       turn: match.event.data.turn,
       assistantStartByStep: new Map(),
       messageCountByStep: new Map(),
+      messageCount: 0,
       toolCallCount: 0,
       subagentCount: 0,
     }
@@ -246,24 +257,54 @@ export const turnProcessDefinition: ConversationNodeDefinition<TurnProcessState>
     }
     return 'immediate'
   },
-  buildLocationData: (context, scope) => {
+  buildLocationData: (context, scope, previous) => {
     if (scope !== 'turn') return null
     const state = context.state ?? fallbackState(context)
     if (state === undefined) return null
     const turn = turnLocation(context)
     if (turn === undefined) return null
+    const current = context.current.get('chat') as ChatNode | null | undefined
+    const latestStep = turn.steps.at(-1)
+    if (previous?.kind === 'turn'
+      && previous.key === 'turn-process'
+      && current?.kind === 'turn-process'
+      && current.data.answerAnchorSeq === null
+      && current.data.controlAnchorSeq === state.controlAnchorSeq
+      && current.data.messageCount === state.messageCount
+      && current.data.toolCallCount === state.toolCallCount
+      && current.data.subagentCount === state.subagentCount
+      && turn.status !== 'closed'
+      && latestStep?.status !== 'closed') return previous
     const spec = processSpec(state, turn)
-    return spec === null ? null : {
+    if (spec === null) return null
+    const value = encodeTurnProcess(spec)
+    if (previous?.kind === 'turn'
+      && previous.turn === spec.turn
+      && previous.key === 'turn-process'
+      && previous.value === value) return previous
+    return {
       kind: 'turn',
       turn: turn.turn,
       key: 'turn-process',
-      value: encodeTurnProcess(spec),
+      value,
     }
   },
   buildViewNode: (context) => {
     const turn = turnLocation(context)
     const signature = turn?.data.get('turn-process')
     if (turn === undefined || signature === undefined) return null
+    const current = context.current.get('chat') as ChatNode | null | undefined
+    const state = context.state
+    if (current?.kind === 'turn-process'
+      && state !== undefined
+      && current.data.answerAnchorSeq === null
+      && current.data.controlAnchorSeq === state.controlAnchorSeq
+      && current.data.messageCount === state.messageCount
+      && current.data.toolCallCount === state.toolCallCount
+      && current.data.subagentCount === state.subagentCount
+      && turn.status !== 'closed'
+      && turn.steps.at(-1)?.status !== 'closed'
+      && current.location === (context.start?.location ?? context.matches[0]?.location)) return current
     const data = decodeTurnProcess(signature)
     return chatNode(
       context,
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-tail.ts
index 9791ee5ceb..3bcc852ab1 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/turn-tail.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-tail.ts
@@ -134,8 +134,9 @@ function hasText(data: AssistantChatData): data is FinalAssistantChatData {
 }
 
 function tailData(context: ConversationNodeContext<TurnTailState>): TurnTailChatData | null {
-  const end = context.state?.end
-    ?? context.matches.find(match => match.event.type === 'turn/end')
+  const end = context.state === undefined
+    ? context.matches.find(match => match.event.type === 'turn/end')
+    : context.state.end
   if (end?.event.type !== 'turn/end') return null
   const turn = turnLocation(context)
   if (turn === undefined) return null
diff --git a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
index 00484dc6c5..ca637e1d4d 100644
--- a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
+++ b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
@@ -608,6 +608,30 @@ describe('built-in conversation node Definitions', () => {
     expect(settled.answerStep).toBe(1)
   })
 
+  it('reuses the open Turn-process projection across continuing Assistant chunks', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'assistant/chunk', {
+        turn: 1, step: 1, chunk: { type: 'reasoning-delta', index: 0, text: 'first' },
+      }),
+    ])
+    const before = snapshot(value)
+    const processNode = node(before, 'turn-process')
+    const processSignature = before.timeline.turns.get(1)?.data.get('turn-process')
+    const assistantNode = node(before, 'assistant-step')
+
+    value.append(at(4, 'assistant/chunk', {
+      turn: 1, step: 1, chunk: { type: 'reasoning-delta', index: 0, text: ' second' },
+    }))
+    value.flush()
+
+    const after = snapshot(value)
+    expect(after.timeline.turns.get(1)?.data.get('turn-process')).toBe(processSignature)
+    expect(node(after, 'turn-process')).toBe(processNode)
+    expect(node(after, 'assistant-step')).not.toBe(assistantNode)
+  })
+
   it('anchors a streamed non-text answer from its block start', () => {
     const value = assembler([
       at(50, 'turn/start', { turn: 5 }),
@@ -640,6 +664,9 @@ describe('built-in conversation node Definitions', () => {
     const runningSnapshot = snapshot(value)
     const running = node(runningSnapshot, 'assistant-step')
     expect(running?.data).toMatchObject({ status: 'running', blocks: [{ kind: 'text', text: 'streaming' }] })
+    expect(running?.location.kind === 'step'
+      ? running.location.step.data.get('assistant-step')
+      : undefined).toBe(running?.data)
     const order = runningSnapshot.order
 
     value.append(at(4, 'assistant/message', {
@@ -654,6 +681,9 @@ describe('built-in conversation node Definitions', () => {
     expect(settled?.key).toBe(running?.key)
     expect(settledSnapshot.order).toBe(order)
     expect(settled?.data).toMatchObject({ status: 'settled', blocks: [{ kind: 'text', text: 'settled' }] })
+    expect(settled?.location.kind === 'step'
+      ? settled.location.step.data.get('assistant-step')
+      : undefined).toBe(settled?.data)
 
     const interruptedValue = assembler([
       at(10, 'turn/start', { turn: 2 }),
diff --git a/packages/client/ui-conversation/src/client/contract/conversation.ts b/packages/client/ui-conversation/src/client/contract/conversation.ts
index 7864383947..ea3ec1c6e0 100644
--- a/packages/client/ui-conversation/src/client/contract/conversation.ts
+++ b/packages/client/ui-conversation/src/client/contract/conversation.ts
@@ -210,11 +210,14 @@ export interface ConversationNodeDefinition<State = unknown> {
    * the same Location key.
    * @param context - latest complete Context.
    * @param scope - Location hierarchy level currently being materialized.
-   * @returns current Location value, or null while unavailable.
+   * @param previous - value from the preceding materialization; return it when unchanged.
+   * @returns current Location value, preserving value identity while unchanged,
+   * or null while unavailable.
    */
   buildLocationData?(
     context: ConversationNodeContext<State>,
     scope: ConversationLocationDataScope,
+    previous: ConversationLocationData | null,
   ): ConversationLocationData | null
   /**
    * Materialize one final Node for this Definition's declared view target.
diff --git a/packages/client/ui-conversation/src/client/conversation/assembler.ts b/packages/client/ui-conversation/src/client/conversation/assembler.ts
index df81e4b7b3..2f752245c4 100644
--- a/packages/client/ui-conversation/src/client/conversation/assembler.ts
+++ b/packages/client/ui-conversation/src/client/conversation/assembler.ts
@@ -826,9 +826,10 @@ export class ConversationNodeAssembler implements ConversationViewSnapshotStore
   private buildLocationData(
     context: InternalContext,
     scope: ConversationLocationDataScope,
+    previous: ConversationLocationData | null,
   ): ConversationLocationData | null {
     if (context.definition.buildLocationData === undefined) return null
-    const data = context.definition.buildLocationData(contextSnapshot(context), scope)
+    const data = context.definition.buildLocationData(contextSnapshot(context), scope, previous)
     if (data === null) return null
     if (data.kind !== scope) {
       throw new Error(
@@ -853,7 +854,7 @@ export class ConversationNodeAssembler implements ConversationViewSnapshotStore
     const entries: { owner: string; data: ConversationLocationData }[] = []
     for (const scope of LOCATION_DATA_SCOPES) {
       for (const context of this.contexts.values()) {
-        const data = this.buildLocationData(context, scope)
+        const data = this.buildLocationData(context, scope, context.locationData[scope])
         context.locationData[scope] = data
         if (data !== null) entries.push({ owner: context.key, data })
       }
@@ -869,9 +870,10 @@ export class ConversationNodeAssembler implements ConversationViewSnapshotStore
       const changes: ConversationLocationDataChange[] = []
       for (const context of this.dirty) {
         const previous = context.locationData[scope]
-        const next = this.buildLocationData(context, scope)
+        const next = this.buildLocationData(context, scope, previous)
+        if (previous === next) continue
         context.locationData[scope] = next
-        if (previous !== next) changes.push({ owner: context.key, previous, next })
+        changes.push({ owner: context.key, previous, next })
       }
       changed = this.locationIndex.applyData(changes) || changed
     }
diff --git a/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts b/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
index 0e95e83465..1a98abd0e1 100644
--- a/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
@@ -1005,6 +1005,52 @@ describe('ConversationNodeAssembler', () => {
       .toEqual({ step: 2, turn: 2 })
   })
 
+  it('does not republish an equivalent Location value', () => {
+    const apply = vi.fn()
+    const initialValue = { value: 1 }
+    const changedValue = { value: 2 }
+    const definition: ConversationNodeDefinition<{ readonly value: ScopeProbeStepData }> = {
+      kind: 'scope-probe',
+      match: (event) => {
+        if (event.type === 'step/start') return { id: '1:1', role: 'start' }
+        if ((event.type as string) === 'scope-probe/update') return { id: '1:1', role: 'update' }
+        return null
+      },
+      start: () => ({ value: initialValue }),
+      update: (_context, match) => ({
+        value: (match.event.data as unknown as { changed: boolean }).changed
+          ? changedValue
+          : initialValue,
+      }),
+      buildLocationData: (context, scope, previous) => {
+        if (scope !== 'step' || context.state === undefined) return null
+        if (previous?.kind === 'step'
+          && previous.turn === 1
+          && previous.step === 1
+          && previous.key === 'scope-probe'
+          && previous.value === context.state.value) return previous
+        return { kind: 'step', turn: 1, step: 1, key: 'scope-probe', value: context.state.value }
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView(apply)]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+    ], false)
+    assembler.flush()
+
+    assembler.append(input(at(3, 'scope-probe/update', { turn: 1, step: 1, changed: false })))
+    expect(assembler.flush()).toBe(false)
+    expect(apply).not.toHaveBeenCalled()
+
+    assembler.append(input(at(4, 'scope-probe/update', { turn: 1, step: 1, changed: true })))
+    expect(assembler.flush()).toBe(true)
+    expect(apply).toHaveBeenCalledOnce()
+  })
+
   it('updates existing turn Locations when their Step membership changes', () => {
     const apply = vi.fn()
     const definition: ConversationNodeDefinition<null> = {
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index b7f74f305b..90e3248516 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -177,14 +177,19 @@ export const deliverablesDefinition: ConversationNodeDefinition<DeliverablesStat
       ? context.state
       : { ...context.state, produced: [...context.state.produced, { seq: match.event.seq, path }] }
   },
-  buildLocationData: (context, scope) => scope !== 'turn' || context.state === undefined
-    ? null
-    : {
+  buildLocationData: (context, scope, previous) => {
+    if (scope !== 'turn' || context.state === undefined) return null
+    if (previous?.kind === 'turn'
+      && previous.turn === context.state.turn
+      && previous.key === 'deliverables'
+      && previous.value.produced === context.state.produced) return previous
+    return {
       kind: 'turn',
       turn: context.state.turn,
       key: 'deliverables',
       value: { produced: context.state.produced },
-    },
+    }
+  },
 }
 
 /**

From c809098b06480f44f73165a23027abc41801882b Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 15:55:41 +0800
Subject: [PATCH 11/37] perf(conversation): publish streaming updates every two
 frames

---
 ...lient-conversation-node-assembly.i18n.yaml |  4 +-
 ...08-09-client-conversation-node-assembly.md | 10 +-
 ...09-client-conversation-node-assembly.zh.md | 10 +-
 .../src/client/contract/conversation.ts       |  2 +-
 .../src/client/conversation/assembly.ts       | 20 ++--
 .../conversation-registry.client.spec.ts      | 99 ++++++++++++++++++-
 6 files changed, 126 insertions(+), 19 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index c60b8ae3ba..e9826ffc02 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 4831c2261791749804b6d0bd555423b7d4894520
-2026-08-09-client-conversation-node-assembly.zh.md: 37463d0543bbabc5d236f662827b932b55bbb11d
+2026-08-09-client-conversation-node-assembly.md: 5efb808af3d551ab65304d5a8d69947f63f25a05
+2026-08-09-client-conversation-node-assembly.zh.md: 870598b46d156d3399d874d6fd1cfc18d5dc3ada
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 4831c22617..5efb808af3 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -125,16 +125,16 @@ The Assembler does not use State reference equality to decide publication or pro
 | Return value | Behavior |
 |---|---|
 | `immediate` | Request a notification and flush in the current microtask |
-| `animation-frame` | Coalesce high-frequency updates into materialization on the next frame |
+| `animation-frame` | Coalesce high-frequency updates into materialization after two browser animation frames |
 | `none` | Do not schedule a flush for this Match; retain its State and dirty marker |
 
 Omitting `publication()` means `immediate`. Assistant token deltas and packed runs use `animation-frame`, invisible Inbox Contexts use `none`, and finals, dependency replays, and Location boundaries publish the latest result through an immediate path.
 
-Every live delta within a frame still executes `update()`, while one historical packed run executes one batch `update()`. Only `buildViewNode()`, View Builder work, and React snapshot notification are coalesced; no fragments are lost.
+Every live delta during the two-frame interval still executes `update()`, while one historical packed run executes one batch `update()`. Location-data publication, `buildViewNode()`, View Builder work, and React snapshot notification are coalesced; no fragments are lost. An immediate publication cancels a pending frame interval and flushes the latest State without delay.
 
 #### `buildLocationData(context, scope)`
 
-`buildLocationData()` lets a Definition publish a read-only value derived from its State onto an engine-owned Step or Turn without exposing another business's mutable State. The Assembler always materializes `step` before `turn`, so Turn-level aggregation can read Step data updated in the same flush; it calls `buildViewNode()` only after all Location data is ready.
+`buildLocationData()` lets a Definition publish a read-only value derived from its State onto an engine-owned Step or Turn without exposing another business's mutable State. The Assembler passes the preceding publication back to its owner, which returns that exact value when its business data is unchanged. The Assembler always materializes `step` before `turn`, so Turn-level aggregation can read Step data updated in the same flush; it calls `buildViewNode()` only after all Location data is ready.
 
 A Definition receives the `step` and `turn` scopes separately and may return one value or `null` in either phase. A value must identify the exact turn/step coordinates and use the Definition's `kind` as its key. The Assembler owns replacement and removal and rejects another Context that claims the same Location key.
 
@@ -390,6 +390,8 @@ History-path tests cover complete replace, non-overlapping prepend, complete-ran
 
 **Let a Location-data consumer read the provider's Context State directly.** Rejected: the consumer would depend on another business's mutable internal shape and could not express which Turn/Step owns the value. Declaration-merged data maps expose only the provider-selected read-only value and engine-owned coordinates.
 
+**Cache every Definition's Location data by State identity.** Rejected because a Definition may mutate and return the same State object, and its Location data may also depend on Match Locations or values published by another Definition. Each Definition instead decides whether its business value changed and returns the preceding publication unchanged when it did not.
+
 **Add generic `end()`, prepared, or window-reset lifecycles.** Rejected: businesses have different completion conditions, and a pagination gap is not a business lifecycle. Business Events update State, Location close triggers replay/build, and Reader dependencies own pagination invalidation.
 
 **Reuse one Event Definition across Chat and Trajectory by branching in `buildViewNode(target)`.** Rejected: the views require different business State and intermediate records, so a shared Definition would make each package carry the other's conditions and payloads. Separate target-owned Definitions keep those choices local while sharing the Assembler's ingestion and lifecycle contracts.
@@ -412,7 +414,7 @@ Initial tail, older prepend, and live append share one set of Context invariants
 
 Append does not scan historical Contexts; prepend replays only Contexts whose Matches, Locations, or Reader answers actually changed. A structural Chat change may still recompute visible order and indexes, but does not rerun unrelated business folds or replace unchanged Node identity.
 
-Separating State updates from publication cadence folds every live Assistant delta and each historical packed run while materializing at most once per animation frame. Step or Turn close and final Events can immediately publish the latest State.
+Separating State updates from publication cadence folds every live Assistant delta and each historical packed run while materializing at most once per two animation frames. The Assistant view reads the same projection that the preceding Step Location phase installed. Turn Process returns its existing open data and Node for continuing Assistant chunks without deriving or encoding them again, and Turn Tail defers its complete-Match scan until `turn/end`. Step or Turn close and final Events immediately publish the latest State.
 
 An inactive target retains Definition State and a target Context index but no builder, materialized Nodes, or snapshot. The mounted built-in or third-party View activates its own target through normal subscription; previously opened targets continue receiving incremental updates.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index 37463d0543..870598b46d 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -125,16 +125,16 @@ Assembler 不以 State 引用相等判断是否需要发布或传播。每次成
 | 返回值 | 行为 |
 |---|---|
 | `immediate` | 请求当前 microtask 通知与 flush |
-| `animation-frame` | 把多条高频更新合并到下一帧 materialize |
+| `animation-frame` | 跨过两个浏览器 animation frame 后，把多条高频更新合并为一次 materialization |
 | `none` | 本 Match 不主动安排 flush，State 和 dirty 标记仍被保留 |
 
 省略 `publication()` 等于 `immediate`。Assistant token delta 与 packed run 使用 `animation-frame`，不可见 Inbox Context 使用 `none`，final、依赖 replay 和 Location 边界会以 immediate 路径发布最新结果。
 
-一帧内的每条 live delta 仍执行 `update()`，一个历史 packed run 则执行一次 batch `update()`；合并的只是 `buildViewNode()`、View Builder 和 React snapshot 通知，不会丢失 fragment。
+两帧间隔内的每条 live delta 仍执行 `update()`，一个历史 packed run 则执行一次 batch `update()`；Location-data publication、`buildViewNode()`、View Builder 与 React snapshot 通知会合并执行，不会丢失 fragment。immediate publication 会取消等待中的帧间隔，并立即发布最新 State。
 
 #### `buildLocationData(context, scope)`
 
-`buildLocationData()` 让 Definition 把 State 的只读派生值发布到 Engine-owned Step 或 Turn，而不把另一个业务的可变 State 暴露出去。Assembler 在每次 materialize 中固定先处理 `step`、再处理 `turn`，因此 Turn 级聚合可以读取同一轮已经更新的 Step data；全部 Location data 就绪后才调用 `buildViewNode()`。
+`buildLocationData()` 让 Definition 把 State 的只读派生值发布到 Engine-owned Step 或 Turn，而不把另一个业务的可变 State 暴露出去。Assembler 会把前一次 publication 传回它的 owner；业务数据未变时，owner 原样返回该值。Assembler 在每次 materialize 中固定先处理 `step`、再处理 `turn`，因此 Turn 级聚合可以读取同一轮已经更新的 Step data；全部 Location data 就绪后才调用 `buildViewNode()`。
 
 Definition 分别收到 `step` 和 `turn` scope，可以在任一阶段返回一个值或 `null`。返回值必须声明准确的 turn/step 坐标，并使用与 Definition `kind` 相同的 key；Assembler 拥有替换和移除，并拒绝另一个 Context 占用同一 Location key。
 
@@ -390,6 +390,8 @@ Assembled Web snapshot、GUI 和浏览器场景覆盖真实 plugin graph。浏
 
 **让 Location data 消费者直接读取提供方 Context State。** 拒绝：消费者会依赖另一个业务的可变内部形状，也无法表达值属于哪个 Turn/Step。declaration-merged data map 只公开提供方选择发布的只读值和 Engine-owned 坐标。
 
+**按 State identity 缓存每个 Definition 的 Location data。** 拒绝：Definition 可以原地修改并返回同一个 State 对象，其 Location data 也可能依赖 Match Location 或其他 Definition 发布的 value。各 Definition 改为自行判断业务值是否变化；未变化时原样返回前一次 publication。
+
 **增加通用 `end()`、prepared 或 window reset 生命周期。** 拒绝：不同业务完成条件不同，分页缺口也不是业务生命周期。业务 Event 更新 State，Location close 触发 replay/build，Reader dependency 负责补页失效。
 
 **在同一个 Event Definition 内通过 `buildViewNode(target)` 为 Chat 与 Trajectory 分支。** 拒绝：两种视图需要不同的业务 State 与中间记录，共用 Definition 会迫使每个 package 携带另一边的条件与 payload。target 自有的 Definition 把这些选择留在本地，同时复用 Assembler 的摄入与生命周期约定。
@@ -412,7 +414,7 @@ Host 业务 package 把自己的持久 Event 成员 declaration-merge 到 `@deep
 
 Append 不扫描历史 Context；prepend 只 replay Match、Location 或 Reader 答案真正受影响的 Context。Chat 结构变化仍可能重算 visible order 和索引，但不会重跑无关业务 fold 或替换未变化 Node identity。
 
-State 更新与发布频率分离后，Assistant 的每条 live delta 与每个历史 packed run 都会被 fold，同时每 animation frame 最多 materialize 一次。step/turn close 和 final 可立即发布最新 State。
+State update 与 publication cadence 分离后，Assistant 的每条 live delta 与每个历史 packed run 都会被 fold，同时每两个 animation frame 最多 materialize 一次。Assistant view 读取前置 Step Location 阶段刚写入的同一 projection。Turn Process 对持续 Assistant chunk 直接返回已有 open data 和 Node，不再重复派生或编码；Turn Tail 到 `turn/end` 才执行完整 Match 扫描。Step/Turn close 与 final Event 会立即发布最新 State。
 
 inactive target 会保留 Definition State 和 target Context 索引，但不保留 builder、已物化 Node 或 snapshot。已挂载的内建或第三方 View 通过正常订阅激活自己的 target；已经打开的 target 则继续接收增量更新。
 
diff --git a/packages/client/ui-conversation/src/client/contract/conversation.ts b/packages/client/ui-conversation/src/client/contract/conversation.ts
index ea3ec1c6e0..77808ba52c 100644
--- a/packages/client/ui-conversation/src/client/contract/conversation.ts
+++ b/packages/client/ui-conversation/src/client/contract/conversation.ts
@@ -158,7 +158,7 @@ export interface ConversationContextReader {
   previous<State>(kind: string): ConversationPreviousContext<State> | undefined
 }
 
-/** Requested cadence for materializing updated business State into view Nodes. */
+/** Requested cadence; `animation-frame` materializes after two browser animation frames. */
 export type ConversationPublication = 'none' | 'animation-frame' | 'immediate'
 
 /** Engine-owned Location data publication phase. */
diff --git a/packages/client/ui-conversation/src/client/conversation/assembly.ts b/packages/client/ui-conversation/src/client/conversation/assembly.ts
index 6957f5874e..0741d600b2 100644
--- a/packages/client/ui-conversation/src/client/conversation/assembly.ts
+++ b/packages/client/ui-conversation/src/client/conversation/assembly.ts
@@ -86,10 +86,7 @@ class BoundConversation implements ConversationBinding {
   rebuild(): void { this.publish(this.assembler.rebuildRegistry()) }
 
   dispose(): void {
-    if (this.frame !== undefined && typeof cancelAnimationFrame === 'function') {
-      cancelAnimationFrame(this.frame)
-    }
-    this.frame = undefined
+    this.cancelFrame()
     this.disposeFeed()
   }
 
@@ -124,15 +121,26 @@ class BoundConversation implements ConversationBinding {
     if (publication === 'none') return
     if (publication === 'animation-frame' && typeof requestAnimationFrame === 'function') {
       if (this.frame !== undefined) return
+      // Cross two paint opportunities before publishing high-frequency stream updates.
       this.frame = requestAnimationFrame(() => {
-        this.frame = undefined
-        this.flush()
+        this.frame = requestAnimationFrame(() => {
+          this.frame = undefined
+          this.flush()
+        })
       })
       return
     }
+    this.cancelFrame()
     this.flush()
   }
 
+  private cancelFrame(): void {
+    if (this.frame !== undefined && typeof cancelAnimationFrame === 'function') {
+      cancelAnimationFrame(this.frame)
+    }
+    this.frame = undefined
+  }
+
   private flush(): void {
     if (this.assembler.flush()) this.snapshot.set(this.currentSnapshot())
   }
diff --git a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
index ba52e36ba6..de43362fe2 100644
--- a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
@@ -1,6 +1,6 @@
 import { Context } from '@deepseek-ai/cordis'
-import { describe, expect, it, vi } from 'vitest'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import {
   createScope, MutableSessionEventSource,
@@ -17,6 +17,8 @@ import type {
 
 const SESSION_ID = 'resident' as SessionId
 
+afterEach(() => { vi.unstubAllGlobals() })
+
 function sessionSnapshot(): SessionSnapshot {
   return {
     sessionId: SESSION_ID,
@@ -136,6 +138,99 @@ async function bootRegistries(): Promise<{
 }
 
 describe('Conversation registries', () => {
+  it('publishes frame-paced updates after two animation frames and lets immediate updates preempt them', async () => {
+    let nextFrame = 0
+    const frames = new Map<number, FrameRequestCallback>()
+    const requestFrame = vi.fn((callback: FrameRequestCallback) => {
+      nextFrame++
+      frames.set(nextFrame, callback)
+      return nextFrame
+    })
+    const cancelFrame = vi.fn((frame: number) => { frames.delete(frame) })
+    vi.stubGlobal('requestAnimationFrame', requestFrame)
+    vi.stubGlobal('cancelAnimationFrame', cancelFrame)
+    const { uiConversation, binding, events, views } = await bootRegistries()
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'frame-probe',
+      target: 'chat',
+      match: event => event.type === 'turn/start'
+        ? { id: String(event.data.turn), role: 'start' }
+        : event.type === 'assistant/chunk' || event.type === 'assistant/message'
+          ? { id: String(event.data.turn), role: 'update' }
+          : null,
+      start: () => 0,
+      update: context => context.state + 1,
+      publication: match => match.event.type === 'assistant/chunk' ? 'animation-frame' : 'immediate',
+      buildViewNode: context => ({
+        key: context.key,
+        kind: 'frame-probe',
+        id: context.id,
+        target: 'chat',
+        data: context.state,
+      }),
+    }
+    events.register(definition)
+    views.register(viewDefinition('chat'))
+    await Promise.resolve()
+    const conversation = uiConversation.binding(binding)
+    conversation.activate('chat')
+    const listener = vi.fn()
+    const unsubscribe = conversation.snapshot.subscribe(listener)
+    const source = binding.eventSource as MutableSessionEventSource
+    const append = (event: SessionEvent): void => {
+      source.append({ type: 'event', event })
+    }
+
+    append({ seq: 1, time: 1, type: 'turn/start', data: { turn: 1 } })
+    listener.mockClear()
+    append({
+      seq: 2,
+      time: 2,
+      type: 'assistant/chunk',
+      data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'a' } },
+    })
+    append({
+      seq: 3,
+      time: 3,
+      type: 'assistant/chunk',
+      data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'b' } },
+    })
+    expect(requestFrame).toHaveBeenCalledOnce()
+    expect(listener).not.toHaveBeenCalled()
+
+    const first = frames.get(1)
+    if (first === undefined) throw new Error('first animation frame was not scheduled')
+    frames.delete(1)
+    first(0)
+    expect(requestFrame).toHaveBeenCalledTimes(2)
+    expect(listener).not.toHaveBeenCalled()
+
+    const second = frames.get(2)
+    if (second === undefined) throw new Error('second animation frame was not scheduled')
+    frames.delete(2)
+    second(16)
+    expect(listener).toHaveBeenCalledOnce()
+
+    append({
+      seq: 4,
+      time: 4,
+      type: 'assistant/chunk',
+      data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'c' } },
+    })
+    append({
+      seq: 5,
+      time: 5,
+      type: 'assistant/message',
+      data: { turn: 1, step: 1, message: { id: 'a1', role: 'assistant', content: [] } },
+    } as SessionEvent)
+    expect(cancelFrame).toHaveBeenCalledWith(3)
+    expect(frames).toHaveLength(0)
+    expect(listener).toHaveBeenCalledTimes(2)
+
+    unsubscribe()
+    await binding.ctx.fiber.dispose()
+  })
+
   it('rejects duplicate Event Definitions and disposes an ordinary registration once', async () => {
     const { events } = await bootRegistries()
     const definition = eventDefinition('message')

From 2ab37e9558859ab1ba442dcebe2bd3ed4121fff3 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 15:58:27 +0800
Subject: [PATCH 12/37] perf(trajectory): page resident history before
 rendering

---
 ...ry-conversation-context-assembly.i18n.yaml |   4 +-
 ...rajectory-conversation-context-assembly.md |   6 +-
 ...ectory-conversation-context-assembly.zh.md |   6 +-
 .../tests/trajectory-virtualization.e2e.ts    |   7 +-
 .../client/ui-trajectory/README.i18n.yaml     |   4 +-
 packages/client/ui-trajectory/README.md       |   4 +-
 packages/client/ui-trajectory/README.zh.md    |   4 +-
 .../src/client/TrajectoryView.tsx             |  64 ++++++--
 .../ui-trajectory/tests/views.client.spec.tsx | 152 +++++++++++++++++-
 9 files changed, 226 insertions(+), 25 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.i18n.yaml
index 61a386bc8f..0c56c30caf 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.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 .agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md
-2026-08-11-trajectory-conversation-context-assembly.md: c041d7a8ba9f39f74cf55f8a35513724eaeb4f54
-2026-08-11-trajectory-conversation-context-assembly.zh.md: 06e7b801b67b789ddffe991916aceee86cc903f8
+2026-08-11-trajectory-conversation-context-assembly.md: 6a8c41598533d1b277548b04e003c9eaa956f0b0
+2026-08-11-trajectory-conversation-context-assembly.zh.md: 1f5b5eb7ab086adf9f6c91f670ac99ad2c897a1b
diff --git a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md
index c041d7a8ba..6a8c415985 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md
@@ -74,7 +74,7 @@ The Context migration and the following presentation optimizations solve differe
 | Following Assistant lookup | One reverse pass records the next Assistant for every input position | The former repeated forward lookup falls from worst-case `O(C²)` to `O(C)` |
 | Group duration | Fixed decimal grouping replaces `toLocaleString('en-US')` for the invariant English numeric shape | Complexity remains linear in Groups, but the Intl formatter leaves the repeated render path |
 
-Display memoization and search indexing stay separate. Search must include off-screen records and may lag live changes by the throttle interval; Table rendering must update the visible changed record immediately and must not inherit the index's commit cadence.
+Display memoization and search indexing stay separate. Search includes off-screen records in the current React-visible history window and may lag live changes by the throttle interval; Table rendering must update the visible changed record immediately and must not inherit the index's commit cadence.
 
 ## Alternatives considered
 
@@ -88,7 +88,7 @@ Display memoization and search indexing stay separate. Search must include off-s
 
 **Replace the Trajectory stages with generic Conversation Nodes.** Rejected: stages organize requests, timing, schemas, and table layout for one view. Making them engine contracts would constrain a future plain Session-log view and return view-specific composition to Client Runtime.
 
-**Share one Markdown cache between display and search.** Rejected: display is immediate and viewport-bound, while search covers the complete loaded record set and intentionally batches updates. A shared cache would couple correctness and scheduling across unrelated consumers.
+**Share one Markdown cache between display and search.** Rejected: display is immediate and viewport-bound, while search covers the complete React-visible record set and intentionally batches updates. A shared cache would couple correctness and scheduling across unrelated consumers.
 
 ## Verification
 
@@ -100,7 +100,7 @@ Trajectory Definition and Builder tests pin Assistant streaming and interruption
 
 Trajectory business assembly now scales with the changed page or keyed Context instead of restarting from the complete raw Event window. Target-owned Definitions can evolve independently from Chat while retaining one Session window and one set of lifecycle rules. Steering becomes a first-class Trajectory record at its actual Step position without adding steering-specific state to Session.
 
-After first activation, the retained stage-oriented Builder still performs work proportional to materialized Trajectory contributions and may sort on publication. Before activation, the target retains Context State and one target index but no Builder, materialized Node, or snapshot. The search index still performs a light linear signature pass when its input layout changes.
+After first activation, the retained stage-oriented Builder still performs work proportional to materialized Trajectory contributions and may sort on publication. Before activation, the target retains Context State and one target index but no Builder, materialized Node, or snapshot. Each Trajectory view mount anchors React layout, timeline, and search data to 50 target Nodes at the current tail; live appends extend that window, and the existing earlier-history action extends its prefix before it requests another Session page. Request numbering and cumulative usage remain derived from the complete resident snapshot. The search index still performs a light linear signature pass when its input layout changes.
 
 Definition authors must provide stable protocol identities. Old Events without a required ID can disappear from the affected Trajectory business view, which is preferable to joining unrelated records or failing history load; producers that require faithful display must log the identity.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.zh.md
index 06e7b801b6..1f5b5eb7ab 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.zh.md
@@ -74,7 +74,7 @@ Context 迁移与下列表现层优化解决的是不同成本。这些优化保
 | 后继 Assistant 查找 | 一次反向遍历为每个输入位置记录后续 Assistant | 原先重复向前查找的最坏复杂度从 `O(C²)` 降为 `O(C)` |
 | Group duration | 以固定十进制分组替代固定英文数字形态下的 `toLocaleString('en-US')` | 复杂度仍与 Group 数线性相关，但重复 render 路径不再调用 Intl formatter |
 
-展示 memo 与搜索索引彼此独立。搜索必须覆盖屏幕外 record，并允许实时变化延迟一个 throttle 周期；Table 必须立即更新发生变化的可见 record，不能继承索引的提交节奏。
+展示 memo 与搜索索引彼此独立。搜索覆盖当前 React 可见历史窗口中的屏幕外 record，并允许实时变化延迟一个 throttle 周期；Table 必须立即更新发生变化的可见 record，不能继承索引的提交节奏。
 
 ## 考虑过的替代方案
 
@@ -88,7 +88,7 @@ Context 迁移与下列表现层优化解决的是不同成本。这些优化保
 
 **用通用 Conversation Node 替换 Trajectory stage。** 不予采纳：stage 为单一视图组织 Request、计时、schema 和表格 layout。把它变成引擎约定会限制未来的朴素 Session-log 视图，并把视图专属组合重新放回 Client Runtime。
 
-**在展示与搜索之间共享一套 Markdown cache。** 不予采纳：展示要求立即更新且受 viewport 约束，搜索则覆盖全部已加载 record，并有意批量提交更新。共享 cache 会把两个无关消费方的正确性与调度节奏耦合起来。
+**在展示与搜索之间共享一套 Markdown cache。** 不予采纳：展示要求立即更新且受 viewport 约束，搜索则覆盖全部 React 可见 record，并有意批量提交更新。共享 cache 会把两个无关消费方的正确性与调度节奏耦合起来。
 
 ## 验证
 
@@ -100,7 +100,7 @@ Trajectory Definition 与 Builder 测试固定 Assistant streaming 与 interrupt
 
 Trajectory 业务组装的成本随变化页面或 keyed Context 增长，不再从完整原始 Event 窗口重新开始。target 自有 Definition 可以独立于 Chat 演进，同时继续共享一份 Session 窗口和一套生命周期规则。steering 会在实际所属 Step 位置成为一等 Trajectory record，不需要向 Session 增加 steering 专属状态。
 
-首次激活后，保留的 stage-oriented Builder 仍会执行与已物化 Trajectory contribution 数量成正比的工作，并可能在发布时排序。激活前，target 保留 Context State 和一个 target 索引，但不保留 Builder、已物化 Node 或 snapshot。输入 layout 变化时，搜索索引仍会执行一次轻量线性签名检查。
+首次激活后，保留的 stage-oriented Builder 仍会执行与已物化 Trajectory contribution 数量成正比的工作，并可能在发布时排序。激活前，target 保留 Context State 和一个 target 索引，但不保留 Builder、已物化 Node 或 snapshot。每次挂载 Trajectory 视图时，React layout、timeline 与搜索数据都锚定在当前尾部的 50 个 target Node；实时 append 会扩展该窗口，现有更早历史操作则先扩展其前缀，再请求下一个 Session 页面。请求编号与累计用量仍从完整的驻留 snapshot 派生。输入 layout 变化时，搜索索引仍会执行一次轻量线性签名检查。
 
 Definition 作者必须提供稳定的协议标识。缺少必要 ID 的旧 Event 可能不会出现在受影响的 Trajectory 业务视图中；与合并无关记录或让历史加载失败相比，这是更安全的退化方式。要求完整展示的生产方必须记录该标识。
 
diff --git a/apps/web/tests/trajectory-virtualization.e2e.ts b/apps/web/tests/trajectory-virtualization.e2e.ts
index 062fcc19c8..9f17854c06 100644
--- a/apps/web/tests/trajectory-virtualization.e2e.ts
+++ b/apps/web/tests/trajectory-virtualization.e2e.ts
@@ -255,6 +255,11 @@ describe('web e2e: Trajectory virtualization over tail-paged history', () => {
       await compareOrRefreshGolden(LOAD_MORE_EXPECTED, loadMoreSnapshot, MODE)
       // Avoid Playwright scrolling the offscreen first row into the automatic-load threshold.
       await loadMore.evaluate((button: HTMLButtonElement) => { button.click() })
+      await expect.poll(() => logicalRows(page), { timeout: 15_000 }).toBeGreaterThan(initialRows)
+      const residentRows = await logicalRows(page)
+      expect(held).toBe(false)
+      await expect.poll(() => loadMore.isDisabled(), { timeout: 15_000 }).toBe(false)
+      await loadMore.evaluate((button: HTMLButtonElement) => { button.click() })
       await expect.poll(() => held, { timeout: 15_000 }).toBe(true)
       await expect.poll(async () => ({
         disabled: await loadMore.isDisabled(),
@@ -274,7 +279,7 @@ describe('web e2e: Trajectory virtualization over tail-paged history', () => {
         .toBe('true')
 
       releaseHistory()
-      await expect.poll(() => logicalRows(page), { timeout: 60_000 }).toBeGreaterThan(initialRows)
+      await expect.poll(() => logicalRows(page), { timeout: 60_000 }).toBeGreaterThan(residentRows)
       await nextPaint(page)
       await expect.poll(async () => {
         const top = await rowTop(page, anchor.key)
diff --git a/packages/client/ui-trajectory/README.i18n.yaml b/packages/client/ui-trajectory/README.i18n.yaml
index a1d5f1c686..edc665438f 100644
--- a/packages/client/ui-trajectory/README.i18n.yaml
+++ b/packages/client/ui-trajectory/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/client/ui-trajectory/README.md
-README.md: 02daa3a7e4440b4ea4901f98139044bbda68827f
-README.zh.md: 0a1aa49a94d68cc1ab56e02831e4cbf06be5fdb1
+README.md: d947787c123fca77dc7978456f4cfdc4e99951bf
+README.zh.md: 3b281c6c1e90108d66f050e07a3b08208ed8c802
diff --git a/packages/client/ui-trajectory/README.md b/packages/client/ui-trajectory/README.md
index 02daa3a7e4..d947787c12 100644
--- a/packages/client/ui-trajectory/README.md
+++ b/packages/client/ui-trajectory/README.md
@@ -29,7 +29,7 @@ Open the Trajectory tab in the conversation's view ring to inspect agent activit
 
 ### Inspecting records
 
-Selection, timeline navigation, folding, search, and Request totals cover the loaded window. Selecting a record opens a local inspector for token usage, duration, Input, Output, Timing, and durable images. Image URLs use the Conversation-owned per-session cache, so Chat and Trajectory share one authorized read per attachment. A record without text labels its row with the image count. A standalone compaction request appears chronologically in its own `Between turns` section, while a numbered compaction remains inside its owning turn.
+Selection, timeline navigation, folding, and search cover the React-visible window. Request numbers and cumulative usage cover the complete resident snapshot. Selecting a record opens a local inspector for token usage, duration, Input, Output, Timing, and durable images. Image URLs use the Conversation-owned per-session cache, so Chat and Trajectory share one authorized read per attachment. A record without text labels its row with the image count. A standalone compaction request appears chronologically in its own `Between turns` section, while a numbered compaction remains inside its owning turn.
 
 ### The timing overview
 
@@ -47,7 +47,7 @@ The view is a pure projection: Trajectory-owned Definitions assemble business re
 
 ### Virtual rows
 
-Long ledgers mount only the visible row window plus a small overscan; request-only separators share the next measurable virtual item, while semantic row keys and ARIA indexes survive prepends. Content-only stream frames preserve virtual row keys and heights, reuse measurements, and do not issue repeated tail-scroll writes. Completed replies retain assembled blocks, timing, and usage in Trajectory target State, while the shared Session window keeps the raw Events.
+Long ledgers initially derive React data from 50 target Nodes ending at the mount-time tail. Later Nodes extend that anchored window without evicting its prefix, and the existing load control reveals earlier resident Nodes before requesting another Session page. Virtualization mounts only the visible row window plus a small overscan; request-only separators share the next measurable virtual item, while semantic row keys and ARIA indexes survive prepends. Content-only stream frames preserve virtual row keys and heights, reuse measurements, and do not issue repeated tail-scroll writes. Completed replies retain assembled blocks, timing, and usage in Trajectory target State, while the shared Session window keeps the raw Events.
 
 ### Layout
 
diff --git a/packages/client/ui-trajectory/README.zh.md b/packages/client/ui-trajectory/README.zh.md
index 0a1aa49a94..3b281c6c1e 100644
--- a/packages/client/ui-trajectory/README.zh.md
+++ b/packages/client/ui-trajectory/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 检查记录
 
-选择、时间线导航、折叠、搜索与请求汇总只覆盖已加载的窗口。选择记录会打开局部检查器，查看 token 用量、耗时、输入、输出、计时与持久图片。图片 URL 使用 Conversation 拥有的逐会话缓存，因此 Chat 与 Trajectory 对每个附件共享一次已授权读取。没有文本的记录会用图片数量标记其行。独立运行的压缩请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。
+选择、时间线导航、折叠与搜索只覆盖 React 可见窗口。请求编号与累计用量覆盖完整的驻留 snapshot。选择记录会打开局部检查器，查看 token 用量、耗时、输入、输出、计时与持久图片。图片 URL 使用 Conversation 拥有的逐会话缓存，因此 Chat 与 Trajectory 对每个附件共享一次已授权读取。没有文本的记录会用图片数量标记其行。独立运行的压缩请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。
 
 ### 时间概览
 
@@ -47,7 +47,7 @@ kind: "package-reference"
 
 ### 虚拟行
 
-长记录表只挂载可见行窗口加少量缓冲；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键与 ARIA 索引在向前补页后保持不变。仅含内容更新的流式帧会保持虚拟行的键与高度、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复会在 Trajectory target State 中保留组装后的 blocks、计时与用量，共享 Session 窗口则保留原始 Event。
+长记录表最初只从挂载时尾部结束的 50 个 target Node 派生 React 数据。后续 Node 会扩展这个固定起点的窗口而不会逐出其前缀；现有加载控件会先显露更早的驻留 Node，再请求下一个 Session 页面。虚拟化只挂载可见行窗口加少量缓冲；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键与 ARIA 索引在向前补页后保持不变。仅含内容更新的流式帧会保持虚拟行的键与高度、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复会在 Trajectory target State 中保留组装后的 blocks、计时与用量，共享 Session 窗口则保留原始 Event。
 
 ### 布局
 
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
index 2ac0d5ddf1..f950084244 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
+++ b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type {
   AssistantBlock, AssistantMessageNode, ConvViewProps, MessageImageLoader, RenderMessageImages,
+  ToolCallBlock,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { InjectFace, PropsLocale, PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
@@ -30,6 +31,14 @@ import css from './views.module.css'
 const EMPTY_TURN_IDS: ReadonlySet<number> = new Set()
 const EMPTY_RECORD_IDS: ReadonlySet<string> = new Set()
 const SEARCH_INDEX_THROTTLE_MS = 3_000
+const HISTORY_PAGE_NODES = 50
+
+function containsCall(calls: readonly ToolCallBlock[], callId: string): boolean {
+  for (const call of calls) {
+    if (call.callId === callId || containsCall(call.subCalls, callId)) return true
+  }
+  return false
+}
 
 function lastCellIndex(turns: readonly TrajectoryTurnModel[]): number {
   let last = 0
@@ -146,10 +155,35 @@ export function TrajectoryView({
   const [timelineRecordFocus, setTimelineRecordFocus] = useState<{
     readonly index: number
   } | null>(null)
-  const inspection = useTrajectory(snapshot => snapshot)
+  const completeInspection = useTrajectory(snapshot => snapshot)
+  const latestNodeSeq = completeInspection.eventNodes.at(-1)?.seq
+  const [historyTailSeq, setHistoryTailSeq] = useState(latestNodeSeq)
+  const [historyNodeLimit, setHistoryNodeLimit] = useState(HISTORY_PAGE_NODES)
+  const fixedTailSeq = historyTailSeq ?? latestNodeSeq
+  const historyEndIndex = fixedTailSeq === undefined
+    ? 0
+    : completeInspection.eventNodes.findLastIndex(node => node.seq <= fixedTailSeq) + 1
+  const historyStartIndex = Math.max(0, historyEndIndex - historyNodeLimit)
+  useEffect(() => {
+    if (historyTailSeq === undefined && latestNodeSeq !== undefined) setHistoryTailSeq(latestNodeSeq)
+  }, [historyTailSeq, latestNodeSeq])
+  const inspection = useMemo<TrajectorySnapshot>(() => {
+    if (historyStartIndex === 0) return completeInspection
+    const eventNodes = completeInspection.eventNodes.slice(historyStartIndex)
+    const firstSeq = eventNodes[0]?.seq ?? 0
+    return {
+      ...completeInspection,
+      eventNodes,
+      requests: completeInspection.requests.filter(request =>
+        request.startSeq >= firstSeq || (request.resultSeq ?? -1) >= firstSeq),
+    }
+  }, [completeInspection, historyStartIndex])
   const historyLoading = useSession(snapshot => snapshot.openState === 'loading')
   const olderHistoryLoading = useSession(snapshot => snapshot.loadingOlder)
-  const hasOlderHistory = useSession(snapshot => snapshot.hasMore)
+  const sessionHasOlderHistory = useSession(snapshot => snapshot.hasMore)
+  const hasResidentOlderHistory = historyStartIndex > 0
+  const hasOlderHistory = hasResidentOlderHistory
+    || sessionHasOlderHistory
   const nodes = inspection.eventNodes
   const eventLocations = inspection.eventLocations
   const historyBaseSeq = nodes[0]?.seq ?? 0
@@ -158,14 +192,24 @@ export function TrajectoryView({
   const requests = inspection.requests
   const callSchemas = inspection.callSchemas
   const inspectCallId = viewRequest?.view === 'trajectory' ? viewRequest.focus : null
+  const inspectNodeIndex = useMemo(() => inspectCallId === null
+    ? -1
+    : completeInspection.eventNodes.findIndex(node => node.kind === 'assistant'
+      ? node.blocks.some(block => block.kind === 'tool-call' && block.callId === inspectCallId)
+      : node.kind === 'tool-result' && containsCall([node], inspectCallId)),
+  [completeInspection.eventNodes, inspectCallId])
+  useEffect(() => {
+    if (inspectNodeIndex < 0 || inspectNodeIndex >= historyStartIndex) return
+    setHistoryNodeLimit(limit => limit + historyStartIndex - inspectNodeIndex)
+  }, [historyStartIndex, inspectNodeIndex])
   const requestNumbers = useMemo<readonly TrajectoryRequestNumber[]>(() => {
     const assistantsByStep = new Map<string, AssistantMessageNode>()
-    for (const node of nodes) {
+    for (const node of completeInspection.eventNodes) {
       if (node.kind !== 'assistant' || node.step <= 0) continue
       assistantsByStep.set(`${node.turn}\u0000${node.step}`, node)
     }
     const requestsByStep = new Map(
-      requests
+      completeInspection.requests
         .filter(request => request.purpose === 'assistant')
         .map(request => [
           `${request.turn}\u0000${request.step}`,
@@ -173,7 +217,7 @@ export function TrajectoryView({
         ]),
     )
     const orderedRequests = [
-      ...requests.map(request => ({
+      ...completeInspection.requests.map(request => ({
         seq: request.startSeq,
         request,
         node: request.purpose === 'assistant'
@@ -257,7 +301,7 @@ export function TrajectoryView({
 
     return numbered
   }, [
-    nodes, requests, t,
+    completeInspection.eventNodes, completeInspection.requests, t,
   ])
   const partialTurn = partial?.turn ?? null
   const partialStep = partial?.step ?? null
@@ -448,9 +492,11 @@ export function TrajectoryView({
     })
   }
 
-  const loadEarlierHistory = useCallback(() => {
-    return loadOlder()
-  }, [loadOlder])
+  const loadEarlierHistory = useCallback(async () => {
+    if (!hasResidentOlderHistory && !await loadOlder()) return false
+    setHistoryNodeLimit(limit => limit + HISTORY_PAGE_NODES)
+    return true
+  }, [hasResidentOlderHistory, loadOlder])
 
   return (
     <div className={css.root} data-conversation-composer-overlay="">
diff --git a/packages/client/ui-trajectory/tests/views.client.spec.tsx b/packages/client/ui-trajectory/tests/views.client.spec.tsx
index 463c84e07e..967a39bbb5 100644
--- a/packages/client/ui-trajectory/tests/views.client.spec.tsx
+++ b/packages/client/ui-trajectory/tests/views.client.spec.tsx
@@ -8,7 +8,7 @@
  * Timeline projection and inclusive focus edge cases ride along.
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { createElement, type ComponentProps, type FC, type ReactNode } from 'react'
 import { bindSnapshotSelector, SlotTestRuntime, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
@@ -66,6 +66,8 @@ const runtimes: SlotTestRuntime[] = []
 
 afterEach(async () => {
   cleanup()
+  vi.restoreAllMocks()
+  Reflect.deleteProperty(HTMLElement.prototype, 'scrollTo')
   for (const runtime of runtimes.splice(0)) await runtime.dispose()
 })
 // The Conversation store persists under its declared key; clear so one case's active
@@ -1264,6 +1266,154 @@ describe('timeline projection', () => {
 })
 
 describe('TrajectoryView state', () => {
+  it('reveals resident history one bounded page at a time', async () => {
+    const nodes: LegacyConversationSlice['nodes'] = Array.from({ length: 5_000 }, (_, index) => ({
+      kind: 'user' as const,
+      seq: index + 1,
+      time: index + 1,
+      content: [{ type: 'text' as const, text: `prompt ${String(index + 1)}` }],
+      source: null,
+    }))
+    const trajectory = createSnapshotStore(historySnapshot([]))
+    const loadOlder = vi.fn(() => Promise.resolve(false))
+    render(
+      <TrajectoryView
+        {...standaloneProps([])}
+        {...standaloneHistory(historySnapshot(nodes))}
+        {...standaloneDuration()}
+        useTrajectory={bindSnapshotSelector(trajectory)}
+        loadOlder={loadOlder}
+      />,
+    )
+
+    act(() => { trajectory.set(historySnapshot(nodes)) })
+    expect(screen.getByRole('table').getAttribute('aria-rowcount')).toBe('51')
+    fireEvent.click(screen.getAllByRole('button', { name: '加载更早的历史' }).at(-1)!)
+    expect(screen.getByRole('table').getAttribute('aria-rowcount')).toBe('101')
+    expect(loadOlder).not.toHaveBeenCalled()
+
+    act(() => { trajectory.set(historySnapshot([...nodes, {
+      kind: 'user', seq: 5_001, time: 5_001,
+      content: [{ type: 'text', text: 'appended prompt' }], source: null,
+    }])) })
+    expect(screen.getByRole('table').getAttribute('aria-rowcount')).toBe('102')
+  })
+
+  it('keeps resident request numbering and cumulative usage outside the layout page', async () => {
+    vi.spyOn(HTMLElement.prototype, 'offsetHeight', 'get').mockReturnValue(600)
+    Object.defineProperty(HTMLElement.prototype, 'scrollTo', {
+      configurable: true,
+      value: vi.fn(),
+    })
+    const visibleNodes: LegacyConversationSlice['nodes'] = Array.from(
+      { length: 10 },
+      (_, index) => ({
+        kind: 'assistant' as const,
+        seq: index * 2 + 44,
+        time: index * 2 + 44,
+        turn: index + 2,
+        step: 1,
+        blocks: [{ kind: 'text' as const, text: `visible response ${String(index + 1)}` }],
+      }),
+    )
+    const nodes: LegacyConversationSlice['nodes'] = [{
+      kind: 'assistant', seq: 2, time: 2, turn: 1, step: 1,
+      blocks: [{ kind: 'tool-call', callId: 'boundary-call', name: 'bash', argsRaw: '{}' }],
+    }, {
+      kind: 'tool-result', seq: 3, time: 3, callId: 'boundary-call',
+      call: { name: 'bash', argsRaw: '{}' }, callTime: 2,
+      content: [], isError: false, subCalls: [],
+    }, ...Array.from({ length: 39 }, (_, index) => ({
+      kind: 'compaction' as const,
+      seq: index + 4,
+      time: index + 4,
+      summary: null,
+      summaryEventSeq: null,
+      shadowedItemCount: null,
+      shadowedTokenCount: null,
+    })), ...visibleNodes]
+    const requests: readonly RequestView[] = [{
+      purpose: 'assistant', startSeq: 1, resultSeq: 2, startedAt: 1, completedAt: 2,
+      status: 'complete', turn: 1, step: 1, usage: { inputTokens: 1 },
+    }, ...visibleNodes.map((node, index) => ({
+      purpose: 'assistant' as const,
+      startSeq: node.seq - 1,
+      resultSeq: node.seq,
+      startedAt: node.seq - 1,
+      completedAt: node.seq,
+      status: 'complete' as const,
+      turn: index + 2,
+      step: 1,
+      usage: { inputTokens: 1 },
+    }))]
+    render(
+      <TrajectoryView
+        {...standaloneProps([])}
+        {...standaloneHistory(historySnapshot(nodes, { requests }))}
+        {...standaloneDuration()}
+      />,
+    )
+
+    await waitFor(() => { expect(screen.getByRole('button', { name: '请求 #1' })).toBeTruthy() })
+    await waitFor(() => { expect(screen.getByRole('button', { name: '请求 #11' })).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: '请求 #11' }))
+    fireEvent.click(screen.getByRole('tab', { name: '用量' }))
+    expect(screen.getByText('会话累计').closest('section')?.textContent).toContain('11 tok')
+  })
+
+  it.each([
+    ['root', {
+      kind: 'assistant' as const,
+      seq: 3,
+      time: 3,
+      turn: 1,
+      step: 1,
+      blocks: [{ kind: 'tool-call' as const, callId: 'hidden-root', name: 'bash', argsRaw: '{}' }],
+    }, 'hidden-root'],
+    ['nested', {
+      kind: 'tool-result' as const,
+      seq: 3,
+      time: 3,
+      callId: 'hidden-root',
+      call: { name: 'run_code', argsRaw: '{}' },
+      callTime: 2,
+      content: [],
+      isError: false,
+      subCalls: [{
+        callId: 'hidden-child', parentCallId: 'hidden-root', name: 'bash', argsRaw: '{}',
+        turn: 1, step: 1, time: 3, subCalls: [],
+      }],
+    }, 'hidden-child'],
+  ])('reveals a hidden resident %s call for cross-view inspection', (_kind, target, focus) => {
+    const nodes: LegacyConversationSlice['nodes'] = [
+      { kind: 'user', seq: 1, time: 1, content: [], source: null },
+      {
+        kind: 'tool-result', seq: 2, time: 2, callId: 'unrelated', call: null, callTime: null,
+        content: [], isError: false, subCalls: [],
+      },
+      target,
+      ...Array.from({ length: 50 }, (_, index) => ({
+        kind: 'user' as const,
+        seq: index + 4,
+        time: index + 4,
+        content: [{ type: 'text' as const, text: `later ${String(index + 1)}` }],
+        source: null,
+      })),
+    ]
+    const completeViewRequest = vi.fn()
+    render(
+      <TrajectoryView
+        {...standaloneProps([])}
+        {...standaloneHistory(historySnapshot(nodes))}
+        {...standaloneDuration()}
+        viewRequest={{ view: 'trajectory', focus }}
+        completeViewRequest={completeViewRequest}
+      />,
+    )
+
+    expect(completeViewRequest).toHaveBeenCalledOnce()
+  })
+
   it('persists the duration preference through the runtime snapshot-store seam', () => {
     const firstDuration = createTrajectoryDurationStore()
     const commonProps = {

From 6401a64e20040f5cb9a56cce723d09af51938c03 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 16:41:17 +0800
Subject: [PATCH 13/37] test(web): cover optimized streaming paths

---
 apps/web/tests/lifecycle-chrome.e2e.ts             | 14 ++++++++++----
 .../tests/produced-files.client.spec.tsx           |  3 +++
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 428e3c195a..56f47f10c9 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -188,10 +188,16 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
         await input.press('Enter')
         if (MODE !== 'record') {
           const liveTail = page.locator('[data-variant="think"][data-state="running"] [data-follow-end]')
-          await expect.poll(async () => await liveTail.evaluate(element => (
-            element.scrollWidth > element.clientWidth
-              && element.scrollLeft >= element.scrollWidth - element.clientWidth - 1
-          )), { timeout: 10_000, interval: 10 }).toBe(true)
+          await expect.poll(async () => {
+            if (await liveTail.count() !== 1) return false
+            return await liveTail.evaluate((element) => {
+              const text = element.firstElementChild
+              if (!(text instanceof HTMLElement)) return false
+              const viewport = element.getBoundingClientRect()
+              const content = text.getBoundingClientRect()
+              return content.width > viewport.width && Math.abs(content.right - viewport.right) <= 1
+            })
+          }, { timeout: 10_000, interval: 10 }).toBe(true)
         }
         return await settled
       } finally {
diff --git a/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
index 5e78ccba63..62ea12276d 100644
--- a/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
@@ -382,6 +382,9 @@ describe('produced-file Turn data', () => {
     value.append(call(4, 'second', 'edit', {
       file_path: 'second.txt', old_string: 'before', new_string: 'after',
     }))
+    value.flush()
+    expect(deliverablesOf(value)).toBe(first)
+
     value.append(result(5, 'second'))
     value.flush()
     expect(producedForClosing(deliverablesOf(value))).toEqual(['first.txt', 'second.txt'])

From a731536eccfe924fc5b6784cca7e4f3657b41340 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:05:15 +0800
Subject: [PATCH 14/37] perf: ChatNodeSeat use seperated source

---
 .../ui-chat/src/client/chat/ChatNodeSeat.tsx  |  9 +--
 .../ui-chat/src/client/chat/ChatView.tsx      |  1 +
 .../ui-chat/src/client/contract/snapshot.ts   | 16 +++++
 .../chat-snapshot-builder.ts                  | 57 +++++++++++++++--
 packages/client/ui-chat/src/client/index.ts   |  2 +-
 .../ui-chat/tests/chat-apply.client.spec.tsx  |  7 ++-
 .../tests/chat-node-source.client.spec.ts     | 51 ++++++++++++++++
 .../tests/chat-snapshot-fixture.client.ts     | 61 ++++++++++++++++---
 .../tests/tool-details-render.client.tsx      |  1 +
 .../tests/plan-review-panel.client.spec.tsx   |  3 +-
 .../user-questions-composer.client.spec.tsx   |  3 +-
 11 files changed, 190 insertions(+), 21 deletions(-)
 create mode 100644 packages/client/ui-chat/tests/chat-node-source.client.spec.ts

diff --git a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
index 00eb9fd70d..cfa4b52f13 100644
--- a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
@@ -1,8 +1,8 @@
-import { memo, useCallback, useMemo } from 'react'
+import { memo, useCallback, useMemo, useSyncExternalStore } from 'react'
 import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts'
 import type { ChatNode } from '../contract/chat-nodes.ts'
-import type { ChatNodeStore } from '../contract/snapshot.ts'
+import type { ChatNodeSource, ChatNodeStore } from '../contract/snapshot.ts'
 import {
   decodeTurnProcess, TURN_PROCESS_INDEPENDENT_KINDS, turnProcessGeneration,
   type TurnProcessSpec,
@@ -13,6 +13,7 @@ import css from './ChatView.module.css'
 
 interface ChatNodeSeatProps extends ChatNodeOwnerProps {
   readonly nodeKey: string
+  readonly nodeSource: ChatNodeSource
   readonly historyIncomplete: boolean
   readonly compactTranscript: boolean
   readonly useChat: ChatViewSlotProps['useChat']
@@ -78,11 +79,11 @@ function turnProcessLayout(
 
 /** Subscribe, apply Turn-process visibility, and dispatch one stable Context key. */
 export const ChatNodeSeat = memo(function ChatNodeSeat({
-  nodeKey, historyIncomplete, compactTranscript,
+  nodeKey, nodeSource, historyIncomplete, compactTranscript,
   selectedCallId, cwd, openFile, inspectCall, forkAt,
   renderMessageImages, fileMentions, useChat, useStore, actions, renderSlot, t,
 }: ChatNodeSeatProps) {
-  const node = useChat(snapshot => snapshot.nodes.get(nodeKey))
+  const node = useSyncExternalStore(nodeSource.subscribe, nodeSource.getSnapshot)
   const processSignature = useChat((snapshot) => {
     const current = snapshot.nodes.get(nodeKey)
     const location = current?.location
diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index 75ff66b500..259687ee00 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -746,6 +746,7 @@ export function ChatView({
             <ChatNodeSeat
               key={nodeKey}
               nodeKey={nodeKey}
+              nodeSource={nodeStore.source(nodeKey)}
               historyIncomplete={hasMore}
               compactTranscript={compactTranscript}
               useChat={useChat}
diff --git a/packages/client/ui-chat/src/client/contract/snapshot.ts b/packages/client/ui-chat/src/client/contract/snapshot.ts
index 4a3deb7410..ea46ee4382 100644
--- a/packages/client/ui-chat/src/client/contract/snapshot.ts
+++ b/packages/client/ui-chat/src/client/contract/snapshot.ts
@@ -10,10 +10,21 @@ export type {
   ToolCallBlock, ToolResultNode, TurnErrorNode, TurnMaxTokensNode, UnknownSurfaceNode,
   UserMessageNode,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+/** Per-key observable used by one mounted Chat Node Seat. */
+export interface ChatNodeSource {
+  /** @returns the current Node for this source's stable key. */
+  getSnapshot(): ChatConversationViewNode | undefined
+  /** @param listener - callback for changes to this key. @returns the unsubscribe function. */
+  subscribe(listener: () => void): () => void
+}
+
 /** Stable live per-key reader for Chat nodes. */
 export interface ChatNodeStore {
   /** @param key - stable Conversation Context key. @returns current Node, when visible or hidden. */
   get(key: string): ChatConversationViewNode | undefined
+  /** @param key - stable Conversation Context key. @returns its identity-stable observable source. */
+  source(key: string): ChatNodeSource
   /** @returns all currently materialized Nodes without imposing render order. */
   values(): readonly ChatConversationViewNode[]
 }
@@ -75,12 +86,17 @@ declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
 
 const EMPTY_LIST: readonly never[] = []
 const EMPTY_TIMELINE: ConversationTimelineSnapshot = { turnOrder: EMPTY_LIST, turns: new Map() }
+const EMPTY_NODE_SOURCE: ChatNodeSource = {
+  getSnapshot: () => undefined,
+  subscribe: () => () => {},
+}
 
 /** Empty Chat target used before a view builder is registered. */
 export const EMPTY_CHAT_SNAPSHOT: ChatSnapshot = {
   order: EMPTY_LIST,
   nodes: {
     get: () => undefined,
+    source: () => EMPTY_NODE_SOURCE,
     values: () => EMPTY_LIST,
   },
   locations: {
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
index 74fa8c6ac8..1f1c7bb2a6 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -1,4 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis'
+import { notifySubscribers } from '@deepseek-ai/dsh-client-store'
 import type {
   ConversationLocation, ConversationTimelineSnapshot, ConversationViewBuilder,
   ConversationViewDefinition,
@@ -6,7 +7,7 @@ import type {
 import type { ChatConversationViewNode, ChatNode } from '../contract/chat-nodes.ts'
 import { isRunningTool } from '../contract/chat-nodes.ts'
 import type {
-  ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot, ChatTurnNavigationIndex, ConversationNode,
+  ChatLocationNodeIndex, ChatNodeSource, ChatNodeStore, ChatSnapshot, ChatTurnNavigationIndex, ConversationNode,
   LegacyConversationSlice, PartialAssistant, RunningToolCall, TurnNavigationItem,
 } from '../contract/snapshot.ts'
 import { TURN_PROCESS_INDEPENDENT_KINDS } from '../contract/turn-process.ts'
@@ -22,8 +23,30 @@ function sameReferences<T>(left: readonly T[], right: readonly T[]): boolean {
   return left.length === right.length && left.every((value, index) => value === right[index])
 }
 
+class MutableChatNodeSource implements ChatNodeSource {
+  private readonly listeners = new Set<() => void>()
+
+  constructor(
+    private readonly store: MutableChatNodeStore,
+    private readonly key: string,
+  ) {}
+
+  readonly getSnapshot = (): ChatConversationViewNode | undefined => this.store.get(this.key)
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  publish(): void {
+    notifySubscribers(this.listeners, `[ui-chat] node source ${this.key}`)
+  }
+}
+
 class MutableChatNodeStore implements ChatNodeStore {
   private readonly byKey = new Map<string, ChatConversationViewNode>()
+  private readonly sources = new Map<string, MutableChatNodeSource>()
+  private readonly dirtyKeys = new Set<string>()
   private valuesCache: readonly ChatConversationViewNode[] = EMPTY_LIST
   private valuesDirty = false
 
@@ -31,6 +54,15 @@ class MutableChatNodeStore implements ChatNodeStore {
     return this.byKey.get(key)
   }
 
+  source(key: string): ChatNodeSource {
+    let source = this.sources.get(key)
+    if (source === undefined) {
+      source = new MutableChatNodeSource(this, key)
+      this.sources.set(key, source)
+    }
+    return source
+  }
+
   values(): readonly ChatConversationViewNode[] {
     if (this.valuesDirty) {
       this.valuesCache = [...this.byKey.values()]
@@ -40,8 +72,14 @@ class MutableChatNodeStore implements ChatNodeStore {
   }
 
   replace(nodes: readonly ChatConversationViewNode[]): void {
+    const previous = new Map(this.byKey)
     this.byKey.clear()
-    for (const node of nodes) this.byKey.set(node.key, node)
+    for (const node of nodes) {
+      this.byKey.set(node.key, node)
+      if (previous.get(node.key) !== node) this.dirtyKeys.add(node.key)
+      previous.delete(node.key)
+    }
+    for (const key of previous.keys()) this.dirtyKeys.add(key)
     this.valuesCache = [...this.byKey.values()]
     this.valuesDirty = false
   }
@@ -51,10 +89,17 @@ class MutableChatNodeStore implements ChatNodeStore {
     for (const node of nodes) {
       if (this.byKey.get(node.key) === node) continue
       this.byKey.set(node.key, node)
+      this.dirtyKeys.add(node.key)
       changed = true
     }
     if (changed) this.valuesDirty = true
   }
+
+  publish(): void {
+    const dirty = [...this.dirtyKeys]
+    this.dirtyKeys.clear()
+    for (const key of dirty) this.sources.get(key)?.publish()
+  }
 }
 
 class MutableChatLocationIndex implements ChatLocationNodeIndex {
@@ -652,7 +697,9 @@ export class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversa
     this.locations.rebuild(this.order, this.store)
     this.navigation.rebuild(input.timeline, this.locations, this.store)
     this.timeline = input.timeline
-    return this.snapshot(input.timeline, this.legacy.replace(nodes, input.timeline))
+    const snapshot = this.snapshot(input.timeline, this.legacy.replace(nodes, input.timeline))
+    this.store.publish()
+    return snapshot
   }
 
   apply(input: {
@@ -685,7 +732,9 @@ export class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversa
       this.navigation.touch(turnsOf(contentOnly), this.locations, this.store)
     }
     this.timeline = input.timeline
-    return this.snapshot(input.timeline, this.legacy.apply(upserts, input.timeline))
+    const snapshot = this.snapshot(input.timeline, this.legacy.apply(upserts, input.timeline))
+    this.store.publish()
+    return snapshot
   }
 
   private snapshot(
diff --git a/packages/client/ui-chat/src/client/index.ts b/packages/client/ui-chat/src/client/index.ts
index f45b686af5..da4d8de2e6 100644
--- a/packages/client/ui-chat/src/client/index.ts
+++ b/packages/client/ui-chat/src/client/index.ts
@@ -15,7 +15,7 @@ export type {} from './conversation-nodes/turn-tail.ts'
 
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
-  AssistantTiming, ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot, ChatTurnNavigationIndex,
+  AssistantTiming, ChatLocationNodeIndex, ChatNodeSource, ChatNodeStore, ChatSnapshot, ChatTurnNavigationIndex,
   CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode,
   LegacyConversationSlice, ModelRetryNode, PartialAssistant, RunningToolCall,
   SteeringMessageNode, ToolCallBlock, ToolResultNode, TurnErrorNode, TurnMaxTokensNode,
diff --git a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
index d9c1538190..d040ac0f2c 100644
--- a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
@@ -162,6 +162,7 @@ describe('Chat apply wiring', () => {
     )
     const data = { get: (key: string) => key === 'metric' ? 42 : undefined }
     const turn = { data }
+    const emptySource = { getSnapshot: () => undefined, subscribe: () => () => {} }
 
     snapshot = chatSnapshot({
       nodes: { get: () => ({ location: { kind: 'turn', turn } }), values: () => [] } as never,
@@ -176,7 +177,11 @@ describe('Chat apply wiring', () => {
     })
     expect(useTurnData('metric')).toBeUndefined()
     snapshot = chatSnapshot({
-      nodes: { get: () => undefined, values: () => [] },
+      nodes: {
+        get: () => undefined,
+        source: () => emptySource,
+        values: () => [],
+      },
     })
     expect(useTurnData('metric')).toBeUndefined()
 
diff --git a/packages/client/ui-chat/tests/chat-node-source.client.spec.ts b/packages/client/ui-chat/tests/chat-node-source.client.spec.ts
new file mode 100644
index 0000000000..71f2cecf12
--- /dev/null
+++ b/packages/client/ui-chat/tests/chat-node-source.client.spec.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from 'vitest'
+import type {
+  ChatConversationViewNode, ChatNodeSource,
+} from '@deepseek-ai/dsh-client-ui-chat/client'
+import type { ConversationTimelineSnapshot } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { ChatSnapshotBuilder } from '../src/client/conversation-nodes/chat-snapshot-builder.ts'
+
+const timeline: ConversationTimelineSnapshot = { turnOrder: [], turns: new Map() }
+
+function userNode(index: number, text = `message ${String(index)}`): ChatConversationViewNode {
+  return {
+    key: `user:${String(index)}`,
+    id: String(index),
+    target: 'chat',
+    kind: 'user',
+    anchorSeq: index,
+    location: { kind: 'session' },
+    visibility: 'visible',
+    data: {
+      kind: 'user',
+      messageId: `message-${String(index)}`,
+      seq: index,
+      time: index,
+      content: [{ type: 'text', text }],
+      source: null,
+    },
+  } as ChatConversationViewNode
+}
+
+describe('Chat Node keyed sources', () => {
+  it('notifies only the updated key among 4,000 mounted sources', () => {
+    const builder = new ChatSnapshotBuilder()
+    const nodes = Array.from({ length: 4_000 }, (_, index) => userNode(index + 1))
+    const initial = builder.replace({ nodes, timeline })
+    const listeners = nodes.map(() => vi.fn())
+    const sources: ChatNodeSource[] = nodes.map((node, index) => {
+      const source = initial.nodes.source(node.key)
+      source.subscribe(listeners[index]!)
+      return source
+    })
+
+    const target = 2_347
+    const changed = userNode(target + 1, 'streamed update')
+    const next = builder.apply({ upserts: [changed], timeline })
+
+    expect(listeners[target]).toHaveBeenCalledOnce()
+    expect(listeners.reduce((count, listener) => count + listener.mock.calls.length, 0)).toBe(1)
+    expect(next.nodes.source(changed.key)).toBe(sources[target])
+    expect(next.nodes.get(changed.key)).toBe(changed)
+  })
+})
diff --git a/packages/client/ui-chat/tests/chat-snapshot-fixture.client.ts b/packages/client/ui-chat/tests/chat-snapshot-fixture.client.ts
index 311e2545a8..ce29f6f529 100644
--- a/packages/client/ui-chat/tests/chat-snapshot-fixture.client.ts
+++ b/packages/client/ui-chat/tests/chat-snapshot-fixture.client.ts
@@ -1,6 +1,6 @@
 import type {
   AssistantChatData, AssistantMessageNode, ChatConversationViewNode, ChatSnapshot, ConversationNode,
-  ChatLocationNodeIndex, ChatNodeStore, CompactionSummaryNode, FinalAssistantChatData,
+  ChatLocationNodeIndex, ChatNodeSource, ChatNodeStore, CompactionSummaryNode, FinalAssistantChatData,
   LegacyConversationSlice, PartialAssistant, RunningToolCall, ToolCallBlock, TurnNavigationItem,
 } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type {
@@ -63,35 +63,77 @@ function toolCallName(call: ToolCallBlock): string | null {
   return 'name' in call ? call.name : call.call?.name ?? null
 }
 
+class FixtureNodeSource implements ChatNodeSource {
+  private readonly listeners = new Set<() => void>()
+
+  constructor(
+    private readonly store: FixtureNodeStore,
+    private readonly key: string,
+  ) {}
+
+  readonly getSnapshot = (): ChatConversationViewNode | undefined => this.store.get(this.key)
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  publish(): void {
+    for (const listener of [...this.listeners]) listener()
+  }
+}
+
 class FixtureNodeStore implements ChatNodeStore {
   private byKey = new Map<string, ChatConversationViewNode>()
+  private readonly sources = new Map<string, FixtureNodeSource>()
+  private readonly dirtyKeys = new Set<string>()
   private list: readonly ChatConversationViewNode[] = EMPTY
 
   get(key: string): ChatConversationViewNode | undefined {
     return this.byKey.get(key)
   }
 
+  source(key: string): ChatNodeSource {
+    let source = this.sources.get(key)
+    if (source === undefined) {
+      source = new FixtureNodeSource(this, key)
+      this.sources.set(key, source)
+    }
+    return source
+  }
+
   values(): readonly ChatConversationViewNode[] {
     return this.list
   }
 
   replace(candidates: readonly ChatConversationViewNode[]): void {
+    const previous = this.byKey
     const next = new Map<string, ChatConversationViewNode>()
     const list = candidates.map((candidate) => {
-      const previous = this.byKey.get(candidate.key)
-      const node = previous !== undefined
-        && previous.kind === candidate.kind
-        && previous.anchorSeq === candidate.anchorSeq
-        && sameFixtureLocation(previous.location, candidate.location)
-        && previous.visibility === candidate.visibility
-        && nodeSource(previous) === nodeSource(candidate)
-        ? previous
+      const existing = previous.get(candidate.key)
+      const node = existing !== undefined
+        && existing.kind === candidate.kind
+        && existing.anchorSeq === candidate.anchorSeq
+        && sameFixtureLocation(existing.location, candidate.location)
+        && existing.visibility === candidate.visibility
+        && nodeSource(existing) === nodeSource(candidate)
+        ? existing
         : candidate
       next.set(node.key, node)
       return node
     })
     this.byKey = next
     this.list = sameValues(this.list, list) ? this.list : list
+    const keys = new Set([...previous.keys(), ...next.keys()])
+    for (const key of keys) {
+      if (previous.get(key) !== next.get(key)) this.dirtyKeys.add(key)
+    }
+  }
+
+  publish(): void {
+    const dirty = [...this.dirtyKeys]
+    this.dirtyKeys.clear()
+    for (const key of dirty) this.sources.get(key)?.publish()
   }
 }
 
@@ -420,6 +462,7 @@ export function chatSnapshotFixture(input: {
     && derived.every((item, index) => sameTurnNavigationItem(kept[index], item))
     ? kept
     : derived
+  store.publish()
   return {
     order,
     nodes: store,
diff --git a/packages/client/ui-tool/tests/tool-details-render.client.tsx b/packages/client/ui-tool/tests/tool-details-render.client.tsx
index fb2d60c6bf..5488ac5470 100644
--- a/packages/client/ui-tool/tests/tool-details-render.client.tsx
+++ b/packages/client/ui-tool/tests/tool-details-render.client.tsx
@@ -50,6 +50,7 @@ export function toolChatSnapshot(
     order: nodes.map(node => node.key),
     nodes: {
       get: key => byKey.get(key),
+      source: key => ({ getSnapshot: () => byKey.get(key), subscribe: () => () => {} }),
       values: () => nodes,
     },
     locations: {
diff --git a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
index 0667f16376..101e5cd6d8 100644
--- a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
@@ -64,9 +64,10 @@ const conversationState: ConversationState = {
   activeTargets: new Set(),
 }
 const emptyKeys: readonly string[] = []
+const emptyNodeSource = { getSnapshot: () => undefined, subscribe: () => () => {} }
 const chatState: ChatState = {
   order: emptyKeys,
-  nodes: { get: () => undefined, values: () => [] },
+  nodes: { get: () => undefined, source: () => emptyNodeSource, values: () => [] },
   locations: { getTurn: () => emptyKeys, getStep: () => emptyKeys },
   navigation: { items: () => [] },
   timeline: { turnOrder: [], turns: new Map() },
diff --git a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
index 0ae174caca..e472e6d132 100644
--- a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
@@ -63,9 +63,10 @@ const conversationState: ConversationState = {
   activeTargets: new Set(),
 }
 const emptyKeys: readonly string[] = []
+const emptyNodeSource = { getSnapshot: () => undefined, subscribe: () => () => {} }
 const chatState: ChatState = {
   order: emptyKeys,
-  nodes: { get: () => undefined, values: () => [] },
+  nodes: { get: () => undefined, source: () => emptyNodeSource, values: () => [] },
   locations: { getTurn: () => emptyKeys, getStep: () => emptyKeys },
   navigation: { items: () => [] },
   timeline: { turnOrder: [], turns: new Map() },

From 5f1eca58eaaaf5bf604b64a27cbd25a8d38e5095 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:05:27 +0800
Subject: [PATCH 15/37] perf: InputBar use immutable props

---
 .../ui-conversation/src/client/apply.ts       |  8 +++---
 .../src/client/contract/slots.ts              | 23 ++++++---------
 .../src/client/skeleton/ConversationRoot.tsx  |  5 ----
 .../src/client/skeleton/InputBar.tsx          | 28 ++++++++++++-------
 .../tests/input-bar.client.spec.tsx           | 22 ++++++++++-----
 .../tests/skeleton.client.spec.tsx            | 19 +++++++++++++
 6 files changed, 64 insertions(+), 41 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 87623ca3c3..4c8527c1ee 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -202,11 +202,7 @@ export function apply(ctx: Context): void {
       'conversation.session.header': { kind: 'single', scope: 'session' },
       'conversation.composer': { kind: 'chain', scope: 'session' },
       'conversation.composer.bar': { kind: 'single', scope: 'session-maybe' },
-      'conversation.input.overlay': { kind: 'list', scope: 'session' },
       'conversation.input.dock': { kind: 'list', scope: 'session' },
-      'conversation.composer.dock': { kind: 'list', scope: 'session' },
-      'conversation.input.left': { kind: 'list', scope: 'session' },
-      'conversation.input.right': { kind: 'list', scope: 'session' },
       'conversation.hero.brand.mark': { kind: 'single', scope: 'root' },
       'conversation.hero.workspace': { kind: 'single', scope: 'root' },
       'conversation.hero.agentPreset': { kind: 'single', scope: 'root' },
@@ -277,8 +273,12 @@ export function apply(ctx: Context): void {
     locale: NS,
     children: {
       'conversation.input.attachments': { kind: 'single', scope: 'session-maybe' },
+      'conversation.input.overlay': { kind: 'list', scope: 'session' },
+      'conversation.input.left': { kind: 'list', scope: 'session' },
       'conversation.input.plan': { kind: 'single', scope: 'session' },
+      'conversation.input.right': { kind: 'list', scope: 'session' },
       'conversation.input.model': { kind: 'single', scope: 'session' },
+      'conversation.composer.dock': { kind: 'list', scope: 'session' },
     },
     inject: (sessionId: SessionId | undefined): ComposerBarInjected => {
       if (sessionId === undefined) {
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 1f84c8e3f1..5107c319bf 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -128,11 +128,11 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     /** Floating entries rendered inside the resident composer card. */
     'conversation.input.overlay': { kind: 'list'; scope: 'session' }
     /** Ambient entries below the composer card. */
-    'conversation.composer.dock': { kind: 'list'; scope: 'session'; owner: InputZone }
+    'conversation.composer.dock': { kind: 'list'; scope: 'session' }
     /** Compact controls at the left of the composer tool row. */
-    'conversation.input.left': { kind: 'list'; scope: 'session'; owner: InputZone }
+    'conversation.input.left': { kind: 'list'; scope: 'session' }
     /** Compact controls before the composer submit action. */
-    'conversation.input.right': { kind: 'list'; scope: 'session'; owner: InputZone }
+    'conversation.input.right': { kind: 'list'; scope: 'session' }
     /** Resident composer body, including the no-Session inert state. */
     'conversation.composer.bar': { kind: 'single'; scope: 'session-maybe'; owner: ComposerBarOwnerProps }
     /** Optional draft-image rail and drop target. */
@@ -255,14 +255,6 @@ export interface ComposerBarOwnerProps {
   placeholder?: string
   /** Optional content rendered above the composer surface. */
   accessory?: ReactNode
-  /** Floating overlay content rendered inside the composer card. */
-  overlay?: ReactNode
-  /** Left-side input controls. */
-  leftItems?: ReactNode
-  /** Right-side input controls. */
-  rightItems?: ReactNode
-  /** Ambient content below the card. */
-  footer?: ReactNode
 }
 
 /** Package-private operations injected into the resident composer bar. */
@@ -296,7 +288,10 @@ export interface InputControlOwnerProps {
 export type ComposerBarProps =
   PropsRuntime<'conversation.composer.bar'>
   & PropsRenderSlots<
-    'conversation.input.attachments' | 'conversation.input.plan' | 'conversation.input.model'
+    | 'conversation.input.attachments' | 'conversation.input.overlay'
+    | 'conversation.input.left' | 'conversation.input.plan'
+    | 'conversation.input.right' | 'conversation.input.model'
+    | 'conversation.composer.dock'
   >
   & InjectFace<ComposerBarInjected>
   & PropsLocale<'conversation'>
@@ -325,9 +320,7 @@ export type ConversationSlotProps =
   & PropsRenderSlots<
     | 'conversation.session' | 'conversation.session.header'
     | 'conversation.composer' | 'conversation.composer.bar'
-    | 'conversation.input.overlay'
-    | 'conversation.input.dock' | 'conversation.composer.dock'
-    | 'conversation.input.left' | 'conversation.input.right'
+    | 'conversation.input.dock'
     | 'conversation.hero.brand.mark'
     | 'conversation.hero.workspace'
     | 'conversation.hero.agentPreset'
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
index eb9a3be4fd..dfb515bde6 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
@@ -341,11 +341,6 @@ export function ConversationRoot({
         // user clears it.
         ? { blocked: composerBlock, placeholder: composerBlock.reason }
         : hero ? { placeholder: t('placeholder.hero') } : {}),
-    overlay: sessionId === undefined ? undefined : renderSlot('conversation.input.overlay', {}),
-    leftItems: zone === undefined ? null : renderSlot('conversation.input.left', zone),
-    rightItems: zone === undefined ? null : renderSlot('conversation.input.right', zone),
-    // Ambient dock under the card shares the composer's width constraint.
-    footer: !hero && zone !== undefined ? renderSlot('conversation.composer.dock', zone) : null,
   })
 
   const composerBar = (
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 6c8c46cad4..c223459c51 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -2,8 +2,8 @@
  * Machine state arrives through the standard provide channel
  * (useInput + inputActions); the keyboard/DOM command face and stop arrive
  * through this entry's own inject, whose hooks compartment binds
- * useNotices/useLexicon; layout-phase inputs (variant, placeholder,
- * region-slot content) ride the owner props. Session facts
+ * useNotices/useLexicon; layout-phase inputs (variant and placeholder) ride
+ * the owner props. Session facts
  * (running/removed/promptError) are self-selected via useSession.
  *
  * The text surface is the shell-owned Lexical editor bound here through
@@ -13,7 +13,7 @@
  * trigger instead of a parallel tree.
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { CSSProperties, KeyboardEvent, MouseEvent, ReactNode } from 'react'
 import clsx from 'clsx'
 import {
@@ -39,13 +39,13 @@ import css from './InputBar.module.css'
 
 export type InputBarProps = ComposerBarProps
 
-export function InputBar({
+export const InputBar = memo(function InputBar({
   useSession, useInput, inputActions, keyboard, addImages, removeImage, draftImages,
   resolveSubmitMode, toggleCommandMenu, stop, command, t,
   renderSlot, useNotices, useLexicon, useMenuLauncher,
   useProjection, sessionId, variant, disabled: inert = false, blocked,
   workspacePickerOpen = false, onRequestWorkspace,
-  placeholder, accessory, overlay, leftItems, rightItems, footer,
+  placeholder, accessory,
 }: InputBarProps) {
   const input = useInput(s => s)
   const notice = useNotices(s => s)
@@ -391,7 +391,9 @@ export function InputBar({
         onClick={workspaceTrigger ? onRequestWorkspace : undefined}
         onPointerDown={workspaceTrigger ? (e) => { e.stopPropagation() } : undefined}
       >
-        {overlay !== undefined && <div className={css.overlayAnchor}>{overlay}</div>}
+        {sessionId !== undefined && (
+          <div className={css.overlayAnchor}>{renderSlot('conversation.input.overlay', {})}</div>
+        )}
         {accessory !== undefined && <div className={css.accessory}>{accessory}</div>}
         {renderSlot('conversation.input.attachments', {
           attachments,
@@ -454,10 +456,14 @@ export function InputBar({
               {accessSelect}
               {sessionId === undefined ? null : renderSlot('conversation.input.plan', { locked })}
             </div>
-            {leftItems}
+            {input === undefined || sessionId === undefined
+              ? null
+              : renderSlot('conversation.input.left', {})}
           </div>
           <div className={css.trailing}>
-            {rightItems}
+            {input === undefined || sessionId === undefined
+              ? null
+              : renderSlot('conversation.input.right', {})}
             {sessionId === undefined ? null : renderSlot('conversation.input.model', { locked: modelSeatLocked })}
             <ContextMeter useProjection={useProjection} t={t} />
             {interruptible && (
@@ -499,7 +505,9 @@ export function InputBar({
           </div>
         </div>
       </div>
-      {footer}
+      {variant === 'composer' && input !== undefined && sessionId !== undefined
+        ? renderSlot('conversation.composer.dock', {})
+        : null}
     </div>
   )
-}
+})
diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
index 94aec70bbf..0edc8b9ef6 100644
--- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
@@ -85,6 +85,7 @@ interface BenchOptions {
   overlay?: React.ReactNode
   leftItems?: React.ReactNode
   rightItems?: React.ReactNode
+  footer?: React.ReactNode
   attachments?: readonly ComposerAttachment[]
   addImages?: (files: readonly File[]) => string | null
   commandMenuOpen?: boolean
@@ -145,6 +146,10 @@ function bench(over?: BenchOptions) {
   const slotCalls: { key: string; owner: unknown }[] = []
   const renderSlot = ((key: string, owner: object) => {
     slotCalls.push({ key, owner })
+    if (key === 'conversation.input.overlay') return over?.overlay ?? null
+    if (key === 'conversation.input.left') return over?.leftItems ?? null
+    if (key === 'conversation.input.right') return over?.rightItems ?? null
+    if (key === 'conversation.composer.dock') return over?.footer ?? null
     if (key === 'conversation.input.plan') return over?.planEntry ?? null
     if (key === 'conversation.input.model') return over?.modelEntry ?? null
     return null
@@ -196,9 +201,6 @@ function bench(over?: BenchOptions) {
     ...(over?.onRequestWorkspace !== undefined ? { onRequestWorkspace: over.onRequestWorkspace } : {}),
     ...(over?.placeholder !== undefined ? { placeholder: over.placeholder } : {}),
     ...(over?.accessory !== undefined ? { accessory: over.accessory } : {}),
-    ...(over?.overlay !== undefined ? { overlay: over.overlay } : {}),
-    ...(over?.leftItems !== undefined ? { leftItems: over.leftItems } : {}),
-    ...(over?.rightItems !== undefined ? { rightItems: over.rightItems } : {}),
   }
   const view = render(<InputBar {...props} />)
   const textarea = view.container.querySelector<HTMLDivElement>('[data-composer-input]')!
@@ -1278,15 +1280,17 @@ describe('strips and variants', () => {
     expect(view.container.querySelector('[class*="hero"]')).not.toBeNull()
   })
 
-  it('renders overlay anchor and left/right slot items', () => {
+  it('renders overlay, left/right, and footer slots at their layout positions', () => {
     const { view } = bench({
       overlay: <i data-testid="ov" />,
       leftItems: <i data-testid="li" />,
       rightItems: <i data-testid="ri" />,
+      footer: <i data-testid="foot" />,
     })
     expect(view.getByTestId('ov')).toBeTruthy()
     expect(view.getByTestId('li')).toBeTruthy()
     expect(view.getByTestId('ri')).toBeTruthy()
+    expect(view.getByTestId('foot')).toBeTruthy()
   })
 })
 
@@ -1299,7 +1303,10 @@ describe('command launcher chrome and control seats', () => {
     // Every seat dispatched, nothing rendered (render passes may repeat; the
     // seat set is the contract).
     expect([...new Set(slotCalls.map(c => c.key))]).toEqual([
-      'conversation.input.attachments', 'conversation.input.plan', 'conversation.input.model',
+      'conversation.input.overlay', 'conversation.input.attachments',
+      'conversation.input.plan', 'conversation.input.left',
+      'conversation.input.right', 'conversation.input.model',
+      'conversation.composer.dock',
     ])
     expect(view.queryByLabelText('Plan mode')).toBeNull()
     expect(view.queryByLabelText('Model')).toBeNull()
@@ -1465,12 +1472,13 @@ describe('command launcher chrome and control seats', () => {
     expect(view.getByTestId('plan-entry')).toBeTruthy()
     expect(view.getByTestId('model-entry')).toBeTruthy()
     // The bar hands its chrome disable state to the filling entry.
-    const controls = slotCalls.filter(call => call.key !== 'conversation.input.attachments')
+    const controlKeys = new Set(['conversation.input.plan', 'conversation.input.model'])
+    const controls = slotCalls.filter(call => controlKeys.has(call.key))
     expect(controls.every(c => (c.owner as { locked: boolean }).locked)).toBe(true)
     expect(attachmentOwner(slotCalls).canAcceptDrop).toBe(false)
     cleanup()
     const live = bench({ running: true })
-    const liveControls = live.slotCalls.filter(call => call.key !== 'conversation.input.attachments')
+    const liveControls = live.slotCalls.filter(call => controlKeys.has(call.key))
     expect(liveControls.every(c => !(c.owner as { locked: boolean }).locked)).toBe(true)
     expect(attachmentOwner(live.slotCalls).canAcceptDrop).toBe(true)
   })
diff --git a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
index 3abf6f1381..b431a51ff8 100644
--- a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
@@ -328,6 +328,25 @@ describe('Hero chrome', () => {
 })
 
 describe('ConversationRoot resident composer', () => {
+  it('does not redispatch composer child slots for an unrelated Session publication', () => {
+    const b = mount(sessionSnapshotOf())
+    const childKeys = new Set([
+      'conversation.input.overlay',
+      'conversation.input.left',
+      'conversation.input.right',
+      'conversation.composer.dock',
+    ])
+    const dispatchCount = () => b.slotCalls.filter(key => childKeys.has(key)).length
+    const before = dispatchCount()
+
+    act(() => {
+      const current = b.session.getSnapshot()
+      b.session.set({ ...current, hasMore: !current.hasMore })
+    })
+
+    expect(dispatchCount()).toBe(before)
+  })
+
   it('renders the composer inert with the blocker\u2019s own reason', () => {
     const b = mount(sessionSnapshotOf(), undefined, undefined, {
       composerBlock: { reason: 'select a model first' },

From 56a4d51d2c68657132b8781cbb077b34c677f2b9 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:07:25 +0800
Subject: [PATCH 16/37] perf(ui-chat): scope turn process updates

---
 packages/client/ui-chat/src/client/apply.ts   |  10 +-
 .../ui-chat/src/client/chat/ChatNodeSeat.tsx  | 148 +++++-------------
 .../ui-chat/src/client/chat/ChatView.tsx      |   3 +-
 .../ui-chat/src/client/chat/use-turn-data.ts  |  23 +++
 .../ui-chat/src/client/contract/slots.ts      |   5 +-
 .../ui-chat/src/client/contract/snapshot.ts   |  25 +++
 .../ui-chat/src/client/contract/store.ts      |   4 +-
 .../src/client/contract/turn-process.ts       |  67 ++------
 .../chat-snapshot-builder.ts                  | 119 ++++++++++++--
 .../turn-process-presentation.ts              | 135 ++++++++++++++++
 .../client/conversation-nodes/turn-process.ts |  17 +-
 packages/client/ui-chat/src/client/index.ts   |   5 +-
 packages/client/ui-chat/src/client/stores.ts  |   9 +-
 .../ui-chat/tests/chat-apply.client.spec.tsx  |  77 +++++----
 .../tests/chat-snapshot-fixture.client.ts     | 107 ++++++++++---
 .../ui-chat/tests/chat-store.client.spec.ts   |  22 +--
 .../ui-chat/tests/chat-view.client.spec.tsx   |  28 ++--
 ...nversation-node-definitions.client.spec.ts |  84 +++++++---
 .../src/client/contract/conversation.ts       |  20 ++-
 .../src/client/conversation/assembler.ts      |   2 +
 .../src/client/conversation/location-index.ts |  93 +++++++++--
 .../ui-conversation/src/client/index.ts       |   3 +-
 .../conversation-assembler.client.spec.ts     |  53 ++++++-
 .../tests/produced-files.client.spec.tsx      |  14 +-
 .../tests/tool-details-render.client.tsx      |   1 +
 .../tests/layout.client.spec.tsx              |   7 +-
 .../tests/snapshot-builder.client.spec.ts     |   5 +-
 .../tests/plan-review-panel.client.spec.tsx   |   7 +-
 .../user-questions-composer.client.spec.tsx   |   7 +-
 29 files changed, 764 insertions(+), 336 deletions(-)
 create mode 100644 packages/client/ui-chat/src/client/chat/use-turn-data.ts
 create mode 100644 packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts

diff --git a/packages/client/ui-chat/src/client/apply.ts b/packages/client/ui-chat/src/client/apply.ts
index a23ada43d7..f36ba12728 100644
--- a/packages/client/ui-chat/src/client/apply.ts
+++ b/packages/client/ui-chat/src/client/apply.ts
@@ -31,16 +31,12 @@ import { TranscriptViewRow, type TranscriptViewRowInjected } from './settings/Tr
 import { createChatStore } from './stores.ts'
 import { TranscriptViewPolicy } from './transcript-view.ts'
 import { CHAT_SETTINGS_NAMESPACE, type ChatSettings } from '../chat-settings.ts'
+import { useTurnDataValue } from './chat/use-turn-data.ts'
 
 const CHAT_NODE_INJECT: ChatNodeTurnDataInjected = {
   hooks: {
-    turnData: ({ useChat }, nodeKey) => function useTurnData(key) {
-      return useChat((snapshot) => {
-        const location = snapshot.nodes.get(nodeKey)?.location
-        return location?.kind === 'turn' || location?.kind === 'step'
-          ? location.turn.data.get(key)
-          : undefined
-      })
+    turnData: (_standard, data) => function useTurnData(key) {
+      return useTurnDataValue(data, key)
     },
   },
 }
diff --git a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
index cfa4b52f13..0476b71132 100644
--- a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
@@ -1,22 +1,19 @@
 import { memo, useCallback, useMemo, useSyncExternalStore } from 'react'
 import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ConversationLocationDataStore, ConversationTurnDataMap } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts'
 import type { ChatNode } from '../contract/chat-nodes.ts'
-import type { ChatNodeSource, ChatNodeStore } from '../contract/snapshot.ts'
-import {
-  decodeTurnProcess, TURN_PROCESS_INDEPENDENT_KINDS, turnProcessGeneration,
-  type TurnProcessSpec,
-} from '../contract/turn-process.ts'
+import type { ChatNodeProcessSource, ChatNodeSource } from '../contract/snapshot.ts'
+import { TURN_PROCESS_INDEPENDENT_KINDS } from '../contract/turn-process.ts'
 import { storedTurnProcessEntry } from '../stores.ts'
 import { useSearchableHidden } from './searchable-hidden.ts'
 import css from './ChatView.module.css'
 
 interface ChatNodeSeatProps extends ChatNodeOwnerProps {
-  readonly nodeKey: string
   readonly nodeSource: ChatNodeSource
+  readonly processSource: ChatNodeProcessSource
   readonly historyIncomplete: boolean
   readonly compactTranscript: boolean
-  readonly useChat: ChatViewSlotProps['useChat']
   readonly useStore: ChatViewSlotProps['useStore']
   readonly actions: ChatViewSlotProps['actions']
   readonly renderSlot: ChatViewSlotProps['renderSlot']
@@ -27,133 +24,65 @@ type RoutedChatNodeOwner = {
   [Kind in ChatNode['kind']]: ChatNodeOwnerProps & { readonly node: ChatNode<Kind> }
 }[ChatNode['kind']]
 
-const EMPTY_PROCESS_KEYS: readonly string[] = []
-
-interface TurnProcessLayout {
-  readonly hasExternalProcess: boolean
-  readonly compactAnswer: boolean
+function turnDataOf(node: ChatNode | undefined): ConversationLocationDataStore<ConversationTurnDataMap> | undefined {
+  const location = node?.location
+  return location?.kind === 'turn' || location?.kind === 'step' ? location.turn.data : undefined
 }
 
-function turnProcessOpeningHumanAnchor(
-  keys: readonly string[],
-  nodes: ChatNodeStore,
-  spec: TurnProcessSpec,
-): number | undefined {
-  let anchor: number | undefined
-  for (const key of keys) {
-    const node = nodes.get(key) as ChatNode | undefined
-    if ((node?.kind === 'user' || node?.kind === 'steering')
-      && node.anchorSeq < spec.controlAnchorSeq) {
-      anchor = Math.min(anchor ?? node.anchorSeq, node.anchorSeq)
-    }
-  }
-  return anchor
-}
-
-/** Derive disclosure facts from one content-revisioned Turn index. */
-function turnProcessLayout(
-  keys: readonly string[],
-  nodes: ChatNodeStore,
-  spec: TurnProcessSpec,
-): TurnProcessLayout {
-  let hasExternalProcess = false
-  let compactAnswer = true
-  const openingHumanAnchor = turnProcessOpeningHumanAnchor(keys, nodes, spec)
-  for (const key of keys) {
-    const node = nodes.get(key) as ChatNode | undefined
-    if (node === undefined || node.kind === 'turn-process') continue
-    if ((node.kind === 'user' || node.kind === 'steering')
-      && (openingHumanAnchor === undefined || node.anchorSeq > openingHumanAnchor)
-      && (spec.answerAnchorSeq === null || node.anchorSeq < spec.answerAnchorSeq)) {
-      compactAnswer = false
-    }
-    if (TURN_PROCESS_INDEPENDENT_KINDS.has(node.kind)
-      || node.anchorSeq < spec.processStartSeq
-      || (spec.answerAnchorSeq !== null && node.anchorSeq >= spec.answerAnchorSeq)) continue
-    if (node.kind !== 'assistant-step' || spec.answerStep === null || node.data.step !== spec.answerStep) {
-      hasExternalProcess = true
-    }
-  }
-  return { hasExternalProcess, compactAnswer }
+function turnOf(node: ChatNode | undefined): number | undefined {
+  const location = node?.location
+  return location?.kind === 'turn' || location?.kind === 'step' ? location.turn.turn : undefined
 }
 
 /** Subscribe, apply Turn-process visibility, and dispatch one stable Context key. */
 export const ChatNodeSeat = memo(function ChatNodeSeat({
-  nodeKey, nodeSource, historyIncomplete, compactTranscript,
+  nodeSource, processSource, historyIncomplete, compactTranscript,
   selectedCallId, cwd, openFile, inspectCall, forkAt,
-  renderMessageImages, fileMentions, useChat, useStore, actions, renderSlot, t,
+  renderMessageImages, fileMentions, useStore, actions, renderSlot, t,
 }: ChatNodeSeatProps) {
   const node = useSyncExternalStore(nodeSource.subscribe, nodeSource.getSnapshot)
-  const processSignature = useChat((snapshot) => {
-    const current = snapshot.nodes.get(nodeKey)
-    const location = current?.location
-    return location?.kind === 'turn' || location?.kind === 'step'
-      ? location.turn.data.get('turn-process')
-      : undefined
-  })
-  const processSpec = useMemo(
-    () => processSignature === undefined ? undefined : decodeTurnProcess(processSignature),
-    [processSignature],
-  )
-  const nodeStore = useChat(snapshot => snapshot.nodes)
-  const processLayoutKeys = useChat((snapshot) => {
-    if (!compactTranscript || historyIncomplete || processSpec === undefined) return EMPTY_PROCESS_KEYS
-    const current = snapshot.nodes.get(nodeKey) as ChatNode | undefined
-    const location = current?.location
-    if (current === undefined
-      || (location?.kind !== 'turn' && location?.kind !== 'step')
-      || location.turn.status !== 'closed'
-      || location.turn.turn !== processSpec.turn) return EMPTY_PROCESS_KEYS
-    const ownsLayout = current.kind === 'turn-process'
-      || (current.kind === 'assistant-step' && current.data.step === processSpec.answerStep)
-    return ownsLayout ? snapshot.locations.getTurn(processSpec.turn) : EMPTY_PROCESS_KEYS
-  })
-  const processLayout = useMemo(
-    () => processSpec === undefined || processLayoutKeys.length === 0
-      ? undefined
-      : turnProcessLayout(processLayoutKeys, nodeStore, processSpec),
-    [nodeStore, processLayoutKeys, processSpec],
-  )
-  const processGeneration = useMemo(
-    () => processSpec === undefined ? undefined : turnProcessGeneration(processSpec),
-    [processSpec],
+  const routedNode = node as ChatNode | undefined
+  const turn = turnOf(routedNode)
+  const processPresentation = useSyncExternalStore(
+    processSource.subscribe,
+    processSource.getSnapshot,
   )
+  const processSpec = processPresentation?.spec
   const storedEntry = useStore(state => processSpec === undefined
     ? undefined
     : storedTurnProcessEntry(state, processSpec.turn))
-  const processEntry = storedEntry?.generation === processGeneration ? storedEntry : undefined
+  const processEntry = processSpec !== undefined
+    && processSpec.answerStep !== null
+    && storedEntry?.answerStep === processSpec.answerStep
+    ? storedEntry
+    : undefined
   const processOpen = processEntry !== undefined
   const setOpen = useCallback((open: boolean) => {
-    if (processGeneration !== undefined && processSpec !== undefined) {
-      actions.setTurnProcessOpen(processSpec.turn, processGeneration, open)
+    if (processSpec !== undefined && processSpec.answerStep !== null) {
+      actions.setTurnProcessOpen(processSpec.turn, processSpec.answerStep, open)
     }
-  }, [actions, processGeneration, processSpec])
-  const routedNode = node as ChatNode | undefined
-  const sameTurn = routedNode !== undefined
-    && processSpec !== undefined
-    && (routedNode.location.kind === 'turn' || routedNode.location.kind === 'step')
-    && routedNode.location.turn.turn === processSpec.turn
-  const turnClosed = sameTurn
-    && routedNode.location.turn.status === 'closed'
+  }, [actions, processSpec])
   const processWindowReady = processSpec !== undefined
+    && processPresentation !== undefined
     && compactTranscript
     && processSpec.answerAnchorSeq !== null
-    && turnClosed
+    && processPresentation.turn === processSpec.turn
+    && processPresentation.turnClosed
     && !historyIncomplete
-  const processMember = sameTurn
+  const processMember = routedNode !== undefined
     && processWindowReady
     && !TURN_PROCESS_INDEPENDENT_KINDS.has(routedNode.kind)
     && routedNode.anchorSeq >= processSpec.processStartSeq
     && routedNode.anchorSeq < processSpec.answerAnchorSeq
-  const processAnswer = sameTurn
+  const processAnswer = routedNode !== undefined
     && processWindowReady
     && routedNode.kind === 'assistant-step'
     && routedNode.data.step === processSpec.answerStep
   const ownsDisclosure = routedNode?.kind === 'turn-process' || processAnswer
   const foldable = processWindowReady
     && (processMember || (ownsDisclosure
-      && ((processLayout?.hasExternalProcess ?? false) || processSpec.inlineReasoning)))
-  const turnProcess = useMemo(() => processGeneration === undefined || processSpec === undefined
+      && (processPresentation.hasExternalProcess || processSpec.inlineReasoning)))
+  const turnProcess = useMemo(() => processSpec === undefined
     ? undefined
     : {
       spec: processSpec,
@@ -161,13 +90,13 @@ export const ChatNodeSeat = memo(function ChatNodeSeat({
       open: processOpen,
       setOpen,
     }, [
-    foldable, processGeneration, processOpen, processSpec, setOpen,
+    foldable, processOpen, processSpec, setOpen,
   ])
   const controllerInactive = routedNode?.kind === 'turn-process'
     && !foldable
   const compactAnswer = processAnswer
     && foldable
-    && processLayout?.compactAnswer === true
+    && processPresentation.compactAnswer
     && !processOpen
   const processHidden = controllerInactive || (foldable && processMember && !processOpen)
   const revealProcess = useCallback(() => {
@@ -190,10 +119,7 @@ export const ChatNodeSeat = memo(function ChatNodeSeat({
     renderMessageImages, fileMentions, turnProcess,
   ])
   if (routedNode === undefined || owner === null) return null
-  const location = routedNode.location
-  const turn = location.kind === 'turn' || location.kind === 'step'
-    ? location.turn.turn
-    : undefined
+  const turnData = turnDataOf(routedNode)
   // Runtime dispatch owns the correlation: every Node's discriminant is the
   // keyed-slot entry passed alongside that same Node. TypeScript does not
   // distribute an object containing a union into a union of objects itself.
@@ -212,7 +138,7 @@ export const ChatNodeSeat = memo(function ChatNodeSeat({
     >
       {renderSlot('conversation.chat.node', routedOwner, {
         entryKey: routedNode.kind,
-        hookContext: nodeKey,
+        hookContext: turnData,
         fallback: (
           <JsonBlock
             label={t('message.unknownSurface', { type: routedNode.kind })}
diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index 259687ee00..28f789afad 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -745,11 +745,10 @@ export function ChatView({
           {order.map(nodeKey => (
             <ChatNodeSeat
               key={nodeKey}
-              nodeKey={nodeKey}
               nodeSource={nodeStore.source(nodeKey)}
+              processSource={nodeStore.processSource(nodeKey)}
               historyIncomplete={hasMore}
               compactTranscript={compactTranscript}
-              useChat={useChat}
               useStore={useStore}
               actions={actions}
               selectedCallId={selectedCallId}
diff --git a/packages/client/ui-chat/src/client/chat/use-turn-data.ts b/packages/client/ui-chat/src/client/chat/use-turn-data.ts
new file mode 100644
index 0000000000..b16e2f55ff
--- /dev/null
+++ b/packages/client/ui-chat/src/client/chat/use-turn-data.ts
@@ -0,0 +1,23 @@
+import { useSyncExternalStore } from 'react'
+import type {
+  ConversationLocationDataSource, ConversationLocationDataStore, ConversationTurnDataMap,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const EMPTY_SOURCE: ConversationLocationDataSource<undefined> = {
+  getSnapshot: () => undefined,
+  subscribe: () => () => {},
+}
+
+/**
+ * Subscribe to one value from a Turn's keyed Location-data store.
+ * @param data - current Turn data store, or absence for a Node outside a Turn.
+ * @param key - declaration-merged business key.
+ * @returns the current value for that key.
+ */
+export function useTurnDataValue<Key extends Extract<keyof ConversationTurnDataMap, string>>(
+  data: ConversationLocationDataStore<ConversationTurnDataMap> | undefined,
+  key: Key,
+): Readonly<ConversationTurnDataMap[Key]> | undefined {
+  const source = data?.source(key) ?? EMPTY_SOURCE
+  return useSyncExternalStore(source.subscribe, source.getSnapshot)
+}
diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts
index 2ff7122ea2..405a94238f 100644
--- a/packages/client/ui-chat/src/client/contract/slots.ts
+++ b/packages/client/ui-chat/src/client/contract/slots.ts
@@ -2,7 +2,8 @@
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type {
-  ConversationTurnDataMap, MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, TurnLocation,
+  ConversationLocationDataStore, ConversationTurnDataMap,
+  MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, TurnLocation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
   InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SlotHookFactory,
@@ -176,7 +177,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
       scope: 'session'
       owner: ChatNodeOwnerProps
       keyProps: { [Kind in ChatNodeKind]: { node: ChatNode<Kind> } }
-      hookContext: string
+      hookContext: ConversationLocationDataStore<ConversationTurnDataMap> | undefined
       inject: ChatNodeTurnDataInjected
     }
     /**
diff --git a/packages/client/ui-chat/src/client/contract/snapshot.ts b/packages/client/ui-chat/src/client/contract/snapshot.ts
index ea46ee4382..b6526a60c3 100644
--- a/packages/client/ui-chat/src/client/contract/snapshot.ts
+++ b/packages/client/ui-chat/src/client/contract/snapshot.ts
@@ -2,6 +2,7 @@ import type {
   ConversationNode, ConversationTimelineSnapshot, PartialAssistant, RunningToolCall,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ChatConversationViewNode } from './chat-nodes.ts'
+import type { TurnProcessSpec } from './turn-process.ts'
 
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
@@ -19,12 +20,22 @@ export interface ChatNodeSource {
   subscribe(listener: () => void): () => void
 }
 
+/** Per-key observable for the Turn-process presentation surrounding one Chat Node. */
+export interface ChatNodeProcessSource {
+  /** @returns the current presentation, or absence outside a projected Turn process. */
+  getSnapshot(): ChatTurnProcessPresentation | undefined
+  /** @param listener - callback for presentation changes. @returns the unsubscribe function. */
+  subscribe(listener: () => void): () => void
+}
+
 /** Stable live per-key reader for Chat nodes. */
 export interface ChatNodeStore {
   /** @param key - stable Conversation Context key. @returns current Node, when visible or hidden. */
   get(key: string): ChatConversationViewNode | undefined
   /** @param key - stable Conversation Context key. @returns its identity-stable observable source. */
   source(key: string): ChatNodeSource
+  /** @param key - stable Conversation Context key. @returns its Turn-process presentation source. */
+  processSource(key: string): ChatNodeProcessSource
   /** @returns all currently materialized Nodes without imposing render order. */
   values(): readonly ChatConversationViewNode[]
 }
@@ -59,6 +70,15 @@ export interface ChatLocationNodeIndex {
   getStep(turn: number, step: number): readonly string[]
 }
 
+/** Cross-Node presentation facts derived for one Turn process. */
+export interface ChatTurnProcessPresentation {
+  readonly turn: number
+  readonly spec: TurnProcessSpec
+  readonly turnClosed: boolean
+  readonly hasExternalProcess: boolean
+  readonly compactAnswer: boolean
+}
+
 /** Compatibility projection backing StatsLine and the legacy top-level snapshot fields. */
 export interface LegacyConversationSlice {
   readonly nodes: readonly ConversationNode[]
@@ -90,6 +110,10 @@ const EMPTY_NODE_SOURCE: ChatNodeSource = {
   getSnapshot: () => undefined,
   subscribe: () => () => {},
 }
+const EMPTY_NODE_PROCESS_SOURCE: ChatNodeProcessSource = {
+  getSnapshot: () => undefined,
+  subscribe: () => () => {},
+}
 
 /** Empty Chat target used before a view builder is registered. */
 export const EMPTY_CHAT_SNAPSHOT: ChatSnapshot = {
@@ -97,6 +121,7 @@ export const EMPTY_CHAT_SNAPSHOT: ChatSnapshot = {
   nodes: {
     get: () => undefined,
     source: () => EMPTY_NODE_SOURCE,
+    processSource: () => EMPTY_NODE_PROCESS_SOURCE,
     values: () => EMPTY_LIST,
   },
   locations: {
diff --git a/packages/client/ui-chat/src/client/contract/store.ts b/packages/client/ui-chat/src/client/contract/store.ts
index f5f22a4f85..dc7bb4463e 100644
--- a/packages/client/ui-chat/src/client/contract/store.ts
+++ b/packages/client/ui-chat/src/client/contract/store.ts
@@ -1,7 +1,5 @@
 /** Chat-owned selection state shared by the transcript and details panel. */
 
-import type { TurnProcessGeneration } from './turn-process.ts'
-
 /** Tool call identity as carried by Chat nodes. */
 export type ToolCallId = string
 
@@ -16,7 +14,7 @@ export interface SelectionTarget {
 /** One manually expanded Turn answer generation. */
 export interface TurnProcessViewEntry {
   readonly turn: number
-  readonly generation: TurnProcessGeneration
+  readonly answerStep: number
 }
 
 /** Per-Session state shared only by the Chat view and details surface. */
diff --git a/packages/client/ui-chat/src/client/contract/turn-process.ts b/packages/client/ui-chat/src/client/contract/turn-process.ts
index 791830dead..15c90523bb 100644
--- a/packages/client/ui-chat/src/client/contract/turn-process.ts
+++ b/packages/client/ui-chat/src/client/contract/turn-process.ts
@@ -1,11 +1,5 @@
 import type { ChatNode } from './chat-nodes.ts'
 
-/** Turn-local process window encoded as a reference-stable Location-data scalar. */
-export type TurnProcessSignature = string
-
-/** Stable identity of one finalized answer generation, independent of its exact ordering anchor. */
-export type TurnProcessGeneration = string
-
 /** Current process range and finalized answer boundary derived from one Turn. */
 export interface TurnProcessSpec {
   readonly turn: number
@@ -39,54 +33,21 @@ export const TURN_PROCESS_INDEPENDENT_KINDS: ReadonlySet<string> = new Set(
 )
 
 /**
- * Identify one finalized answer generation without using its ordering anchor.
- * @param spec - current Turn process specification.
- * @returns stable identity until the finalized answer Step is withdrawn or replaced.
+ * Compare immutable Turn-process specifications by their published fields.
+ * @param left - previous specification.
+ * @param right - next specification.
+ * @returns whether both values describe the same process presentation.
  */
-export function turnProcessGeneration(spec: TurnProcessSpec): TurnProcessGeneration {
-  return `${String(spec.turn)}|${spec.answerStep === null ? '' : String(spec.answerStep)}`
-}
-
-/**
- * Encode one process specification as a primitive Location-data value.
- * @param spec - current Turn process specification.
- * @returns reference-stable scalar for equal specifications.
- */
-export function encodeTurnProcess(spec: TurnProcessSpec): TurnProcessSignature {
-  return [
-    spec.turn,
-    spec.controlAnchorSeq,
-    spec.processStartSeq,
-    spec.answerAnchorSeq ?? '',
-    spec.answerStep ?? '',
-    spec.inlineReasoning ? 1 : 0,
-    spec.messageCount,
-    spec.toolCallCount,
-    spec.subagentCount,
-  ].join('|')
-}
-
-/**
- * Decode a same-process signature produced by {@link encodeTurnProcess}.
- * @param signature - encoded Turn process value.
- * @returns decoded process specification.
- */
-export function decodeTurnProcess(signature: TurnProcessSignature): TurnProcessSpec {
-  const [
-    turn, controlAnchorSeq, processStartSeq, answerAnchorSeq, answerStep, inlineReasoning,
-    messageCount, toolCallCount, subagentCount,
-  ] = signature.split('|')
-  return {
-    turn: Number(turn),
-    controlAnchorSeq: Number(controlAnchorSeq),
-    processStartSeq: Number(processStartSeq),
-    answerAnchorSeq: answerAnchorSeq === '' ? null : Number(answerAnchorSeq),
-    answerStep: answerStep === '' ? null : Number(answerStep),
-    inlineReasoning: inlineReasoning === '1',
-    messageCount: Number(messageCount),
-    toolCallCount: Number(toolCallCount),
-    subagentCount: Number(subagentCount),
-  }
+export function sameTurnProcessSpec(left: TurnProcessSpec, right: TurnProcessSpec): boolean {
+  return left.turn === right.turn
+    && left.controlAnchorSeq === right.controlAnchorSeq
+    && left.processStartSeq === right.processStartSeq
+    && left.answerAnchorSeq === right.answerAnchorSeq
+    && left.answerStep === right.answerStep
+    && left.inlineReasoning === right.inlineReasoning
+    && left.messageCount === right.messageCount
+    && left.toolCallCount === right.toolCallCount
+    && left.subagentCount === right.subagentCount
 }
 
 /**
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
index 1f1c7bb2a6..1ef2b16d3f 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -7,12 +7,14 @@ import type {
 import type { ChatConversationViewNode, ChatNode } from '../contract/chat-nodes.ts'
 import { isRunningTool } from '../contract/chat-nodes.ts'
 import type {
-  ChatLocationNodeIndex, ChatNodeSource, ChatNodeStore, ChatSnapshot, ChatTurnNavigationIndex, ConversationNode,
-  LegacyConversationSlice, PartialAssistant, RunningToolCall, TurnNavigationItem,
+  ChatLocationNodeIndex, ChatNodeProcessSource, ChatNodeSource, ChatNodeStore, ChatSnapshot,
+  ChatTurnNavigationIndex, ChatTurnProcessPresentation, ConversationNode, LegacyConversationSlice,
+  PartialAssistant, RunningToolCall, TurnNavigationItem,
 } from '../contract/snapshot.ts'
 import { TURN_PROCESS_INDEPENDENT_KINDS } from '../contract/turn-process.ts'
 import { sessionRecallLabels } from './event-projection.ts'
 import { sameTurnNavigationItem, turnNavigationItem } from './turn-navigation.ts'
+import { ChatTurnProcessProjector } from './turn-process-presentation.ts'
 
 const EMPTY_KEYS: readonly string[] = []
 const EMPTY_TURNS: readonly number[] = []
@@ -23,15 +25,31 @@ function sameReferences<T>(left: readonly T[], right: readonly T[]): boolean {
   return left.length === right.length && left.every((value, index) => value === right[index])
 }
 
-class MutableChatNodeSource implements ChatNodeSource {
+function cachedSource<Key, Source>(
+  sources: Map<Key, Source>,
+  key: Key,
+  create: () => Source,
+): Source {
+  let source = sources.get(key)
+  if (source === undefined) {
+    source = create()
+    sources.set(key, source)
+  }
+  return source
+}
+
+class MutableChatSource<Value> {
   private readonly listeners = new Set<() => void>()
+  private published: Value
 
   constructor(
-    private readonly store: MutableChatNodeStore,
-    private readonly key: string,
-  ) {}
+    private readonly read: () => Value,
+    private readonly label: string,
+  ) {
+    this.published = read()
+  }
 
-  readonly getSnapshot = (): ChatConversationViewNode | undefined => this.store.get(this.key)
+  readonly getSnapshot = (): Value => this.read()
 
   readonly subscribe = (listener: () => void): (() => void) => {
     this.listeners.add(listener)
@@ -39,14 +57,20 @@ class MutableChatNodeSource implements ChatNodeSource {
   }
 
   publish(): void {
-    notifySubscribers(this.listeners, `[ui-chat] node source ${this.key}`)
+    const next = this.getSnapshot()
+    if (this.published === next) return
+    this.published = next
+    notifySubscribers(this.listeners, this.label)
   }
 }
 
 class MutableChatNodeStore implements ChatNodeStore {
   private readonly byKey = new Map<string, ChatConversationViewNode>()
-  private readonly sources = new Map<string, MutableChatNodeSource>()
+  private readonly turnProcesses = new ChatTurnProcessProjector()
+  private readonly sources = new Map<string, MutableChatSource<ChatConversationViewNode | undefined>>()
+  private readonly processSources = new Map<string, MutableChatSource<ChatTurnProcessPresentation | undefined>>()
   private readonly dirtyKeys = new Set<string>()
+  private readonly dirtyProcessKeys = new Set<string>()
   private valuesCache: readonly ChatConversationViewNode[] = EMPTY_LIST
   private valuesDirty = false
 
@@ -55,12 +79,21 @@ class MutableChatNodeStore implements ChatNodeStore {
   }
 
   source(key: string): ChatNodeSource {
-    let source = this.sources.get(key)
-    if (source === undefined) {
-      source = new MutableChatNodeSource(this, key)
-      this.sources.set(key, source)
-    }
-    return source
+    return cachedSource(this.sources, key, () => new MutableChatSource(
+      () => this.get(key),
+      `[ui-chat] node source ${key}`,
+    ))
+  }
+
+  processSource(key: string): ChatNodeProcessSource {
+    return cachedSource(this.processSources, key, () => new MutableChatSource(
+      () => this.process(key),
+      `[ui-chat] node process source ${key}`,
+    ))
+  }
+
+  process(key: string): ChatTurnProcessPresentation | undefined {
+    return this.turnProcesses.get(this.get(key) as ChatNode | undefined)
   }
 
   values(): readonly ChatConversationViewNode[] {
@@ -76,10 +109,16 @@ class MutableChatNodeStore implements ChatNodeStore {
     this.byKey.clear()
     for (const node of nodes) {
       this.byKey.set(node.key, node)
-      if (previous.get(node.key) !== node) this.dirtyKeys.add(node.key)
+      if (previous.get(node.key) !== node) {
+        this.dirtyKeys.add(node.key)
+        this.dirtyProcessKeys.add(node.key)
+      }
       previous.delete(node.key)
     }
-    for (const key of previous.keys()) this.dirtyKeys.add(key)
+    for (const key of previous.keys()) {
+      this.dirtyKeys.add(key)
+      this.dirtyProcessKeys.add(key)
+    }
     this.valuesCache = [...this.byKey.values()]
     this.valuesDirty = false
   }
@@ -90,15 +129,33 @@ class MutableChatNodeStore implements ChatNodeStore {
       if (this.byKey.get(node.key) === node) continue
       this.byKey.set(node.key, node)
       this.dirtyKeys.add(node.key)
+      this.dirtyProcessKeys.add(node.key)
       changed = true
     }
     if (changed) this.valuesDirty = true
   }
 
+  touchProcesses(turns: ReadonlySet<number>, locations: ChatLocationNodeIndex): void {
+    for (const turn of turns) {
+      for (const key of locations.getTurn(turn)) this.dirtyProcessKeys.add(key)
+    }
+  }
+
+  replaceProcesses(order: readonly string[], locations: ChatLocationNodeIndex): void {
+    this.touchProcesses(this.turnProcesses.replace(order, locations, this), locations)
+  }
+
+  updateProcesses(turns: ReadonlySet<number>, locations: ChatLocationNodeIndex): void {
+    this.touchProcesses(this.turnProcesses.update(turns, locations, this), locations)
+  }
+
   publish(): void {
     const dirty = [...this.dirtyKeys]
+    const dirtyProcesses = [...this.dirtyProcessKeys]
     this.dirtyKeys.clear()
+    this.dirtyProcessKeys.clear()
     for (const key of dirty) this.sources.get(key)?.publish()
+    for (const key of dirtyProcesses) this.processSources.get(key)?.publish()
   }
 }
 
@@ -238,6 +295,25 @@ function locationCoordinates(location: ConversationLocation): { turn?: number; s
   return {}
 }
 
+function locationTurnStatus(location: ConversationLocation): string | undefined {
+  return location.kind === 'turn' || location.kind === 'step' ? location.turn.status : undefined
+}
+
+function processPresentationInputChanged(
+  previous: ChatNode | undefined,
+  next: ChatNode,
+  structural: boolean,
+): boolean {
+  if (structural || previous === undefined) return true
+  if (locationTurnStatus(previous.location) !== locationTurnStatus(next.location)) return true
+  if (previous.kind === 'turn-process' && next.kind === 'turn-process') {
+    return previous.data !== next.data
+  }
+  return previous.kind === 'assistant-step'
+    && next.kind === 'assistant-step'
+    && previous.data.step !== next.data.step
+}
+
 interface TurnProcessPresentation {
   readonly control?: ChatNode<'turn-process'>
   readonly openingHumanAnchor?: number
@@ -695,6 +771,7 @@ export class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversa
     this.store.replace(nodes)
     this.order = orderedVisibleChatNodes(nodes).map(node => node.key)
     this.locations.rebuild(this.order, this.store)
+    this.store.replaceProcesses(this.order, this.locations)
     this.navigation.rebuild(input.timeline, this.locations, this.store)
     this.timeline = input.timeline
     const snapshot = this.snapshot(input.timeline, this.legacy.replace(nodes, input.timeline))
@@ -707,6 +784,7 @@ export class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversa
     readonly timeline: ConversationTimelineSnapshot
   }): ChatSnapshot {
     const upserts = this.referenceLabels.apply(input.upserts, this.store)
+    const processTurns = new Set<number>()
     let structural = false
     const contentOnly: ChatConversationViewNode[] = []
     for (const node of upserts) {
@@ -718,6 +796,12 @@ export class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversa
         || locationIdentity(previous.location) !== locationIdentity(node.location)
       structural ||= nodeStructural
       if (!nodeStructural) contentOnly.push(node)
+      if (processPresentationInputChanged(previous as ChatNode | undefined, node as ChatNode, nodeStructural)) {
+        const previousTurn = previous === undefined ? undefined : locationCoordinates(previous.location).turn
+        const nextTurn = locationCoordinates(node.location).turn
+        if (previousTurn !== undefined) processTurns.add(previousTurn)
+        if (nextTurn !== undefined) processTurns.add(nextTurn)
+      }
     }
     this.store.upsert(upserts)
     if (structural) {
@@ -726,6 +810,7 @@ export class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversa
       this.locations.rebuild(this.order, this.store)
     }
     this.locations.touch(contentOnly)
+    this.store.updateProcesses(processTurns, this.locations)
     if (structural || input.timeline !== this.timeline) {
       this.navigation.rebuild(input.timeline, this.locations, this.store)
     } else {
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts
new file mode 100644
index 0000000000..1c9a4acf81
--- /dev/null
+++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts
@@ -0,0 +1,135 @@
+import type { ChatNode } from '../contract/chat-nodes.ts'
+import type {
+  ChatLocationNodeIndex, ChatNodeStore, ChatTurnProcessPresentation,
+} from '../contract/snapshot.ts'
+import { TURN_PROCESS_INDEPENDENT_KINDS } from '../contract/turn-process.ts'
+
+function nodeTurn(node: ChatNode | undefined): number | undefined {
+  const location = node?.location
+  return location?.kind === 'turn' || location?.kind === 'step' ? location.turn.turn : undefined
+}
+
+function samePresentation(
+  left: ChatTurnProcessPresentation | undefined,
+  right: ChatTurnProcessPresentation | undefined,
+): boolean {
+  return left === right || (left !== undefined && right !== undefined
+    && left.spec === right.spec
+    && left.turn === right.turn
+    && left.turnClosed === right.turnClosed
+    && left.hasExternalProcess === right.hasExternalProcess
+    && left.compactAnswer === right.compactAnswer)
+}
+
+function derivePresentation(
+  turn: number,
+  locations: ChatLocationNodeIndex,
+  nodes: ChatNodeStore,
+): ChatTurnProcessPresentation | undefined {
+  const keys = locations.getTurn(turn)
+  const control = keys
+    .map(key => nodes.get(key) as ChatNode | undefined)
+    .find((node): node is ChatNode<'turn-process'> => node?.kind === 'turn-process')
+  if (control === undefined) return undefined
+
+  const spec = control.data
+  const location = control.location
+  if (location.kind !== 'turn' && location.kind !== 'step') return undefined
+  let openingHumanAnchor: number | undefined
+  for (const key of keys) {
+    const node = nodes.get(key) as ChatNode | undefined
+    if ((node?.kind === 'user' || node?.kind === 'steering')
+      && node.anchorSeq < spec.controlAnchorSeq) {
+      openingHumanAnchor = Math.min(openingHumanAnchor ?? node.anchorSeq, node.anchorSeq)
+    }
+  }
+
+  let hasExternalProcess = false
+  let compactAnswer = true
+  for (const key of keys) {
+    const node = nodes.get(key) as ChatNode | undefined
+    if (node === undefined || node.kind === 'turn-process') continue
+    if ((node.kind === 'user' || node.kind === 'steering')
+      && (openingHumanAnchor === undefined || node.anchorSeq > openingHumanAnchor)
+      && (spec.answerAnchorSeq === null || node.anchorSeq < spec.answerAnchorSeq)) {
+      compactAnswer = false
+    }
+    if (TURN_PROCESS_INDEPENDENT_KINDS.has(node.kind)
+      || node.anchorSeq < spec.processStartSeq
+      || (spec.answerAnchorSeq !== null && node.anchorSeq >= spec.answerAnchorSeq)) continue
+    if (node.kind !== 'assistant-step' || spec.answerStep === null || node.data.step !== spec.answerStep) {
+      hasExternalProcess = true
+    }
+  }
+  return {
+    turn,
+    spec,
+    turnClosed: location.turn.status === 'closed',
+    hasExternalProcess,
+    compactAnswer,
+  }
+}
+
+/** Mutable projection of cross-Node process layout facts by Turn. */
+export class ChatTurnProcessProjector {
+  private presentations = new Map<number, ChatTurnProcessPresentation>()
+
+  /** @param node - current Chat Node. @returns its Turn's process presentation, when present. */
+  get(node: ChatNode | undefined): ChatTurnProcessPresentation | undefined {
+    const turn = nodeTurn(node)
+    return turn === undefined ? undefined : this.presentations.get(turn)
+  }
+
+  /**
+   * Replace every projected Turn.
+   * @param order - visible Chat Node order.
+   * @param locations - current Chat Location index.
+   * @param nodes - current Chat Node store.
+   * @returns Turns whose process presentation changed.
+   */
+  replace(
+    order: readonly string[],
+    locations: ChatLocationNodeIndex,
+    nodes: ChatNodeStore,
+  ): ReadonlySet<number> {
+    const turns = new Set<number>()
+    for (const key of order) {
+      const turn = nodeTurn(nodes.get(key) as ChatNode | undefined)
+      if (turn !== undefined) turns.add(turn)
+    }
+    const changed = new Set<number>()
+    for (const turn of new Set([...this.presentations.keys(), ...turns])) {
+      if (this.set(turn, turns.has(turn) ? derivePresentation(turn, locations, nodes) : undefined)) {
+        changed.add(turn)
+      }
+    }
+    return changed
+  }
+
+  /**
+   * Recompute selected Turns after incremental Node changes.
+   * @param turns - affected Turn numbers.
+   * @param locations - current Chat Location index.
+   * @param nodes - current Chat Node store.
+   * @returns Turns whose process presentation changed.
+   */
+  update(
+    turns: ReadonlySet<number>,
+    locations: ChatLocationNodeIndex,
+    nodes: ChatNodeStore,
+  ): ReadonlySet<number> {
+    const changed = new Set<number>()
+    for (const turn of turns) {
+      if (this.set(turn, derivePresentation(turn, locations, nodes))) changed.add(turn)
+    }
+    return changed
+  }
+
+  private set(turn: number, next: ChatTurnProcessPresentation | undefined): boolean {
+    const current = this.presentations.get(turn)
+    if (samePresentation(current, next)) return false
+    if (next === undefined) this.presentations.delete(turn)
+    else this.presentations.set(turn, next)
+    return true
+  }
+}
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-process.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-process.ts
index bacd360a57..bea22165b3 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/turn-process.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-process.ts
@@ -9,8 +9,7 @@ import type {} from '@deepseek-ai/dsh-tools/types'
 import { hasAssistantReplyContent } from '../contract/assistant-content.ts'
 import type { AssistantChatData, ChatNode, FinalAssistantChatData } from '../contract/chat-nodes.ts'
 import {
-  decodeTurnProcess, encodeTurnProcess, isSubagentDelegationTool,
-  type TurnProcessSignature, type TurnProcessSpec,
+  isSubagentDelegationTool, sameTurnProcessSpec, type TurnProcessSpec,
 } from '../contract/turn-process.ts'
 import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 import { toAssistantBlocks } from './event-projection.ts'
@@ -24,8 +23,8 @@ declare module '../contract/chat-nodes.ts' {
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   interface ConversationTurnDataMap {
-    /** Encoded process range and finalized answer boundary for this Turn. */
-    'turn-process': TurnProcessSignature
+    /** Process range and finalized answer boundary for this Turn. */
+    'turn-process': TurnProcessSpec
   }
 }
 
@@ -277,22 +276,21 @@ export const turnProcessDefinition: ConversationNodeDefinition<TurnProcessState>
       && latestStep?.status !== 'closed') return previous
     const spec = processSpec(state, turn)
     if (spec === null) return null
-    const value = encodeTurnProcess(spec)
     if (previous?.kind === 'turn'
       && previous.turn === spec.turn
       && previous.key === 'turn-process'
-      && previous.value === value) return previous
+      && sameTurnProcessSpec(previous.value, spec)) return previous
     return {
       kind: 'turn',
       turn: turn.turn,
       key: 'turn-process',
-      value,
+      value: spec,
     }
   },
   buildViewNode: (context) => {
     const turn = turnLocation(context)
-    const signature = turn?.data.get('turn-process')
-    if (turn === undefined || signature === undefined) return null
+    const data = turn?.data.get('turn-process')
+    if (turn === undefined || data === undefined) return null
     const current = context.current.get('chat') as ChatNode | null | undefined
     const state = context.state
     if (current?.kind === 'turn-process'
@@ -305,7 +303,6 @@ export const turnProcessDefinition: ConversationNodeDefinition<TurnProcessState>
       && turn.status !== 'closed'
       && turn.steps.at(-1)?.status !== 'closed'
       && current.location === (context.start?.location ?? context.matches[0]?.location)) return current
-    const data = decodeTurnProcess(signature)
     return chatNode(
       context,
       'turn-process',
diff --git a/packages/client/ui-chat/src/client/index.ts b/packages/client/ui-chat/src/client/index.ts
index da4d8de2e6..5cae4dccd7 100644
--- a/packages/client/ui-chat/src/client/index.ts
+++ b/packages/client/ui-chat/src/client/index.ts
@@ -15,7 +15,8 @@ export type {} from './conversation-nodes/turn-tail.ts'
 
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
-  AssistantTiming, ChatLocationNodeIndex, ChatNodeSource, ChatNodeStore, ChatSnapshot, ChatTurnNavigationIndex,
+  AssistantTiming, ChatLocationNodeIndex, ChatNodeProcessSource, ChatNodeSource, ChatNodeStore,
+  ChatSnapshot, ChatTurnNavigationIndex, ChatTurnProcessPresentation,
   CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode,
   LegacyConversationSlice, ModelRetryNode, PartialAssistant, RunningToolCall,
   SteeringMessageNode, ToolCallBlock, ToolResultNode, TurnErrorNode, TurnMaxTokensNode,
@@ -37,7 +38,7 @@ export type {
   TurnProcessOwnerProps, TurnTailOwnerProps, UseChat, UseChatNodeTurnData,
 } from './contract/slots.ts'
 export type {
-  TurnProcessGeneration, TurnProcessSignature, TurnProcessSpec,
+  TurnProcessSpec,
 } from './contract/turn-process.ts'
 export type { ChatKey } from './locale.ts'
 export type { ConversationContext, ConversationContextOriginKind } from './model/conversation-context.ts'
diff --git a/packages/client/ui-chat/src/client/stores.ts b/packages/client/ui-chat/src/client/stores.ts
index be2c411f7b..a0115445e2 100644
--- a/packages/client/ui-chat/src/client/stores.ts
+++ b/packages/client/ui-chat/src/client/stores.ts
@@ -1,6 +1,5 @@
 /** Per-Session Chat selection store shared by the transcript and details panel. */
 import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-store'
-import type { TurnProcessGeneration } from './contract/turn-process.ts'
 import type { ChatStoreState, SelectionTarget, TurnProcessViewEntry } from './contract/store.ts'
 
 type ChatActions = {
@@ -8,13 +7,13 @@ type ChatActions = {
   setTurnProcessOpen: (
     draft: ChatStoreState,
     turn: number,
-    generation: TurnProcessGeneration,
+    answerStep: number,
     open: boolean,
   ) => void
 }
 
 /**
- * Resolve any stored generation for one Turn.
+ * Resolve the manually expanded answer for one Turn.
  * @param state - Chat store snapshot.
  * @param turn - owning Turn.
  * @returns the Turn's stored entry, when present.
@@ -35,13 +34,13 @@ export function createChatStore(): EngineStoreHandle<ChatStoreState, ChatActions
     init: (): ChatStoreState => ({ selection: null, turnProcesses: [] }),
     actions: {
       select: (draft, target: SelectionTarget | null) => { draft.selection = target },
-      setTurnProcessOpen: (draft, turn, generation, open) => {
+      setTurnProcessOpen: (draft, turn, answerStep, open) => {
         const index = draft.turnProcesses.findIndex(entry => entry.turn === turn)
         if (!open) {
           if (index >= 0) draft.turnProcesses.splice(index, 1)
           return
         }
-        const next = { turn, generation } satisfies TurnProcessViewEntry
+        const next = { turn, answerStep } satisfies TurnProcessViewEntry
         if (index < 0) draft.turnProcesses.push(next)
         else draft.turnProcesses[index] = next
       },
diff --git a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
index d040ac0f2c..23d2384ec4 100644
--- a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
@@ -1,7 +1,8 @@
 // @vitest-environment jsdom
 import { describe, expect, it, vi } from 'vitest'
+import { act, render } from '@testing-library/react'
 import {
-  chatSnapshot, SlotTestRuntime, TestRemote, stubSettingsScope, usePinnedBrowserLanguages,
+  SlotTestRuntime, TestRemote, stubSettingsScope, usePinnedBrowserLanguages,
 } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
@@ -11,11 +12,14 @@ import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import {
   apply as applyConversation, inject as injectConversation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type {
+  ConversationLocationDataSource, ConversationLocationDataStore, ConversationTurnDataMap,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import {
   apply as applyChat, EMPTY_CHAT_SNAPSHOT, inject as injectChat,
 } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type {
-  ChatNodeTurnDataInjected, ChatSnapshot, TranscriptViewRowInjected, UseChat,
+  ChatNodeTurnDataInjected, ChatSnapshot, TranscriptViewRowInjected, UseChatNodeTurnData,
 } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { CHAT_SETTINGS_NAMESPACE, type ChatSettings } from '../src/chat-settings.ts'
 
@@ -149,42 +153,51 @@ describe('Chat apply wiring', () => {
     await b.runtime.dispose()
   })
 
-  it('binds Turn data through the Chat selector hook for Turn and Step locations', async () => {
+  it('binds Turn data directly to its keyed Location source', async () => {
     const b = await bench()
     const spec = b.runtime.slots.spec('conversation.chat.node') as unknown as {
       inject: ChatNodeTurnDataInjected
     }
-    let snapshot: ChatSnapshot = chatSnapshot()
-    const useChat = ((selector: (value: ChatSnapshot) => unknown) => selector(snapshot)) as UseChat
-    const useTurnData = spec.inject.hooks.turnData(
-      { useChat } as Parameters<typeof spec.inject.hooks.turnData>[0],
-      'node-1',
-    )
-    const data = { get: (key: string) => key === 'metric' ? 42 : undefined }
-    const turn = { data }
-    const emptySource = { getSnapshot: () => undefined, subscribe: () => () => {} }
-
-    snapshot = chatSnapshot({
-      nodes: { get: () => ({ location: { kind: 'turn', turn } }), values: () => [] } as never,
-    })
-    expect(useTurnData('metric')).toBe(42)
-    snapshot = chatSnapshot({
-      nodes: { get: () => ({ location: { kind: 'step', turn } }), values: () => [] } as never,
-    })
-    expect(useTurnData('metric')).toBe(42)
-    snapshot = chatSnapshot({
-      nodes: { get: () => ({ location: { kind: 'session' } }), values: () => [] } as never,
-    })
-    expect(useTurnData('metric')).toBeUndefined()
-    snapshot = chatSnapshot({
-      nodes: {
-        get: () => undefined,
-        source: () => emptySource,
-        values: () => [],
+    let value: number | undefined = 42
+    const listeners = new Set<() => void>()
+    const source: ConversationLocationDataSource<number | undefined> = {
+      getSnapshot: () => value,
+      subscribe: (listener) => {
+        listeners.add(listener)
+        return () => { listeners.delete(listener) }
       },
-    })
-    expect(useTurnData('metric')).toBeUndefined()
+    }
+    const data = {
+      get: () => value,
+      source: () => source,
+    } as unknown as ConversationLocationDataStore<ConversationTurnDataMap>
+    const useChat = vi.fn(() => { throw new Error('Turn data must not read the Chat snapshot') })
+    const useTurnData = spec.inject.hooks.turnData(
+      { useChat } as unknown as Parameters<typeof spec.inject.hooks.turnData>[0],
+      data,
+    )
+    const Probe = ({ useData }: { useData: UseChatNodeTurnData }) => (
+      <output>{useData('metric') ?? 'missing'}</output>
+    )
+    const view = render(<Probe useData={useTurnData} />)
 
+    expect(view.getByText('42')).toBeTruthy()
+    expect(useChat).not.toHaveBeenCalled()
+
+    act(() => {
+      value = 43
+      for (const listener of [...listeners]) listener()
+    })
+    expect(view.getByText('43')).toBeTruthy()
+
+    view.rerender(<Probe useData={spec.inject.hooks.turnData(
+      { useChat } as unknown as Parameters<typeof spec.inject.hooks.turnData>[0],
+      undefined,
+    )} />)
+    expect(view.getByText('missing')).toBeTruthy()
+    expect(useChat).not.toHaveBeenCalled()
+
+    view.unmount()
     await b.runtime.dispose()
   })
 })
diff --git a/packages/client/ui-chat/tests/chat-snapshot-fixture.client.ts b/packages/client/ui-chat/tests/chat-snapshot-fixture.client.ts
index ce29f6f529..6914089291 100644
--- a/packages/client/ui-chat/tests/chat-snapshot-fixture.client.ts
+++ b/packages/client/ui-chat/tests/chat-snapshot-fixture.client.ts
@@ -1,10 +1,11 @@
 import type {
-  AssistantChatData, AssistantMessageNode, ChatConversationViewNode, ChatSnapshot, ConversationNode,
-  ChatLocationNodeIndex, ChatNodeSource, ChatNodeStore, CompactionSummaryNode, FinalAssistantChatData,
-  LegacyConversationSlice, PartialAssistant, RunningToolCall, ToolCallBlock, TurnNavigationItem,
+  AssistantChatData, AssistantMessageNode, ChatConversationViewNode, ChatNode, ChatSnapshot, ConversationNode,
+  ChatLocationNodeIndex, ChatNodeProcessSource, ChatNodeSource, ChatNodeStore,
+  ChatTurnProcessPresentation, CompactionSummaryNode, FinalAssistantChatData, LegacyConversationSlice,
+  PartialAssistant, RunningToolCall, ToolCallBlock, TurnNavigationItem,
 } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type {
-  ConversationLocationDataStore, ConversationTurnDataMap, TurnLocation,
+  ConversationLocationDataSource, ConversationLocationDataStore, ConversationTurnDataMap, TurnLocation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { TurnTokenUsage } from '../src/client/contract/chat-nodes.ts'
 import { deriveTurnMetrics } from '../src/client/contract/turn-metrics.ts'
@@ -12,9 +13,10 @@ import {
   sameTurnNavigationItem, turnNavigationItem,
 } from '../src/client/conversation-nodes/turn-navigation.ts'
 import { orderedVisibleChatNodes } from '../src/client/conversation-nodes/chat-snapshot-builder.ts'
+import { ChatTurnProcessProjector } from '../src/client/conversation-nodes/turn-process-presentation.ts'
 import { hasAssistantReplyContent } from '../src/client/contract/assistant-content.ts'
 import {
-  encodeTurnProcess, isSubagentDelegationTool, TURN_PROCESS_INDEPENDENT_KINDS,
+  isSubagentDelegationTool, sameTurnProcessSpec, TURN_PROCESS_INDEPENDENT_KINDS,
   type TurnProcessSpec,
 } from '../src/client/contract/turn-process.ts'
 
@@ -24,6 +26,19 @@ function sameValues<T>(left: readonly T[], right: readonly T[]): boolean {
   return left.length === right.length && left.every((value, index) => value === right[index])
 }
 
+function cachedSource<Key, Source>(
+  sources: Map<Key, Source>,
+  key: Key,
+  create: () => Source,
+): Source {
+  let source = sources.get(key)
+  if (source === undefined) {
+    source = create()
+    sources.set(key, source)
+  }
+  return source
+}
+
 function sameFixtureLocation(
   left: ChatConversationViewNode['location'],
   right: ChatConversationViewNode['location'],
@@ -52,10 +67,7 @@ function nodeSource(node: ChatConversationViewNode): unknown {
   if (node.kind === 'tool-call') return (node.data as { readonly root: ToolCallBlock }).root
   if (node.kind === 'model-retry') return (node.data as { readonly current: unknown }).current
   if (node.kind === 'turn-tail') return (node.data as { readonly seq: number }).seq
-  if (node.kind === 'turn-process') {
-    const data = node.data as TurnProcessSpec
-    return encodeTurnProcess(data)
-  }
+  if (node.kind === 'turn-process') return node.data
   return node.data
 }
 
@@ -63,15 +75,17 @@ function toolCallName(call: ToolCallBlock): string | null {
   return 'name' in call ? call.name : call.call?.name ?? null
 }
 
-class FixtureNodeSource implements ChatNodeSource {
+class FixtureSource<Value> {
   private readonly listeners = new Set<() => void>()
+  private published: Value
 
   constructor(
-    private readonly store: FixtureNodeStore,
-    private readonly key: string,
-  ) {}
+    private readonly read: () => Value,
+  ) {
+    this.published = read()
+  }
 
-  readonly getSnapshot = (): ChatConversationViewNode | undefined => this.store.get(this.key)
+  readonly getSnapshot = (): Value => this.read()
 
   readonly subscribe = (listener: () => void): (() => void) => {
     this.listeners.add(listener)
@@ -79,14 +93,20 @@ class FixtureNodeSource implements ChatNodeSource {
   }
 
   publish(): void {
+    const next = this.getSnapshot()
+    if (this.published === next) return
+    this.published = next
     for (const listener of [...this.listeners]) listener()
   }
 }
 
 class FixtureNodeStore implements ChatNodeStore {
   private byKey = new Map<string, ChatConversationViewNode>()
-  private readonly sources = new Map<string, FixtureNodeSource>()
+  private readonly turnProcesses = new ChatTurnProcessProjector()
+  private readonly sources = new Map<string, FixtureSource<ChatConversationViewNode | undefined>>()
+  private readonly processSources = new Map<string, FixtureSource<ChatTurnProcessPresentation | undefined>>()
   private readonly dirtyKeys = new Set<string>()
+  private readonly dirtyProcessKeys = new Set<string>()
   private list: readonly ChatConversationViewNode[] = EMPTY
 
   get(key: string): ChatConversationViewNode | undefined {
@@ -94,12 +114,15 @@ class FixtureNodeStore implements ChatNodeStore {
   }
 
   source(key: string): ChatNodeSource {
-    let source = this.sources.get(key)
-    if (source === undefined) {
-      source = new FixtureNodeSource(this, key)
-      this.sources.set(key, source)
-    }
-    return source
+    return cachedSource(this.sources, key, () => new FixtureSource(() => this.get(key)))
+  }
+
+  processSource(key: string): ChatNodeProcessSource {
+    return cachedSource(this.processSources, key, () => new FixtureSource(() => this.process(key)))
+  }
+
+  process(key: string): ChatTurnProcessPresentation | undefined {
+    return this.turnProcesses.get(this.get(key) as ChatNode | undefined)
   }
 
   values(): readonly ChatConversationViewNode[] {
@@ -126,14 +149,27 @@ class FixtureNodeStore implements ChatNodeStore {
     this.list = sameValues(this.list, list) ? this.list : list
     const keys = new Set([...previous.keys(), ...next.keys()])
     for (const key of keys) {
-      if (previous.get(key) !== next.get(key)) this.dirtyKeys.add(key)
+      if (previous.get(key) !== next.get(key)) {
+        this.dirtyKeys.add(key)
+        this.dirtyProcessKeys.add(key)
+      }
+    }
+  }
+
+  replaceProcesses(order: readonly string[], locations: ChatLocationNodeIndex): void {
+    const changed = this.turnProcesses.replace(order, locations, this)
+    for (const turn of changed) {
+      for (const key of locations.getTurn(turn)) this.dirtyProcessKeys.add(key)
     }
   }
 
   publish(): void {
     const dirty = [...this.dirtyKeys]
+    const dirtyProcesses = [...this.dirtyProcessKeys]
     this.dirtyKeys.clear()
+    this.dirtyProcessKeys.clear()
     for (const key of dirty) this.sources.get(key)?.publish()
+    for (const key of dirtyProcesses) this.processSources.get(key)?.publish()
   }
 }
 
@@ -160,6 +196,8 @@ class FixtureLocationIndex implements ChatLocationNodeIndex {
 
 class FixtureTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
   private readonly values = new Map<string, unknown>()
+  private readonly sources = new Map<string, FixtureSource<unknown>>()
+  private readonly dirtyKeys = new Set<string>()
 
   get<Key extends Extract<keyof ConversationTurnDataMap, string>>(
     key: Key,
@@ -167,11 +205,26 @@ class FixtureTurnDataStore implements ConversationLocationDataStore<Conversation
     return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
   }
 
+  source<Key extends Extract<keyof ConversationTurnDataMap, string>>(
+    key: Key,
+  ): ConversationLocationDataSource<Readonly<ConversationTurnDataMap[Key]> | undefined> {
+    const source = cachedSource(this.sources, key, () => new FixtureSource(() => this.values.get(key)))
+    return source as ConversationLocationDataSource<Readonly<ConversationTurnDataMap[Key]> | undefined>
+  }
+
   set<Key extends Extract<keyof ConversationTurnDataMap, string>>(
     key: Key,
     value: ConversationTurnDataMap[Key],
   ): void {
+    if (this.values.get(key) === value) return
     this.values.set(key, value)
+    this.dirtyKeys.add(key)
+  }
+
+  publish(): void {
+    const dirty = [...this.dirtyKeys]
+    this.dirtyKeys.clear()
+    for (const key of dirty) this.sources.get(key)?.publish()
   }
 }
 
@@ -353,7 +406,7 @@ export function chatSnapshotFixture(input: {
     const processStart = inTurn.find(candidate => !TURN_PROCESS_INDEPENDENT_KINDS.has(candidate.kind))
       ?? controlAnchor
     const inlineReasoning = answer?.blocks.some(block => block.kind === 'reasoning' && block.text.trim() !== '') === true
-    const spec: TurnProcessSpec = {
+    const candidate: TurnProcessSpec = {
       turn: turnNumber,
       controlAnchorSeq: controlAnchor.anchorSeq,
       processStartSeq: processStart.anchorSeq,
@@ -373,7 +426,11 @@ export function chatSnapshotFixture(input: {
         return name !== null && isSubagentDelegationTool(name)
       }).length,
     }
-    dataStore.set('turn-process', encodeTurnProcess(spec))
+    const previousSpec = dataStore.get('turn-process')
+    const spec = previousSpec !== undefined && sameTurnProcessSpec(previousSpec, candidate)
+      ? previousSpec
+      : candidate
+    dataStore.set('turn-process', spec)
     const turn = turns.get(turnNumber)
     if (turn !== undefined) {
       nodes.push({
@@ -449,6 +506,7 @@ export function chatSnapshotFixture(input: {
     ? previous.locations
     : new FixtureLocationIndex()
   locations.replace(byTurn)
+  store.replaceProcesses(order, locations)
   const timeline = previous !== undefined
     && previous.legacy.turnTimings === legacy.turnTimings
     && previous.legacy.turnEnds === legacy.turnEnds
@@ -462,6 +520,7 @@ export function chatSnapshotFixture(input: {
     && derived.every((item, index) => sameTurnNavigationItem(kept[index], item))
     ? kept
     : derived
+  for (const data of turnData.values()) data.publish()
   store.publish()
   return {
     order,
diff --git a/packages/client/ui-chat/tests/chat-store.client.spec.ts b/packages/client/ui-chat/tests/chat-store.client.spec.ts
index e0f09bfda1..2be88ae9b8 100644
--- a/packages/client/ui-chat/tests/chat-store.client.spec.ts
+++ b/packages/client/ui-chat/tests/chat-store.client.spec.ts
@@ -24,26 +24,26 @@ describe('createChatStore', () => {
     expect(second.store.getSnapshot().selection).toBeNull()
   })
 
-  it('stores only manually expanded Turn-process generations', () => {
+  it('stores only manually expanded Turn-process answers', () => {
     const store = createChatStore().create()
-    store.actions.setTurnProcessOpen(2, '2|3', true)
-    expect(store.store.getSnapshot().turnProcesses).toEqual([{ turn: 2, generation: '2|3' }])
+    store.actions.setTurnProcessOpen(2, 3, true)
+    expect(store.store.getSnapshot().turnProcesses).toEqual([{ turn: 2, answerStep: 3 }])
 
-    store.actions.setTurnProcessOpen(2, '2|4', true)
-    expect(store.store.getSnapshot().turnProcesses).toEqual([{ turn: 2, generation: '2|4' }])
+    store.actions.setTurnProcessOpen(2, 4, true)
+    expect(store.store.getSnapshot().turnProcesses).toEqual([{ turn: 2, answerStep: 4 }])
 
-    store.actions.setTurnProcessOpen(2, '2|4', false)
+    store.actions.setTurnProcessOpen(2, 4, false)
     expect(store.store.getSnapshot().turnProcesses).toEqual([])
   })
 
   it('closes only the requested Turn-process entry', () => {
     const store = createChatStore().create()
-    store.actions.setTurnProcessOpen(2, '2|3', true)
-    store.actions.setTurnProcessOpen(3, '3|4', true)
+    store.actions.setTurnProcessOpen(2, 3, true)
+    store.actions.setTurnProcessOpen(3, 4, true)
 
-    store.actions.setTurnProcessOpen(2, '2|3', false)
-    store.actions.setTurnProcessOpen(9, '9|10', false)
+    store.actions.setTurnProcessOpen(2, 3, false)
+    store.actions.setTurnProcessOpen(9, 10, false)
 
-    expect(store.store.getSnapshot().turnProcesses).toEqual([{ turn: 3, generation: '3|4' }])
+    expect(store.store.getSnapshot().turnProcesses).toEqual([{ turn: 3, answerStep: 4 }])
   })
 })
diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
index 9ebacea1de..c0c5eb4ad5 100644
--- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
@@ -13,6 +13,9 @@ import type {
 import type {
   SessionListState, SessionSnapshot,
 } from '@deepseek-ai/dsh-api-session-controller/client'
+import type {
+  ConversationLocationDataStore, ConversationTurnDataMap,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { WorkspaceSnapshot } from '@deepseek-ai/dsh-api-workspace-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SessionPendingInteractionSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
@@ -23,6 +26,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { createChatStore } from '../src/client/stores.ts'
 import { ChatView } from '../src/client/chat/ChatView.tsx'
 import { ChatNodeSeat } from '../src/client/chat/ChatNodeSeat.tsx'
+import { useTurnDataValue } from '../src/client/chat/use-turn-data.ts'
 import { zh } from '../src/client/locale.ts'
 import { AssistantNodeView } from '../src/client/chat/AssistantNodeView.tsx'
 import { CommandNodeView, ManualCompactionNodeView } from '../src/client/chat/CommandNodeView.tsx'
@@ -35,7 +39,7 @@ import { TurnProcessNodeView } from '../src/client/chat/TurnProcessNodeView.tsx'
 import { SystemPromptNodeView } from '../src/client/chat/SystemPromptRow.tsx'
 import { formatRunDuration } from '../src/client/chat/message-chrome.ts'
 import { ChatSnapshotBuilder } from '../src/client/conversation-nodes/chat-snapshot-builder.ts'
-import { encodeTurnProcess } from '../src/client/contract/turn-process.ts'
+import type { TurnProcessSpec } from '../src/client/contract/turn-process.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
 
 afterEach(() => {
@@ -259,13 +263,9 @@ function makeHarness(
     if (nodeSlotOverride !== undefined) return nodeSlotOverride(key as never, owner as never, opts as never)
     if (key !== 'conversation.chat.node') return opts?.fallback ?? null
     const nodeOwner = owner as RoutedChatNodeOwner
-    const nodeKey = opts?.hookContext as string | undefined
-    const useTurnData: UseChatNodeTurnData = dataKey => props.useChat((snapshot) => {
-      const location = nodeKey === undefined ? undefined : snapshot.nodes.get(nodeKey)?.location
-      return location?.kind === 'turn' || location?.kind === 'step'
-        ? location.turn.data.get(dataKey)
-        : undefined
-    })
+    const turnData = opts?.hookContext as
+      ConversationLocationDataStore<ConversationTurnDataMap> | undefined
+    const useTurnData: UseChatNodeTurnData = dataKey => useTurnDataValue(turnData, dataKey)
     const nodeProps = <Kind extends ChatNode['kind']>(): ChatNodeViewProps<Kind> => (
       { ...props, ...nodeOwner, useTurnData } as unknown as ChatNodeViewProps<Kind>
     )
@@ -1635,10 +1635,11 @@ describe('ChatView', () => {
       || (process.location.kind !== 'turn' && process.location.kind !== 'step')
       || process.data.answerAnchorSeq === null) throw new Error('fixture lacks a completed Turn process')
     const turnData = process.location.turn.data as typeof process.location.turn.data & {
-      set(key: 'turn-process', value: ReturnType<typeof encodeTurnProcess>): void
+      set(key: 'turn-process', value: TurnProcessSpec): void
+      publish(): void
     }
     const partialSpec = { ...process.data, processStartSeq: process.data.answerAnchorSeq }
-    turnData.set('turn-process', encodeTurnProcess(partialSpec))
+    turnData.set('turn-process', partialSpec)
     const partialProcess = { ...process, data: partialSpec }
     const builder = new ChatSnapshotBuilder()
     const partial = builder.replace({
@@ -1651,7 +1652,7 @@ describe('ChatView', () => {
 
     const beforeKeys = partial.locations.getTurn(1)
     const completeSpec = { ...partialSpec, processStartSeq: 2 }
-    turnData.set('turn-process', encodeTurnProcess(completeSpec))
+    turnData.set('turn-process', completeSpec)
     const complete = builder.apply({
       upserts: [{ ...partialProcess, data: completeSpec }],
       timeline: source.timeline,
@@ -1663,7 +1664,10 @@ describe('ChatView', () => {
       'user', 'turn-process', 'context', 'assistant-step', 'assistant-step', 'turn-tail',
     ])
 
-    act(() => { h.set({ chat: complete, hasMore: false }) })
+    act(() => {
+      turnData.publish()
+      h.set({ chat: complete, hasMore: false })
+    })
     expect(turnProcessControl(view.container)?.getAttribute('aria-expanded')).toBe('false')
   })
 
diff --git a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
index ca637e1d4d..789e257ea5 100644
--- a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
+++ b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
@@ -16,7 +16,6 @@ import {
 import { isChunkRow, packChunkRuns, type ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { hasAssistantReplyContent } from '../src/client/contract/assistant-content.ts'
-import { decodeTurnProcess } from '../src/client/contract/turn-process.ts'
 import { assistantDefinition } from '../src/client/conversation-nodes/assistant.ts'
 import { chatViewDefinition } from '../src/client/conversation-nodes/chat-snapshot-builder.ts'
 import { commandDefinition } from '../src/client/conversation-nodes/command.ts'
@@ -257,10 +256,7 @@ describe('built-in conversation node Definitions', () => {
         chunk: { type: 'tool-call-delta', index: 2, id: 'call-1', name: 'read', argumentsDelta: '{}' },
       }),
     ])
-    const process = () => {
-      const signature = snapshot(value).timeline.turns.get(1)?.data.get('turn-process')
-      return signature === undefined ? undefined : decodeTurnProcess(signature)
-    }
+    const process = () => snapshot(value).timeline.turns.get(1)?.data.get('turn-process')
     expect(process()).toMatchObject({ processStartSeq: 4, answerAnchorSeq: null, answerStep: null })
     expect(node(snapshot(value), 'turn-process')?.data).toMatchObject({ answerAnchorSeq: null })
 
@@ -323,8 +319,8 @@ describe('built-in conversation node Definitions', () => {
       }),
       at(26, 'turn/end', { turn: 2, reason: { kind: 'interrupted' } }),
     ])
-    const recoveredSignature = snapshot(recovered).timeline.turns.get(2)?.data.get('turn-process')
-    expect(recoveredSignature === undefined ? undefined : decodeTurnProcess(recoveredSignature))
+    const recoveredProcess = snapshot(recovered).timeline.turns.get(2)?.data.get('turn-process')
+    expect(recoveredProcess)
       .toMatchObject({ answerStep: 2, answerAnchorSeq: 25.1 })
 
     const partialWindow = assembler([
@@ -333,8 +329,8 @@ describe('built-in conversation node Definitions', () => {
       }),
       at(31, 'step/end', { turn: 3, step: 4 }),
     ], true)
-    const partialSignature = snapshot(partialWindow).timeline.turns.get(3)?.data.get('turn-process')
-    expect(partialSignature === undefined ? undefined : decodeTurnProcess(partialSignature))
+    const partialProcess = snapshot(partialWindow).timeline.turns.get(3)?.data.get('turn-process')
+    expect(partialProcess)
       .toMatchObject({ processStartSeq: 30.1, answerAnchorSeq: 30.1, answerStep: 4 })
   })
 
@@ -365,8 +361,8 @@ describe('built-in conversation node Definitions', () => {
       at(11, 'step/end', { turn: 1, step: 2 }),
       at(12, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
     ])
-    const signature = snapshot(value).timeline.turns.get(1)?.data.get('turn-process')
-    expect(signature === undefined ? undefined : decodeTurnProcess(signature)).toMatchObject({
+    const process = snapshot(value).timeline.turns.get(1)?.data.get('turn-process')
+    expect(process).toMatchObject({
       messageCount: 1,
       toolCallCount: 1,
       subagentCount: 1,
@@ -592,10 +588,15 @@ describe('built-in conversation node Definitions', () => {
       }),
     ])
     const read = () => {
-      const signature = snapshot(value).timeline.turns.get(4)?.data.get('turn-process')
-      if (signature === undefined) throw new Error('turn-process signature is unavailable')
-      return decodeTurnProcess(signature)
+      const process = snapshot(value).timeline.turns.get(4)?.data.get('turn-process')
+      if (process === undefined) throw new Error('turn-process data is unavailable')
+      return process
     }
+    const streamingNode = node(snapshot(value), 'assistant-step')
+    if (streamingNode === undefined) throw new Error('streaming Assistant node is unavailable')
+    const processSource = snapshot(value).nodes.processSource(streamingNode.key)
+    let processNotifications = 0
+    processSource.subscribe(() => { processNotifications++ })
     const streaming = read()
     value.append(at(44, 'assistant/message', {
       turn: 4, step: 1, message: assistantMessage('settled-4', 'answer'),
@@ -606,6 +607,8 @@ describe('built-in conversation node Definitions', () => {
     expect(streaming).toMatchObject({ answerAnchorSeq: null, answerStep: null })
     expect(settled.answerAnchorSeq).toBe(44)
     expect(settled.answerStep).toBe(1)
+    expect(processNotifications).toBe(1)
+    expect(processSource.getSnapshot()?.spec.answerAnchorSeq).toBe(44)
   })
 
   it('reuses the open Turn-process projection across continuing Assistant chunks', () => {
@@ -618,8 +621,13 @@ describe('built-in conversation node Definitions', () => {
     ])
     const before = snapshot(value)
     const processNode = node(before, 'turn-process')
-    const processSignature = before.timeline.turns.get(1)?.data.get('turn-process')
+    const processData = before.timeline.turns.get(1)?.data.get('turn-process')
     const assistantNode = node(before, 'assistant-step')
+    if (assistantNode === undefined) throw new Error('Assistant node is unavailable')
+    const processSource = before.nodes.processSource(assistantNode.key)
+    const processPresentation = processSource.getSnapshot()
+    let processNotifications = 0
+    processSource.subscribe(() => { processNotifications++ })
 
     value.append(at(4, 'assistant/chunk', {
       turn: 1, step: 1, chunk: { type: 'reasoning-delta', index: 0, text: ' second' },
@@ -627,9 +635,49 @@ describe('built-in conversation node Definitions', () => {
     value.flush()
 
     const after = snapshot(value)
-    expect(after.timeline.turns.get(1)?.data.get('turn-process')).toBe(processSignature)
+    expect(after.timeline.turns.get(1)?.data.get('turn-process')).toBe(processData)
     expect(node(after, 'turn-process')).toBe(processNode)
     expect(node(after, 'assistant-step')).not.toBe(assistantNode)
+    expect(processSource.getSnapshot()).toBe(processPresentation)
+    expect(processNotifications).toBe(0)
+  })
+
+  it('notifies process sources only for Nodes in the changed Turn', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'assistant/message', {
+        turn: 1, step: 1, message: assistantMessage('answer-1', 'first answer'),
+      }, { surfaceOp: 'append' }),
+      at(4, 'step/end', { turn: 1, step: 1 }),
+      at(5, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+      at(6, 'turn/start', { turn: 2 }),
+      at(7, 'step/start', { turn: 2, step: 1 }),
+      at(8, 'assistant/chunk', {
+        turn: 2, step: 1, chunk: { type: 'reasoning-delta', index: 0, text: 'thinking' },
+      }),
+    ])
+    const assistants = snapshot(value).nodes.values()
+      .filter((candidate): candidate is ChatConversationViewNode & { data: AssistantChatData } => (
+        candidate.kind === 'assistant-step'
+      ))
+    const first = assistants.find(candidate => candidate.data.turn === 1)
+    const second = assistants.find(candidate => candidate.data.turn === 2)
+    if (first === undefined || second === undefined) throw new Error('Assistant fixtures are unavailable')
+    let firstNotifications = 0
+    let secondNotifications = 0
+    snapshot(value).nodes.processSource(first.key).subscribe(() => { firstNotifications++ })
+    snapshot(value).nodes.processSource(second.key).subscribe(() => { secondNotifications++ })
+
+    value.append(at(9, 'assistant/message', {
+      turn: 2, step: 1, message: assistantMessage('answer-2', 'second answer'),
+    }, { surfaceOp: 'append' }))
+    value.append(at(10, 'step/end', { turn: 2, step: 1 }))
+    value.append(at(11, 'turn/end', { turn: 2, reason: { kind: 'completed' } }))
+    value.flush()
+
+    expect(firstNotifications).toBe(0)
+    expect(secondNotifications).toBe(1)
   })
 
   it('anchors a streamed non-text answer from its block start', () => {
@@ -643,11 +691,11 @@ describe('built-in conversation node Definitions', () => {
     const current = snapshot(value)
     const process = node(current, 'turn-process')
     const answer = node(current, 'assistant-step')
-    const signature = current.timeline.turns.get(5)?.data.get('turn-process')
+    const processData = current.timeline.turns.get(5)?.data.get('turn-process')
 
     expect(process?.anchorSeq).toBe(51.9)
     expect(answer?.anchorSeq).toBe(52)
-    expect(signature === undefined ? undefined : decodeTurnProcess(signature))
+    expect(processData)
       .toMatchObject({ answerAnchorSeq: null, answerStep: null })
   })
 
diff --git a/packages/client/ui-conversation/src/client/contract/conversation.ts b/packages/client/ui-conversation/src/client/contract/conversation.ts
index 77808ba52c..4e053dcaff 100644
--- a/packages/client/ui-conversation/src/client/contract/conversation.ts
+++ b/packages/client/ui-conversation/src/client/contract/conversation.ts
@@ -1,10 +1,6 @@
 import type { SessionEventLike } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 
-/* oxlint-disable typescript/no-duplicate-type-constituents, typescript/no-redundant-type-constituents --
- * The unaugmented declaration-merge maps intentionally resolve to never in the Runtime program;
- * installed business packages supply their concrete keys in consuming Client programs. */
-
 /** Definition-local identity and lifecycle role extracted from one event. */
 export interface ConversationMatchResult {
   readonly id: string
@@ -17,6 +13,14 @@ export interface ConversationTurnDataMap {}
 /** Merge-extensible business values published against one Step. */
 export interface ConversationStepDataMap {}
 
+/** Observable value for one independently owned Location-data key. */
+export interface ConversationLocationDataSource<Value> {
+  /** @returns the current value. */
+  getSnapshot(): Value
+  /** @param listener - callback for value changes. @returns the unsubscribe function. */
+  subscribe(listener: () => void): () => void
+}
+
 /** Stable keyed reader for independently owned Location business values. */
 export interface ConversationLocationDataStore<DataMap extends object> {
   /**
@@ -25,6 +29,14 @@ export interface ConversationLocationDataStore<DataMap extends object> {
    * @returns latest immutable value, when its owning Context has published one.
    */
   get<Key extends keyof DataMap & string>(key: Key): Readonly<DataMap[Key]> | undefined
+  /**
+   * Observe one business value without subscribing to unrelated Location keys.
+   * @param key - declaration-merged business key.
+   * @returns identity-stable source for the current value.
+   */
+  source<Key extends keyof DataMap & string>(
+    key: Key,
+  ): ConversationLocationDataSource<Readonly<DataMap[Key]> | undefined>
 }
 
 interface ConversationLocationDataValue {
diff --git a/packages/client/ui-conversation/src/client/conversation/assembler.ts b/packages/client/ui-conversation/src/client/conversation/assembler.ts
index 2f752245c4..166fe6dd5f 100644
--- a/packages/client/ui-conversation/src/client/conversation/assembler.ts
+++ b/packages/client/ui-conversation/src/client/conversation/assembler.ts
@@ -303,6 +303,7 @@ export class ConversationNodeAssembler implements ConversationViewSnapshotStore
         })
         published = true
       }
+      this.locationIndex.publishData()
       this.replacePending = false
       this.dirty.clear()
       this.dirtyByTarget.clear()
@@ -326,6 +327,7 @@ export class ConversationNodeAssembler implements ConversationViewSnapshotStore
       })
       published = true
     }
+    this.locationIndex.publishData()
     this.dirty.clear()
     this.dirtyByTarget.clear()
     this.timelineDirty = false
diff --git a/packages/client/ui-conversation/src/client/conversation/location-index.ts b/packages/client/ui-conversation/src/client/conversation/location-index.ts
index 9b5f966bcd..41d3d745e8 100644
--- a/packages/client/ui-conversation/src/client/conversation/location-index.ts
+++ b/packages/client/ui-conversation/src/client/conversation/location-index.ts
@@ -1,11 +1,12 @@
 import {
   type SessionEventLike, type SessionEventLikeEntry,
 } from '@deepseek-ai/dsh-api-session-controller/client'
+import { notifySubscribers } from '@deepseek-ai/dsh-client-store'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type {
   ConversationLocation, ConversationLocationData,
-  ConversationLocationDataStore, ConversationStepDataMap, ConversationTimelineSnapshot,
-  ConversationTurnDataMap, StepLocation, TurnLocation,
+  ConversationLocationDataSource, ConversationLocationDataStore, ConversationStepDataMap,
+  ConversationTimelineSnapshot, ConversationTurnDataMap, StepLocation, TurnLocation,
 } from '../contract/conversation.ts'
 
 interface OwnedLocationData {
@@ -20,17 +21,57 @@ export interface ConversationLocationDataChange {
   readonly next: ConversationLocationData | null
 }
 
+class MutableLocationDataSource implements ConversationLocationDataSource<unknown> {
+  private readonly listeners = new Set<() => void>()
+  private published: unknown
+
+  constructor(
+    private readonly store: MutableLocationDataStore,
+    private readonly key: string,
+  ) {
+    this.published = store.get(key)
+  }
+
+  readonly getSnapshot = (): unknown => this.store.get(this.key)
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  publish(): void {
+    const next = this.getSnapshot()
+    if (this.published === next) return
+    this.published = next
+    notifySubscribers(this.listeners, `[ui-conversation] Location data ${this.key}`)
+  }
+}
+
 class MutableLocationDataStore {
   private entries = new Map<string, OwnedLocationData>()
+  private readonly sources = new Map<string, MutableLocationDataSource>()
+  private readonly dirtyKeys = new Set<string>()
+
+  constructor(private readonly markDirty: (store: MutableLocationDataStore) => void) {}
 
   get(key: string): unknown {
     return this.entries.get(key)?.value
   }
 
+  source(key: string): ConversationLocationDataSource<unknown> {
+    let source = this.sources.get(key)
+    if (source === undefined) {
+      source = new MutableLocationDataSource(this, key)
+      this.sources.set(key, source)
+    }
+    return source
+  }
+
   remove(owner: string, key: string): boolean {
     const current = this.entries.get(key)
     if (current?.owner !== owner) return false
     this.entries.delete(key)
+    this.changed(key)
     return true
   }
 
@@ -41,22 +82,32 @@ class MutableLocationDataStore {
     }
     if (current?.value === value) return false
     this.entries.set(key, { owner, value })
+    this.changed(key)
     return true
   }
 
   replace(entries: ReadonlyMap<string, OwnedLocationData>): boolean {
-    let changed = this.entries.size !== entries.size
-    if (!changed) {
-      for (const [key, value] of entries) {
-        const current = this.entries.get(key)
-        if (current?.owner !== value.owner || current.value !== value.value) {
-          changed = true
-          break
-        }
-      }
+    const changedKeys: string[] = []
+    for (const key of new Set([...this.entries.keys(), ...entries.keys()])) {
+      const current = this.entries.get(key)
+      const next = entries.get(key)
+      if (current?.owner !== next?.owner || current?.value !== next?.value) changedKeys.push(key)
     }
-    if (changed) this.entries = new Map(entries)
-    return changed
+    if (changedKeys.length === 0) return false
+    this.entries = new Map(entries)
+    for (const key of changedKeys) this.changed(key)
+    return true
+  }
+
+  publish(): void {
+    const dirty = [...this.dirtyKeys]
+    this.dirtyKeys.clear()
+    for (const key of dirty) this.sources.get(key)?.publish()
+  }
+
+  private changed(key: string): void {
+    this.dirtyKeys.add(key)
+    this.markDirty(this)
   }
 }
 
@@ -131,6 +182,7 @@ export class ConversationLocationIndex {
   private timeline: ConversationTimelineSnapshot = { turnOrder: [], turns: new Map() }
   private readonly turnDataStores = new Map<number, MutableLocationDataStore>()
   private readonly stepDataStores = new Map<string, MutableLocationDataStore>()
+  private readonly dirtyDataStores = new Set<MutableLocationDataStore>()
   private currentTurn: number | undefined
   private currentStep: number | undefined
 
@@ -192,6 +244,13 @@ export class ConversationLocationIndex {
     return changed
   }
 
+  /** Publish committed Location-data changes to their keyed sources. */
+  publishData(): void {
+    const dirty = [...this.dirtyDataStores]
+    this.dirtyDataStores.clear()
+    for (const store of dirty) store.publish()
+  }
+
   /**
    * Resolve the latest Location for one event.
    * @param event - event already ingested into this index.
@@ -481,17 +540,21 @@ export class ConversationLocationIndex {
   }
 
   private mutableTurnData(turn: number): MutableLocationDataStore {
-    const current = this.turnDataStores.get(turn) ?? new MutableLocationDataStore()
+    const current = this.turnDataStores.get(turn) ?? this.createDataStore()
     this.turnDataStores.set(turn, current)
     return current
   }
 
   private mutableStepData(key: string): MutableLocationDataStore {
-    const current = this.stepDataStores.get(key) ?? new MutableLocationDataStore()
+    const current = this.stepDataStores.get(key) ?? this.createDataStore()
     this.stepDataStores.set(key, current)
     return current
   }
 
+  private createDataStore(): MutableLocationDataStore {
+    return new MutableLocationDataStore(store => this.dirtyDataStores.add(store))
+  }
+
   private storeFor(data: ConversationLocationData): MutableLocationDataStore {
     return data.kind === 'turn'
       ? this.mutableTurnData(data.turn)
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index 102b385e8c..7b23cfa5bd 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -6,7 +6,8 @@ export { ConversationController, UnsupportedImageMediaTypeError } from './servic
 export type { IConversation } from './service.ts'
 export type {
   ConversationContextReader, ConversationLocation,
-  ConversationLocationData, ConversationLocationDataScope, ConversationLocationDataStore,
+  ConversationLocationData, ConversationLocationDataScope, ConversationLocationDataSource,
+  ConversationLocationDataStore,
   ConversationMatch, ConversationMatchResult, ConversationNodeContext,
   ConversationNodeDefinition, ConversationPreviousContext, ConversationPublication,
   ConversationStartMatch,
diff --git a/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts b/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
index 1a98abd0e1..641f887498 100644
--- a/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
@@ -6,7 +6,10 @@ import type { ChunkRowEvent } from '@deepseek-ai/dsh-api-session-controller/type
 import type { ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows'
 import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { ConversationNodeAssembler as RuntimeConversationNodeAssembler } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import {
+  ConversationLocationIndex,
+  ConversationNodeAssembler as RuntimeConversationNodeAssembler,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
   ConversationMatch, ConversationNodeContext,
   ConversationNodeDefinition, ConversationViewDefinition, ConversationViewNode,
@@ -162,6 +165,54 @@ function fallbackDefinition(start: () => string): ConversationNodeDefinition<str
 }
 
 describe('ConversationNodeAssembler', () => {
+  it('publishes Location data through stable per-key sources', () => {
+    const index = new ConversationLocationIndex()
+    const turnStart = at(1, 'turn/start', { turn: 1 })
+    const stepStart = at(2, 'step/start', { turn: 1, step: 1 })
+    index.rebuild([input(turnStart), input(stepStart)])
+    const location = index.locationOf(stepStart)
+    if (location.kind !== 'step') throw new Error('scope probe requires a Step Location')
+    const source = location.step.data.source('scope-probe')
+    const listener = vi.fn()
+    source.subscribe(listener)
+    const initial = { value: 1 }
+
+    expect(location.step.data.source('scope-probe')).toBe(source)
+    expect(source.getSnapshot()).toBeUndefined()
+    expect(index.replaceData([{
+      owner: 'scope-probe:1:1',
+      data: { kind: 'step', turn: 1, step: 1, key: 'scope-probe', value: initial },
+    }])).toBe(true)
+    expect(source.getSnapshot()).toBe(initial)
+    expect(listener).not.toHaveBeenCalled()
+
+    index.publishData()
+    expect(listener).toHaveBeenCalledOnce()
+    listener.mockClear()
+
+    index.replaceData([])
+    index.replaceData([{
+      owner: 'scope-probe:1:1',
+      data: { kind: 'step', turn: 1, step: 1, key: 'scope-probe', value: initial },
+    }])
+    index.publishData()
+    expect(listener).not.toHaveBeenCalled()
+
+    const changed = { value: 2 }
+    index.replaceData([{
+      owner: 'scope-probe:1:1',
+      data: { kind: 'step', turn: 1, step: 1, key: 'scope-probe', value: changed },
+    }])
+    index.publishData()
+    expect(source.getSnapshot()).toBe(changed)
+    expect(listener).toHaveBeenCalledOnce()
+
+    index.replaceData([])
+    index.publishData()
+    expect(source.getSnapshot()).toBeUndefined()
+    expect(listener).toHaveBeenCalledTimes(2)
+  })
+
   it('reports a replacement only when an active target has a registered builder', () => {
     const assembler = new RuntimeConversationNodeAssembler(
       new TestEventDefinitions([]),
diff --git a/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
index 62ea12276d..49a93b4ade 100644
--- a/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
@@ -13,7 +13,7 @@ import {
   ConversationNodeAssembler, UiConversation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
-  ConversationLocationDataStore, ConversationMatch, ConversationNodeDefinition,
+  ConversationLocationDataSource, ConversationLocationDataStore, ConversationMatch, ConversationNodeDefinition,
   ConversationStartMatch, ConversationTimelineSnapshot, ConversationTurnDataMap, ConversationViewDefinition,
   ConversationViewNode, TurnLocation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -38,6 +38,7 @@ afterEach(() => {
 
 class TestTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
   private readonly values = new Map<string, unknown>()
+  private readonly sources = new Map<string, ConversationLocationDataSource<unknown>>()
 
   get<Key extends Extract<keyof ConversationTurnDataMap, string>>(
     key: Key,
@@ -45,6 +46,17 @@ class TestTurnDataStore implements ConversationLocationDataStore<ConversationTur
     return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
   }
 
+  source<Key extends Extract<keyof ConversationTurnDataMap, string>>(
+    key: Key,
+  ): ConversationLocationDataSource<Readonly<ConversationTurnDataMap[Key]> | undefined> {
+    let source = this.sources.get(key)
+    if (source === undefined) {
+      source = { getSnapshot: () => this.get(key), subscribe: () => () => {} }
+      this.sources.set(key, source)
+    }
+    return source as ConversationLocationDataSource<Readonly<ConversationTurnDataMap[Key]> | undefined>
+  }
+
   set<Key extends Extract<keyof ConversationTurnDataMap, string>>(
     key: Key,
     value: ConversationTurnDataMap[Key],
diff --git a/packages/client/ui-tool/tests/tool-details-render.client.tsx b/packages/client/ui-tool/tests/tool-details-render.client.tsx
index 5488ac5470..29f8ef954f 100644
--- a/packages/client/ui-tool/tests/tool-details-render.client.tsx
+++ b/packages/client/ui-tool/tests/tool-details-render.client.tsx
@@ -51,6 +51,7 @@ export function toolChatSnapshot(
     nodes: {
       get: key => byKey.get(key),
       source: key => ({ getSnapshot: () => byKey.get(key), subscribe: () => () => {} }),
+      processSource: () => ({ getSnapshot: () => undefined, subscribe: () => () => {} }),
       values: () => nodes,
     },
     locations: {
diff --git a/packages/client/ui-trajectory/tests/layout.client.spec.tsx b/packages/client/ui-trajectory/tests/layout.client.spec.tsx
index fbb454decf..4b75d04d1e 100644
--- a/packages/client/ui-trajectory/tests/layout.client.spec.tsx
+++ b/packages/client/ui-trajectory/tests/layout.client.spec.tsx
@@ -31,6 +31,9 @@ interface LegacyConversationSlice {
   readonly nodes: readonly ConversationNode[]
 }
 
+const EMPTY_LOCATION_DATA_SOURCE = { getSnapshot: () => undefined, subscribe: () => () => {} }
+const EMPTY_LOCATION_DATA = { get: () => undefined, source: () => EMPTY_LOCATION_DATA_SOURCE }
+
 afterEach(cleanup)
 
 describe('TrajectoryTurnHeader', () => {
@@ -271,7 +274,7 @@ describe('deriveTrajectoryLayout', () => {
         blocks: [{ kind: 'text', text: 'second step' }],
       },
     ] as unknown as LegacyConversationSlice['nodes']
-    const data = { get: () => undefined }
+    const data = EMPTY_LOCATION_DATA
     const step = { turn: 1, step: 2, start: undefined, end: undefined, status: 'open' as const, data }
     const turn = {
       turn: 1, start: undefined, end: undefined, status: 'open' as const, steps: [step], data,
@@ -303,7 +306,7 @@ describe('deriveTrajectoryLayout', () => {
       kind: 'steering', messageId: 'steer-1', seq: 3, time: 3_000,
       content: [{ type: 'text', text: 'change direction' }], source: null,
     }] as unknown as LegacyConversationSlice['nodes']
-    const data = { get: () => undefined }
+    const data = EMPTY_LOCATION_DATA
     const step = { turn: 1, step: 2, start: undefined, end: undefined, status: 'open' as const, data }
     const turn = {
       turn: 1, start: undefined, end: undefined, status: 'open' as const, steps: [step], data,
diff --git a/packages/client/ui-trajectory/tests/snapshot-builder.client.spec.ts b/packages/client/ui-trajectory/tests/snapshot-builder.client.spec.ts
index f472455e55..c26486f7dd 100644
--- a/packages/client/ui-trajectory/tests/snapshot-builder.client.spec.ts
+++ b/packages/client/ui-trajectory/tests/snapshot-builder.client.spec.ts
@@ -5,6 +5,9 @@ import type {
 } from '../src/client/trajectory-contract.ts'
 import { TrajectorySnapshotBuilder } from '../src/client/trajectory-snapshot-builder.ts'
 
+const EMPTY_LOCATION_DATA_SOURCE = { getSnapshot: () => undefined, subscribe: () => () => {} }
+const EMPTY_LOCATION_DATA = { get: () => undefined, source: () => EMPTY_LOCATION_DATA_SOURCE }
+
 function assistantRequest(startSeq: number, step: number): Extract<RequestView, { purpose: 'assistant' }> {
   return {
     purpose: 'assistant',
@@ -30,7 +33,7 @@ function contribution(
 }
 
 function stepLocation(turn: number, step: number): TrajectoryRequestHeaderState['location'] {
-  const data = { get: () => undefined }
+  const data = EMPTY_LOCATION_DATA
   const stepLocation = {
     turn,
     step,
diff --git a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
index 101e5cd6d8..35575aeb4d 100644
--- a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
@@ -67,7 +67,12 @@ const emptyKeys: readonly string[] = []
 const emptyNodeSource = { getSnapshot: () => undefined, subscribe: () => () => {} }
 const chatState: ChatState = {
   order: emptyKeys,
-  nodes: { get: () => undefined, source: () => emptyNodeSource, values: () => [] },
+  nodes: {
+    get: () => undefined,
+    source: () => emptyNodeSource,
+    processSource: () => emptyNodeSource,
+    values: () => [],
+  },
   locations: { getTurn: () => emptyKeys, getStep: () => emptyKeys },
   navigation: { items: () => [] },
   timeline: { turnOrder: [], turns: new Map() },
diff --git a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
index e472e6d132..e44f492b10 100644
--- a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
@@ -66,7 +66,12 @@ const emptyKeys: readonly string[] = []
 const emptyNodeSource = { getSnapshot: () => undefined, subscribe: () => () => {} }
 const chatState: ChatState = {
   order: emptyKeys,
-  nodes: { get: () => undefined, source: () => emptyNodeSource, values: () => [] },
+  nodes: {
+    get: () => undefined,
+    source: () => emptyNodeSource,
+    processSource: () => emptyNodeSource,
+    values: () => [],
+  },
   locations: { getTurn: () => emptyKeys, getStep: () => emptyKeys },
   navigation: { items: () => [] },
   timeline: { turnOrder: [], turns: new Map() },

From 56684331c262b7a3d40efcc444ae901aa4dbc0eb Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:59:13 +0800
Subject: [PATCH 17/37] test(ui-chat): compare keyed snapshot values

---
 ...nversation-node-definitions.client.spec.ts | 41 ++++++++++++++++---
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
index 789e257ea5..eeb430ed0a 100644
--- a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
+++ b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
@@ -119,6 +119,37 @@ function node(value: ChatSnapshot, kind: string): ChatConversationViewNode | und
   return value.nodes.values().find(candidate => candidate.kind === kind)
 }
 
+function comparableSnapshot(value: ChatSnapshot) {
+  const nodes = value.nodes.values()
+  return {
+    order: value.order,
+    nodes: nodes.map(candidate => ({
+      ...candidate,
+      location: candidate.location.kind === 'step'
+        ? {
+          kind: 'step',
+          turn: candidate.location.turn.turn,
+          turnStatus: candidate.location.turn.status,
+          step: candidate.location.step.step,
+          stepStatus: candidate.location.step.status,
+        }
+        : candidate.location.kind === 'turn'
+          ? {
+            kind: 'turn',
+            turn: candidate.location.turn.turn,
+            turnStatus: candidate.location.turn.status,
+          }
+          : { kind: candidate.location.kind },
+    })),
+    processes: nodes.map(candidate => [
+      candidate.key,
+      value.nodes.processSource(candidate.key).getSnapshot(),
+    ]),
+    navigation: value.navigation.items(),
+    legacy: value.legacy,
+  }
+}
+
 function textMessage(id: string, text: string) {
   return {
     id,
@@ -904,7 +935,7 @@ describe('built-in conversation node Definitions', () => {
     expect(packedHistory.filter(input => input.event.type.startsWith('chunkrow/'))).toHaveLength(3)
     const packed = assembler(packedHistory)
 
-    expect(snapshot(packed)).toEqual(snapshot(scalar))
+    expect(comparableSnapshot(snapshot(packed))).toEqual(comparableSnapshot(snapshot(scalar)))
     const running = node(snapshot(packed), 'assistant-step')
     expect(running).toMatchObject({ anchorSeq: 6 })
     expect(running?.data).toMatchObject({
@@ -921,7 +952,7 @@ describe('built-in conversation node Definitions', () => {
       value.append(at(14, 'turn/end', { turn: 1, reason: { kind: 'completed' } }))
       value.flush()
     }
-    expect(snapshot(packed)).toEqual(snapshot(scalar))
+    expect(comparableSnapshot(snapshot(packed))).toEqual(comparableSnapshot(snapshot(scalar)))
     expect(node(snapshot(packed), 'turn-tail')?.anchorSeq).toBe(12.2)
 
     const partialHistory = [
@@ -931,7 +962,7 @@ describe('built-in conversation node Definitions', () => {
     ]
     const partialScalar = snapshot(assembler(partialHistory, true))
     const partialPacked = snapshot(assembler(packedInputs(partialHistory), true))
-    expect(partialPacked).toEqual(partialScalar)
+    expect(comparableSnapshot(partialPacked)).toEqual(comparableSnapshot(partialScalar))
     expect(node(partialPacked, 'assistant-step')?.data).toMatchObject({ status: 'interrupted' })
     expect(node(partialPacked, 'turn-tail')?.anchorSeq).toBe(12.2)
 
@@ -967,7 +998,7 @@ describe('built-in conversation node Definitions', () => {
     ]
     const finalizedScalar = snapshot(assembler(finalizedHistory))
     const finalizedPacked = snapshot(assembler(packedInputs(finalizedHistory)))
-    expect(finalizedPacked).toEqual(finalizedScalar)
+    expect(comparableSnapshot(finalizedPacked)).toEqual(comparableSnapshot(finalizedScalar))
     const finalNode = (node(finalizedPacked, 'assistant-step')?.data as AssistantChatData).finalNode
     expect(finalNode?.timing?.firstTokenTime).toBe(1_999)
 
@@ -989,7 +1020,7 @@ describe('built-in conversation node Definitions', () => {
     ]
     const namedToolScalar = snapshot(assembler(namedToolHistory))
     const namedToolPacked = snapshot(assembler(packedInputs(namedToolHistory)))
-    expect(namedToolPacked).toEqual(namedToolScalar)
+    expect(comparableSnapshot(namedToolPacked)).toEqual(comparableSnapshot(namedToolScalar))
     const namedTool = (node(namedToolPacked, 'assistant-step')?.data as AssistantChatData).finalNode
     expect(namedTool?.timing?.firstTokenTime).toBe(4_000)
   })

From f808112ec8cf2849b196a6e38c501944a49a867f Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:59:44 +0800
Subject: [PATCH 18/37] perf(ui-chat): derive user action reveal in CSS

---
 .../client/chat/MessageIconActions.module.css | 21 ++++++++++++-------
 .../ui-chat/src/client/chat/MessageItem.tsx   | 17 ++-------------
 .../chat-font-axis-styles.client.spec.ts      | 18 +++++++++++-----
 .../ui-chat/tests/chat-view.client.spec.tsx   |  8 ++-----
 4 files changed, 31 insertions(+), 33 deletions(-)

diff --git a/packages/client/ui-chat/src/client/chat/MessageIconActions.module.css b/packages/client/ui-chat/src/client/chat/MessageIconActions.module.css
index 2f6ec71c85..ad8f6edb6c 100644
--- a/packages/client/ui-chat/src/client/chat/MessageIconActions.module.css
+++ b/packages/client/ui-chat/src/client/chat/MessageIconActions.module.css
@@ -30,19 +30,26 @@
   white-space: nowrap;
 }
 
-/* Row containers (user rows and turn tails) opt in with
-   data-actions-reveal='hover': every row but the latest of its kind reveals
-   the entire actions row (icons and text) on hover or focus-within, while the
-   latest ('always') keeps its row visible — no rule matches it. Opacity keeps
-   the layout stable, and devices without hover keep the row visible. */
+/* Earlier user-authored flow rows and opted-in turn tails reveal the complete
+   actions row on hover or focus-within. Opacity keeps layout stable, and
+   devices without hover keep every row visible. */
 @media (hover: hover) {
-  [data-actions-reveal='hover'] .actions {
+  [data-actions-reveal='hover'] .actions,
+  :is([data-chat-flow-kind='user'], [data-chat-flow-kind='steering']):has(
+    ~ :is([data-chat-flow-kind='user'], [data-chat-flow-kind='steering'])
+  ) .actions {
     opacity: 0;
     transition: opacity 80ms ease;
   }
 
   [data-actions-reveal='hover']:hover .actions,
-  [data-actions-reveal='hover']:focus-within .actions {
+  [data-actions-reveal='hover']:focus-within .actions,
+  :is([data-chat-flow-kind='user'], [data-chat-flow-kind='steering']):has(
+    ~ :is([data-chat-flow-kind='user'], [data-chat-flow-kind='steering'])
+  ):hover .actions,
+  :is([data-chat-flow-kind='user'], [data-chat-flow-kind='steering']):has(
+    ~ :is([data-chat-flow-kind='user'], [data-chat-flow-kind='steering'])
+  ):focus-within .actions {
     opacity: 1;
   }
 }
diff --git a/packages/client/ui-chat/src/client/chat/MessageItem.tsx b/packages/client/ui-chat/src/client/chat/MessageItem.tsx
index 9846a472d6..07e9fb32a0 100644
--- a/packages/client/ui-chat/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-chat/src/client/chat/MessageItem.tsx
@@ -148,7 +148,7 @@ function TurnMaxTokensItem({ t }: {
 
 /** Right-aligned bubble shared by user and steering rows. */
 function UserStyleBubble({
-  content, renderMessageImages, actions, pending = false, echo = false, referenceLabels = [], previewImages, reveal = 'always', t,
+  content, renderMessageImages, actions, pending = false, echo = false, referenceLabels = [], previewImages, t,
 }: {
   content: readonly unknown[]
   renderMessageImages: ChatNodeOwnerProps['renderMessageImages']
@@ -162,8 +162,6 @@ function UserStyleBubble({
   referenceLabels?: readonly string[]
   /** Local submission-echo previews replacing the content-derived image group. */
   previewImages?: readonly MessageImageSource[]
-  /** Whole actions-row visibility: earlier rows reveal on hover, the latest stays shown (turn tails' gate). */
-  reveal?: 'always' | 'hover'
   t: ChatViewSlotProps['t']
 }): ReactNode {
   const { text, images: contentImages, rest } = contentParts(content)
@@ -175,7 +173,6 @@ function UserStyleBubble({
       className={css.userRow}
       data-pending-steering={pending || undefined}
       data-submission-echo={echo || undefined}
-      data-actions-reveal={reveal}
     >
       <div className={css.userStack}>
         {renderMessageImages({ images, align: 'end' })}
@@ -274,24 +271,14 @@ export function PendingSubmissionBubble({ submission, renderMessageImages, t }:
 
 /** User and admitted-steering keyed Chat renderer. */
 export const UserMessageNodeView = memo(function UserMessageNodeView({
-  node, renderMessageImages, useChat, t,
+  node, renderMessageImages, t,
 }: ChatNodeViewProps<'user' | 'steering'>) {
   const data = node.data
-  // The transcript's last user-authored row keeps its actions row shown, the
-  // same recency gate turn tails use; earlier rows reveal on hover.
-  const isLatestUserRow = useChat((snapshot) => {
-    for (let index = snapshot.order.length - 1; index >= 0; index -= 1) {
-      const candidate = snapshot.nodes.get(snapshot.order[index] ?? '')
-      if (candidate?.kind === 'user' || candidate?.kind === 'steering') return candidate.key === node.key
-    }
-    return true
-  })
   return (
     <UserStyleBubble
       content={data.content}
       renderMessageImages={renderMessageImages}
       {...data.referenceLabels === undefined ? {} : { referenceLabels: data.referenceLabels }}
-      reveal={isLatestUserRow ? 'always' : 'hover'}
       t={t}
       actions={text => (
         <MessageIconActions
diff --git a/packages/client/ui-chat/tests/chat-font-axis-styles.client.spec.ts b/packages/client/ui-chat/tests/chat-font-axis-styles.client.spec.ts
index 4bbfe4dbba..cf84408caf 100644
--- a/packages/client/ui-chat/tests/chat-font-axis-styles.client.spec.ts
+++ b/packages/client/ui-chat/tests/chat-font-axis-styles.client.spec.ts
@@ -137,14 +137,22 @@ describe('chat flow font-size axis', () => {
     // no-hover devices keep the row visible. 'always' has no rule at all —
     // absence, not an override, keeps the latest turn's row shown.
     const css = read('MessageIconActions.module.css')
-    expect(declarationsFrom(css, "[data-actions-reveal='hover'] .actions"))
-      .toEqual(expect.arrayContaining(['opacity: 0']))
-    expect(css).toMatch(
-      /\[data-actions-reveal='hover'\]:hover \.actions,\s*\[data-actions-reveal='hover'\]:focus-within \.actions \{\s*opacity: 1/,
-    )
+    expect(css).toContain("[data-actions-reveal='hover'] .actions,")
+    expect(css).toMatch(/\) \.actions \{\s*opacity: 0/)
+    expect(css).toContain("[data-actions-reveal='hover']:hover .actions,")
+    expect(css).toContain("[data-actions-reveal='hover']:focus-within .actions,")
+    expect(css).toMatch(/\):focus-within \.actions \{\s*opacity: 1/)
     expect(css).not.toContain("[data-actions-reveal='always']")
   })
 
+  it('uses flow sibling selectors to reveal only the latest user-authored row', () => {
+    const css = read('MessageIconActions.module.css')
+    const userKinds = ":is([data-chat-flow-kind='user'], [data-chat-flow-kind='steering'])"
+    expect(css).toContain(`${userKinds}:has(\n    ~ ${userKinds}\n  ) .actions`)
+    expect(css).toContain('):hover .actions')
+    expect(css).toContain('):focus-within .actions')
+  })
+
   it('the interrupted-turn tag stays fixed like the dense token variants', () => {
     // 11px would fall to an illegible 9px at the 12px floor; the tag is
     // exempt from the axis the same way small/code tokens are.
diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
index c0c5eb4ad5..eac7cf3a8b 100644
--- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
@@ -1818,7 +1818,7 @@ describe('ChatView', () => {
     expect(view.queryByText(/首 token|tok\/s/)).toBeNull()
   })
 
-  it('user rows and turn tails both gate the whole actions row by recency', () => {
+  it('keeps only the latest turn tail actions permanently visible', () => {
     const h = makeHarness({
       nodes: [
         user(1, 'hi'),
@@ -1833,15 +1833,11 @@ describe('ChatView', () => {
       turnEnds: new Map([[1, 3], [2, 6]]),
     })
     const view = render(<h.ChatView {...h.props} />)
-    // The last user-authored row and the latest turn's tail stay shown;
-    // every earlier row of either kind reveals on hover.
     const tails = view.container.querySelectorAll('[data-turn-tail]')
     expect(new Map([...tails].map(tail => [
       tail.getAttribute('data-turn-tail'), tail.getAttribute('data-actions-reveal'),
     ]))).toEqual(new Map([['1', 'hover'], ['2', 'always']]))
-    const userRows = [...view.container.querySelectorAll('[data-actions-reveal]')]
-      .filter(row => row.getAttribute('data-turn-tail') === null)
-    expect(userRows.map(row => row.getAttribute('data-actions-reveal'))).toEqual(['hover', 'always'])
+    expect(view.container.querySelectorAll('[data-chat-flow-kind="user"]')).toHaveLength(2)
   })
 
   it('the run-time label is withheld when the turn start is outside the window', () => {

From aad1ce0c685089dee8771325afa5910bd052038d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:00:03 +0800
Subject: [PATCH 19/37] perf(ui-chat): retain the stats resize observer

---
 .../ui-chat/src/client/chat/StatsLine.tsx     | 67 +++++++++++--------
 .../ui-chat/tests/chat-stats.client.spec.tsx  | 19 ++++++
 2 files changed, 59 insertions(+), 27 deletions(-)

diff --git a/packages/client/ui-chat/src/client/chat/StatsLine.tsx b/packages/client/ui-chat/src/client/chat/StatsLine.tsx
index 25c9516b02..170ffec956 100644
--- a/packages/client/ui-chat/src/client/chat/StatsLine.tsx
+++ b/packages/client/ui-chat/src/client/chat/StatsLine.tsx
@@ -2,7 +2,7 @@
 // Mounted on 'conversation.composer.dock' so it sticks with the composer in the
 // active conversation scrollport (see ConversationRoot data-conversation-scroll).
 
-import { Fragment, memo, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { Fragment, memo, useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { UseProjection } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
@@ -122,6 +122,44 @@ export interface StatsLineProps {
   t: ChatViewSlotProps['t']
 }
 
+/** Render and measure one non-empty statistics line. */
+const StatsLineContent = memo(function StatsLineContent({
+  groups,
+  line,
+}: {
+  readonly groups: readonly string[]
+  readonly line: string
+}) {
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const [truncated, setTruncated] = useState(false)
+  const measure = useCallback(() => {
+    const el = rootRef.current
+    if (el === null) return
+    const next = el.scrollWidth > el.clientWidth
+    setTruncated(current => current === next ? current : next)
+  }, [])
+  useLayoutEffect(() => {
+    const el = rootRef.current
+    if (el === null || typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(measure)
+    observer.observe(el)
+    return () => { observer.disconnect() }
+  }, [measure])
+  useLayoutEffect(measure, [line, measure])
+  return (
+    <Tooltip label={line} side="top" delayMs={500} disabled={!truncated}>
+      <div ref={rootRef} className={css.root}>
+        {groups.map((group, i) => (
+          <Fragment key={group}>
+            {i > 0 && <><span className={css.sep} aria-hidden>|</span>{' '}</>}
+            <span>{group}</span>
+          </Fragment>
+        ))}
+      </div>
+    </Tooltip>
+  )
+})
+
 export const StatsLine = memo(function StatsLine({ useChat, useProjection, t }: StatsLineProps) {
   const settledNodes = useChat(s => s.legacy.nodes)
   const usage = useProjection('tokenUsage')
@@ -166,31 +204,6 @@ export const StatsLine = memo(function StatsLine({ useChat, useProjection, t }:
     }))
   }
   const line = groups.join(' | ')
-  // The row elides with ellipsis when overlong; a delayed hover tooltip carries
-  // the full line, enabled only while content is actually clipped.
-  const rootRef = useRef<HTMLDivElement | null>(null)
-  const [truncated, setTruncated] = useState(false)
-  useLayoutEffect(() => {
-    const el = rootRef.current
-    if (el === null) return
-    const measure = () => { setTruncated(el.scrollWidth > el.clientWidth) }
-    measure()
-    if (typeof ResizeObserver === 'undefined') return
-    const observer = new ResizeObserver(measure)
-    observer.observe(el)
-    return () => { observer.disconnect() }
-  }, [line])
   if (groups.length === 0) return null
-  return (
-    <Tooltip label={line} side="top" delayMs={500} disabled={!truncated}>
-      <div ref={rootRef} className={css.root}>
-        {groups.map((group, i) => (
-          <Fragment key={group}>
-            {i > 0 && <><span className={css.sep} aria-hidden>|</span>{' '}</>}
-            <span>{group}</span>
-          </Fragment>
-        ))}
-      </div>
-    </Tooltip>
-  )
+  return <StatsLineContent groups={groups} line={line} />
 })
diff --git a/packages/client/ui-chat/tests/chat-stats.client.spec.tsx b/packages/client/ui-chat/tests/chat-stats.client.spec.tsx
index 01e17ed71e..e35aa297dc 100644
--- a/packages/client/ui-chat/tests/chat-stats.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-stats.client.spec.tsx
@@ -162,6 +162,25 @@ describe('StatsLine', () => {
     return { uncachedInputTokens, outputTokens: 1, cacheReadTokens, cacheWriteTokens: 0 }
   }
 
+  it('mounts one size observer only while a non-empty line exists', () => {
+    let observers = 0
+    class CountingResizeObserver {
+      constructor(_callback: ResizeObserverCallback) { observers++ }
+      observe(): void {}
+      disconnect(): void {}
+    }
+    vi.stubGlobal('ResizeObserver', CountingResizeObserver)
+    const { set, source } = makeSource()
+    render(<StatsLine {...props(source, {})} />)
+    expect(observers).toBe(0)
+
+    act(() => { set({ nodes: [assistant(1, 1)] }) })
+    expect(observers).toBe(1)
+
+    act(() => { set({ nodes: [assistant(1, 1), assistant(2, 1)] }) })
+    expect(observers).toBe(1)
+  })
+
   it('renders the grouped stats row and hides a brand-new empty session', () => {
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
     const view = render(<StatsLine {...props(source)} />)

From ebe9f50b44ee229cca96c07269d32e7d44ca3d21 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:00:23 +0800
Subject: [PATCH 20/37] perf(ui-chat): contain collapsed reasoning layout

---
 .../client/ui-chat/src/client/chat/ReasoningRow.module.css | 5 +++++
 packages/client/ui-chat/src/client/chat/ReasoningRow.tsx   | 7 ++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css b/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
index 50056b0d0c..489d431236 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
@@ -3,6 +3,11 @@
   flex-direction: column;
 }
 
+.root:not([data-expanded]) {
+  contain: size layout;
+  height: calc(24px + var(--dsh-content-font-delta, 0px));
+}
+
 .row {
   position: relative;
   overflow: hidden;
diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
index b3a6e2a9b7..81b10a7c49 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
@@ -28,7 +28,12 @@ export function ReasoningRow({ text, running, t }: { text: string; running: bool
   const summary = running ? latestLine(text) : firstLine(text)
 
   return (
-    <div className={css.root} data-variant="think" data-state={running ? 'running' : 'ok'}>
+    <div
+      className={css.root}
+      data-variant="think"
+      data-state={running ? 'running' : 'ok'}
+      data-expanded={expanded || undefined}
+    >
       {running && <span className={a11yCss.visuallyHidden}>{t('row.running')}</span>}
       <DisclosureRow
         rowClassName={css.row}

From 59342011090af023e3bab4d0fa2f8e057f681b9e Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:01:18 +0800
Subject: [PATCH 21/37] perf(conversation): publish streaming updates every
 three frames

---
 ...-08-09-client-conversation-node-assembly.i18n.yaml |  4 ++--
 .../2026-08-09-client-conversation-node-assembly.md   |  6 +++---
 ...2026-08-09-client-conversation-node-assembly.zh.md |  6 +++---
 .../src/client/contract/conversation.ts               |  2 +-
 .../src/client/conversation/assembly.ts               |  8 +++++---
 .../tests/conversation-registry.client.spec.ts        | 11 +++++++++--
 6 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index e9826ffc02..7d17815ffa 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 5efb808af3d551ab65304d5a8d69947f63f25a05
-2026-08-09-client-conversation-node-assembly.zh.md: 870598b46d156d3399d874d6fd1cfc18d5dc3ada
+2026-08-09-client-conversation-node-assembly.md: 28b21480de60a17fdc141c3a2b20271f2bdaedbf
+2026-08-09-client-conversation-node-assembly.zh.md: f2ae267a1d385283b6fc51396d24b42ec2300469
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 5efb808af3..28b21480de 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -125,12 +125,12 @@ The Assembler does not use State reference equality to decide publication or pro
 | Return value | Behavior |
 |---|---|
 | `immediate` | Request a notification and flush in the current microtask |
-| `animation-frame` | Coalesce high-frequency updates into materialization after two browser animation frames |
+| `animation-frame` | Coalesce high-frequency updates into materialization after three browser animation frames |
 | `none` | Do not schedule a flush for this Match; retain its State and dirty marker |
 
 Omitting `publication()` means `immediate`. Assistant token deltas and packed runs use `animation-frame`, invisible Inbox Contexts use `none`, and finals, dependency replays, and Location boundaries publish the latest result through an immediate path.
 
-Every live delta during the two-frame interval still executes `update()`, while one historical packed run executes one batch `update()`. Location-data publication, `buildViewNode()`, View Builder work, and React snapshot notification are coalesced; no fragments are lost. An immediate publication cancels a pending frame interval and flushes the latest State without delay.
+Every live delta during the three-frame interval still executes `update()`, while one historical packed run executes one batch `update()`. Location-data publication, `buildViewNode()`, View Builder work, and React snapshot notification are coalesced; no fragments are lost. An immediate publication cancels a pending frame interval and flushes the latest State without delay.
 
 #### `buildLocationData(context, scope)`
 
@@ -414,7 +414,7 @@ Initial tail, older prepend, and live append share one set of Context invariants
 
 Append does not scan historical Contexts; prepend replays only Contexts whose Matches, Locations, or Reader answers actually changed. A structural Chat change may still recompute visible order and indexes, but does not rerun unrelated business folds or replace unchanged Node identity.
 
-Separating State updates from publication cadence folds every live Assistant delta and each historical packed run while materializing at most once per two animation frames. The Assistant view reads the same projection that the preceding Step Location phase installed. Turn Process returns its existing open data and Node for continuing Assistant chunks without deriving or encoding them again, and Turn Tail defers its complete-Match scan until `turn/end`. Step or Turn close and final Events immediately publish the latest State.
+Separating State updates from publication cadence folds every live Assistant delta and each historical packed run while materializing at most once per three animation frames. The Assistant view reads the same projection that the preceding Step Location phase installed. Turn Process returns its existing open data and Node for continuing Assistant chunks without deriving or encoding them again, and Turn Tail defers its complete-Match scan until `turn/end`. Step or Turn close and final Events immediately publish the latest State.
 
 An inactive target retains Definition State and a target Context index but no builder, materialized Nodes, or snapshot. The mounted built-in or third-party View activates its own target through normal subscription; previously opened targets continue receiving incremental updates.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index 870598b46d..f2ae267a1d 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -125,12 +125,12 @@ Assembler 不以 State 引用相等判断是否需要发布或传播。每次成
 | 返回值 | 行为 |
 |---|---|
 | `immediate` | 请求当前 microtask 通知与 flush |
-| `animation-frame` | 跨过两个浏览器 animation frame 后，把多条高频更新合并为一次 materialization |
+| `animation-frame` | 跨过三个浏览器 animation frame 后，把多条高频更新合并为一次 materialization |
 | `none` | 本 Match 不主动安排 flush，State 和 dirty 标记仍被保留 |
 
 省略 `publication()` 等于 `immediate`。Assistant token delta 与 packed run 使用 `animation-frame`，不可见 Inbox Context 使用 `none`，final、依赖 replay 和 Location 边界会以 immediate 路径发布最新结果。
 
-两帧间隔内的每条 live delta 仍执行 `update()`，一个历史 packed run 则执行一次 batch `update()`；Location-data publication、`buildViewNode()`、View Builder 与 React snapshot 通知会合并执行，不会丢失 fragment。immediate publication 会取消等待中的帧间隔，并立即发布最新 State。
+三帧间隔内的每条 live delta 仍执行 `update()`，一个历史 packed run 则执行一次 batch `update()`；Location-data publication、`buildViewNode()`、View Builder 与 React snapshot 通知会合并执行，不会丢失 fragment。immediate publication 会取消等待中的帧间隔，并立即发布最新 State。
 
 #### `buildLocationData(context, scope)`
 
@@ -414,7 +414,7 @@ Host 业务 package 把自己的持久 Event 成员 declaration-merge 到 `@deep
 
 Append 不扫描历史 Context；prepend 只 replay Match、Location 或 Reader 答案真正受影响的 Context。Chat 结构变化仍可能重算 visible order 和索引，但不会重跑无关业务 fold 或替换未变化 Node identity。
 
-State update 与 publication cadence 分离后，Assistant 的每条 live delta 与每个历史 packed run 都会被 fold，同时每两个 animation frame 最多 materialize 一次。Assistant view 读取前置 Step Location 阶段刚写入的同一 projection。Turn Process 对持续 Assistant chunk 直接返回已有 open data 和 Node，不再重复派生或编码；Turn Tail 到 `turn/end` 才执行完整 Match 扫描。Step/Turn close 与 final Event 会立即发布最新 State。
+State update 与 publication cadence 分离后，Assistant 的每条 live delta 与每个历史 packed run 都会被 fold，同时每三个 animation frame 最多 materialize 一次。Assistant view 读取前置 Step Location 阶段刚写入的同一 projection。Turn Process 对持续 Assistant chunk 直接返回已有 open data 和 Node，不再重复派生或编码；Turn Tail 到 `turn/end` 才执行完整 Match 扫描。Step/Turn close 与 final Event 会立即发布最新 State。
 
 inactive target 会保留 Definition State 和 target Context 索引，但不保留 builder、已物化 Node 或 snapshot。已挂载的内建或第三方 View 通过正常订阅激活自己的 target；已经打开的 target 则继续接收增量更新。
 
diff --git a/packages/client/ui-conversation/src/client/contract/conversation.ts b/packages/client/ui-conversation/src/client/contract/conversation.ts
index 4e053dcaff..d37ace2fd4 100644
--- a/packages/client/ui-conversation/src/client/contract/conversation.ts
+++ b/packages/client/ui-conversation/src/client/contract/conversation.ts
@@ -170,7 +170,7 @@ export interface ConversationContextReader {
   previous<State>(kind: string): ConversationPreviousContext<State> | undefined
 }
 
-/** Requested cadence; `animation-frame` materializes after two browser animation frames. */
+/** Requested cadence; `animation-frame` materializes after three browser animation frames. */
 export type ConversationPublication = 'none' | 'animation-frame' | 'immediate'
 
 /** Engine-owned Location data publication phase. */
diff --git a/packages/client/ui-conversation/src/client/conversation/assembly.ts b/packages/client/ui-conversation/src/client/conversation/assembly.ts
index 0741d600b2..1d77942d1e 100644
--- a/packages/client/ui-conversation/src/client/conversation/assembly.ts
+++ b/packages/client/ui-conversation/src/client/conversation/assembly.ts
@@ -121,11 +121,13 @@ class BoundConversation implements ConversationBinding {
     if (publication === 'none') return
     if (publication === 'animation-frame' && typeof requestAnimationFrame === 'function') {
       if (this.frame !== undefined) return
-      // Cross two paint opportunities before publishing high-frequency stream updates.
+      // Cross three paint opportunities before publishing high-frequency stream updates.
       this.frame = requestAnimationFrame(() => {
         this.frame = requestAnimationFrame(() => {
-          this.frame = undefined
-          this.flush()
+          this.frame = requestAnimationFrame(() => {
+            this.frame = undefined
+            this.flush()
+          })
         })
       })
       return
diff --git a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
index de43362fe2..efb2750518 100644
--- a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
@@ -138,7 +138,7 @@ async function bootRegistries(): Promise<{
 }
 
 describe('Conversation registries', () => {
-  it('publishes frame-paced updates after two animation frames and lets immediate updates preempt them', async () => {
+  it('publishes frame-paced updates after three animation frames and lets immediate updates preempt them', async () => {
     let nextFrame = 0
     const frames = new Map<number, FrameRequestCallback>()
     const requestFrame = vi.fn((callback: FrameRequestCallback) => {
@@ -209,6 +209,13 @@ describe('Conversation registries', () => {
     if (second === undefined) throw new Error('second animation frame was not scheduled')
     frames.delete(2)
     second(16)
+    expect(requestFrame).toHaveBeenCalledTimes(3)
+    expect(listener).not.toHaveBeenCalled()
+
+    const third = frames.get(3)
+    if (third === undefined) throw new Error('third animation frame was not scheduled')
+    frames.delete(3)
+    third(32)
     expect(listener).toHaveBeenCalledOnce()
 
     append({
@@ -223,7 +230,7 @@ describe('Conversation registries', () => {
       type: 'assistant/message',
       data: { turn: 1, step: 1, message: { id: 'a1', role: 'assistant', content: [] } },
     } as SessionEvent)
-    expect(cancelFrame).toHaveBeenCalledWith(3)
+    expect(cancelFrame).toHaveBeenCalledWith(4)
     expect(frames).toHaveLength(0)
     expect(listener).toHaveBeenCalledTimes(2)
 

From 443efeeba313d170fc60c52ddfeb0d4134e3309c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:02:53 +0800
Subject: [PATCH 22/37] chore(client): refresh slot catalog

---
 .../src/client/slot-catalog.ts                | 39 ++++++-------------
 1 file changed, 12 insertions(+), 27 deletions(-)

diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index dc9c78a9d5..e6faea81ac 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -289,7 +289,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'useTrajectory: UseTrajectory',
     ],
     keyDomain: 'fixed by the owner\'s key table { [Kind in ChatNodeKind]: { node: ChatNode<Kind> } }, already taken: assistant-step, command, command-input, compaction, context, manual-compaction, model-retry, steering, system-prompt, tool-call, turn-error, turn-max-tokens, turn-process, turn-tail, unknown, user, workflow-run',
-    hookContext: 'string',
+    hookContext: 'ConversationLocationDataStore<ConversationTurnDataMap> | undefined',
     slotInject: 'ChatNodeTurnDataInjected',
     declaredBy: 'an entry in \'conversation.view\' (client-ui-chat), so it exists while that entry is mounted',
     occupants: [
@@ -417,7 +417,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     doc: 'Resident composer body, including the no-Session inert state.',
     registerOptions: [],
     ownerProps: [
-      '/** Owner share of the resident composer bar. */\nexport interface ComposerBarOwnerProps {\n  /** Hero uses centered placement; composer uses the active bottom placement. */\n  variant: \'hero\' | \'composer\'\n  /** A feature-owned reason that makes message input inert while leaving model selection live. */\n  blocked?: { readonly reason: string }\n  /** Lock all message actions while preserving the resident composer surface. */\n  disabled?: boolean\n  /** Whether the shared Workspace picker is expanded. */\n  workspacePickerOpen?: boolean\n  /** Open the Workspace picker from the inert composer surface. */\n  onRequestWorkspace?: () => void\n  placeholder?: string\n  /** Optional content rendered above the composer surface. */\n  accessory?: ReactNode\n  /** Floating overlay content rendered inside the composer card. */\n  overlay?: ReactNode\n  /** Left-side input controls. */\n  leftItems?: ReactNode\n  /** Right-side input controls. */\n  rightItems?: ReactNode\n  /** Ambient content below the card. */\n  footer?: ReactNode\n}',
+      '/** Owner share of the resident composer bar. */\nexport interface ComposerBarOwnerProps {\n  /** Hero uses centered placement; composer uses the active bottom placement. */\n  variant: \'hero\' | \'composer\'\n  /** A feature-owned reason that makes message input inert while leaving model selection live. */\n  blocked?: { readonly reason: string }\n  /** Lock all message actions while preserving the resident composer surface. */\n  disabled?: boolean\n  /** Whether the shared Workspace picker is expanded. */\n  workspacePickerOpen?: boolean\n  /** Open the Workspace picker from the inert composer surface. */\n  onRequestWorkspace?: () => void\n  placeholder?: string\n  /** Optional content rendered above the composer surface. */\n  accessory?: ReactNode\n}',
     ],
     ownerPropsReferences: [
       'Workspace',
@@ -471,13 +471,8 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
         doc: 'Display text where the owner projects one (nav rows, tabs). A thunk is re-read on every projection, so localized text follows the active locale without re-registering.',
       },
     ],
-    ownerProps: [
-      '/** Point-in-time owner values for composer extension entries. */\nexport interface InputZone {\n  readonly session: SessionSnapshot\n  readonly input: InputState\n}',
-    ],
-    ownerPropsReferences: [
-      'InputState',
-      'SessionSnapshot',
-    ],
+    ownerProps: [],
+    ownerPropsReferences: [],
     standardProps: [
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
@@ -495,7 +490,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     keyDomain: '',
     hookContext: '',
     slotInject: '',
-    declaredBy: 'an entry in \'conversation\' (client-ui-conversation), so it exists while that entry is mounted',
+    declaredBy: 'an entry in \'conversation.composer.bar\' (client-ui-conversation), so it exists while that entry is mounted',
     occupants: [
       'client-ui-chat StatsLine id \'stats\'',
     ],
@@ -775,13 +770,8 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
         doc: 'Display text where the owner projects one (nav rows, tabs). A thunk is re-read on every projection, so localized text follows the active locale without re-registering.',
       },
     ],
-    ownerProps: [
-      '/** Point-in-time owner values for composer extension entries. */\nexport interface InputZone {\n  readonly session: SessionSnapshot\n  readonly input: InputState\n}',
-    ],
-    ownerPropsReferences: [
-      'InputState',
-      'SessionSnapshot',
-    ],
+    ownerProps: [],
+    ownerPropsReferences: [],
     standardProps: [
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
@@ -799,7 +789,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     keyDomain: '',
     hookContext: '',
     slotInject: '',
-    declaredBy: 'an entry in \'conversation\' (client-ui-conversation), so it exists while that entry is mounted',
+    declaredBy: 'an entry in \'conversation.composer.bar\' (client-ui-conversation), so it exists while that entry is mounted',
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.left\', () => ctx.slots.register(\n      { name: \'conversation.input.left\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
@@ -886,7 +876,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     keyDomain: '',
     hookContext: '',
     slotInject: '',
-    declaredBy: 'an entry in \'conversation\' (client-ui-conversation), so it exists while that entry is mounted',
+    declaredBy: 'an entry in \'conversation.composer.bar\' (client-ui-conversation), so it exists while that entry is mounted',
     occupants: [
       'client-ui-commands PopupSelectView id \'command-popup\'',
       'client-ui-input-trigger MenuView id \'slash-menu\'',
@@ -957,13 +947,8 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
         doc: 'Display text where the owner projects one (nav rows, tabs). A thunk is re-read on every projection, so localized text follows the active locale without re-registering.',
       },
     ],
-    ownerProps: [
-      '/** Point-in-time owner values for composer extension entries. */\nexport interface InputZone {\n  readonly session: SessionSnapshot\n  readonly input: InputState\n}',
-    ],
-    ownerPropsReferences: [
-      'InputState',
-      'SessionSnapshot',
-    ],
+    ownerProps: [],
+    ownerPropsReferences: [],
     standardProps: [
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
@@ -981,7 +966,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     keyDomain: '',
     hookContext: '',
     slotInject: '',
-    declaredBy: 'an entry in \'conversation\' (client-ui-conversation), so it exists while that entry is mounted',
+    declaredBy: 'an entry in \'conversation.composer.bar\' (client-ui-conversation), so it exists while that entry is mounted',
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.right\', () => ctx.slots.register(\n      { name: \'conversation.input.right\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',

From 7db2bab853a4110741635a4b27e40100bb8d015c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:14:19 +0800
Subject: [PATCH 23/37] test(conversation): brand fixture sequences

---
 .../tests/conversation-assembler.client.spec.ts      | 12 ++++++------
 .../tests/conversation-registry.client.spec.ts       | 11 ++++++-----
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts b/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
index 641f887498..8057c2f95a 100644
--- a/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-assembler.client.spec.ts
@@ -167,8 +167,8 @@ function fallbackDefinition(start: () => string): ConversationNodeDefinition<str
 describe('ConversationNodeAssembler', () => {
   it('publishes Location data through stable per-key sources', () => {
     const index = new ConversationLocationIndex()
-    const turnStart = at(1, 'turn/start', { turn: 1 })
-    const stepStart = at(2, 'step/start', { turn: 1, step: 1 })
+    const turnStart = at(SessionSeq(1), 'turn/start', { turn: 1 })
+    const stepStart = at(SessionSeq(2), 'step/start', { turn: 1, step: 1 })
     index.rebuild([input(turnStart), input(stepStart)])
     const location = index.locationOf(stepStart)
     if (location.kind !== 'step') throw new Error('scope probe requires a Step Location')
@@ -1088,16 +1088,16 @@ describe('ConversationNodeAssembler', () => {
       new TestViewDefinitions([testView(apply)]),
     )
     assembler.replaceWindow([
-      input(at(1, 'turn/start', { turn: 1 })),
-      input(at(2, 'step/start', { turn: 1, step: 1 })),
+      input(at(SessionSeq(1), 'turn/start', { turn: 1 })),
+      input(at(SessionSeq(2), 'step/start', { turn: 1, step: 1 })),
     ], false)
     assembler.flush()
 
-    assembler.append(input(at(3, 'scope-probe/update', { turn: 1, step: 1, changed: false })))
+    assembler.append(input(at(SessionSeq(3), 'scope-probe/update', { turn: 1, step: 1, changed: false })))
     expect(assembler.flush()).toBe(false)
     expect(apply).not.toHaveBeenCalled()
 
-    assembler.append(input(at(4, 'scope-probe/update', { turn: 1, step: 1, changed: true })))
+    assembler.append(input(at(SessionSeq(4), 'scope-probe/update', { turn: 1, step: 1, changed: true })))
     expect(assembler.flush()).toBe(true)
     expect(apply).toHaveBeenCalledOnce()
   })
diff --git a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
index efb2750518..9805bf189f 100644
--- a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
@@ -1,5 +1,6 @@
 import { Context } from '@deepseek-ai/cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
+import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import {
@@ -181,16 +182,16 @@ describe('Conversation registries', () => {
       source.append({ type: 'event', event })
     }
 
-    append({ seq: 1, time: 1, type: 'turn/start', data: { turn: 1 } })
+    append({ seq: SessionSeq(1), time: 1, type: 'turn/start', data: { turn: 1 } })
     listener.mockClear()
     append({
-      seq: 2,
+      seq: SessionSeq(2),
       time: 2,
       type: 'assistant/chunk',
       data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'a' } },
     })
     append({
-      seq: 3,
+      seq: SessionSeq(3),
       time: 3,
       type: 'assistant/chunk',
       data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'b' } },
@@ -219,13 +220,13 @@ describe('Conversation registries', () => {
     expect(listener).toHaveBeenCalledOnce()
 
     append({
-      seq: 4,
+      seq: SessionSeq(4),
       time: 4,
       type: 'assistant/chunk',
       data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'c' } },
     })
     append({
-      seq: 5,
+      seq: SessionSeq(5),
       time: 5,
       type: 'assistant/message',
       data: { turn: 1, step: 1, message: { id: 'a1', role: 'assistant', content: [] } },

From 2e21d210a5770fa67e2d737920e0254d38089250 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:17:47 +0800
Subject: [PATCH 24/37] fix(trajectory): reanchor replaced history windows

---
 .../src/client/TrajectoryView.tsx             | 15 +++++++----
 .../ui-trajectory/tests/views.client.spec.tsx | 26 +++++++++++++++++++
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
index f950084244..a9f1df1b36 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
+++ b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
@@ -160,13 +160,18 @@ export function TrajectoryView({
   const [historyTailSeq, setHistoryTailSeq] = useState(latestNodeSeq)
   const [historyNodeLimit, setHistoryNodeLimit] = useState(HISTORY_PAGE_NODES)
   const fixedTailSeq = historyTailSeq ?? latestNodeSeq
-  const historyEndIndex = fixedTailSeq === undefined
-    ? 0
-    : completeInspection.eventNodes.findLastIndex(node => node.seq <= fixedTailSeq) + 1
+  const historyTailIndex = fixedTailSeq === undefined
+    ? -1
+    : completeInspection.eventNodes.findLastIndex(node => node.seq <= fixedTailSeq)
+  const historyEndIndex = historyTailIndex < 0 && latestNodeSeq !== undefined
+    ? completeInspection.eventNodes.length
+    : historyTailIndex + 1
   const historyStartIndex = Math.max(0, historyEndIndex - historyNodeLimit)
   useEffect(() => {
-    if (historyTailSeq === undefined && latestNodeSeq !== undefined) setHistoryTailSeq(latestNodeSeq)
-  }, [historyTailSeq, latestNodeSeq])
+    if (latestNodeSeq !== undefined && (historyTailSeq === undefined || historyTailIndex < 0)) {
+      setHistoryTailSeq(latestNodeSeq)
+    }
+  }, [historyTailIndex, historyTailSeq, latestNodeSeq])
   const inspection = useMemo<TrajectorySnapshot>(() => {
     if (historyStartIndex === 0) return completeInspection
     const eventNodes = completeInspection.eventNodes.slice(historyStartIndex)
diff --git a/packages/client/ui-trajectory/tests/views.client.spec.tsx b/packages/client/ui-trajectory/tests/views.client.spec.tsx
index 967a39bbb5..fba1a7b77e 100644
--- a/packages/client/ui-trajectory/tests/views.client.spec.tsx
+++ b/packages/client/ui-trajectory/tests/views.client.spec.tsx
@@ -1299,6 +1299,32 @@ describe('TrajectoryView state', () => {
     expect(screen.getByRole('table').getAttribute('aria-rowcount')).toBe('102')
   })
 
+  it('keeps a replacement window bounded when its predecessor tail is absent', () => {
+    const nodes = (start: number): LegacyConversationSlice['nodes'] => Array.from(
+      { length: 100 },
+      (_, index) => ({
+        kind: 'user' as const,
+        seq: start + index,
+        time: start + index,
+        content: [],
+        source: null,
+      }),
+    )
+    const trajectory = createSnapshotStore(historySnapshot(nodes(1)))
+    render(
+      <TrajectoryView
+        {...standaloneProps([])}
+        {...standaloneHistory(historySnapshot([]))}
+        {...standaloneDuration()}
+        useTrajectory={bindSnapshotSelector(trajectory)}
+      />,
+    )
+    expect(screen.getByRole('table').getAttribute('aria-rowcount')).toBe('51')
+
+    act(() => { trajectory.set(historySnapshot(nodes(201))) })
+    expect(screen.getByRole('table').getAttribute('aria-rowcount')).toBe('51')
+  })
+
   it('keeps resident request numbering and cumulative usage outside the layout page', async () => {
     vi.spyOn(HTMLElement.prototype, 'offsetHeight', 'get').mockReturnValue(600)
     Object.defineProperty(HTMLElement.prototype, 'scrollTo', {

From b74486ab29b65d132b850350db0cc3c6ff443419 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:04:19 +0800
Subject: [PATCH 25/37] docs: restore Cloudflare's Code Mode name and blog link
 in PTC note
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The code-mode → ptc rename rewrote Cloudflare's product name in the
link text and the external URL path, leaving "PTC mode" pointing at
https://blog.cloudflare.com/ptc/ (404). Restore Cloudflare's own name
and the working https://blog.cloudflare.com/code-mode/ link in both
the English and Chinese notes.
---
 .agents/notes/implemented/feature/2026-06-15-ptc.i18n.yaml | 4 ++--
 .agents/notes/implemented/feature/2026-06-15-ptc.md        | 2 +-
 .agents/notes/implemented/feature/2026-06-15-ptc.zh.md     | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-06-15-ptc.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-ptc.i18n.yaml
index ed42409d93..255067c0f0 100644
--- a/.agents/notes/implemented/feature/2026-06-15-ptc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-ptc.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 .agents/notes/implemented/feature/2026-06-15-ptc.md
-2026-06-15-ptc.md: 5b3971c33df4be46c8a466e564ac86ba6454663a
-2026-06-15-ptc.zh.md: fe44d8a0e97913998fc001c92f632f493888c720
+2026-06-15-ptc.md: c0a0b3ad54716761a74eed8b54c11480e9ca41bc
+2026-06-15-ptc.zh.md: b774fc001509f30d41d1c519f344f67d797c2cbf
diff --git a/.agents/notes/implemented/feature/2026-06-15-ptc.md b/.agents/notes/implemented/feature/2026-06-15-ptc.md
index 5b3971c33d..c0a0b3ad54 100644
--- a/.agents/notes/implemented/feature/2026-06-15-ptc.md
+++ b/.agents/notes/implemented/feature/2026-06-15-ptc.md
@@ -10,7 +10,7 @@ In the registry's native presentation, the agent loop advertises every visible c
 
 For multi-step tool work this is token-heavy and serial. The model cannot compose tools — loop over a result set, branch on an intermediate value, fan out, post-process — without a full model round-trip per call, and each round-trip drags the entire intermediate result back into context whether the model needs it or not.
 
-Cloudflare's [PTC mode](https://blog.cloudflare.com/ptc/) proposes an alternative grounded in a simple observation: LLMs are better at writing code than at emitting tool calls, because they have seen millions of lines of real code and comparatively few contrived tool-calling traces. Instead of one tool call per step, the model writes a TypeScript program against a generated API over the tools, the program executes in a sandboxed runtime, and the model curates what comes back — only what it prints or returns — instead of every intermediate result.
+Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) proposes an alternative grounded in a simple observation: LLMs are better at writing code than at emitting tool calls, because they have seen millions of lines of real code and comparatively few contrived tool-calling traces. Instead of one tool call per step, the model writes a TypeScript program against a generated API over the tools, the program executes in a sandboxed runtime, and the model curates what comes back — only what it prints or returns — instead of every intermediate result.
 
 Tool presentation belongs to the registry that owns tool visibility: implementing a second presentation as an after-the-fact waterfall transform would make correctness depend on listener order and fight [reconstructable requests](../architecture/2026-07-05-reconstructable-requests.md). The execution substrate is also part of the foundation rather than a placeholder: Node `worker_threads` provides a separate isolate, an empty environment, heap caps, and termination of a hot synchronous loop, while fitting the harness's existing trust model (§Trust posture).
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-ptc.zh.md b/.agents/notes/implemented/feature/2026-06-15-ptc.zh.md
index fe44d8a0e9..b774fc0015 100644
--- a/.agents/notes/implemented/feature/2026-06-15-ptc.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-ptc.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 对于多步工具操作，这种方式 token 开销大且串行。模型无法组合工具——遍历结果集、根据中间值分支、扇出、后处理——每次调用都需要一次完整的模型往返，而每次往返都会把完整的中间结果拖回上下文，不管模型是否需要。
 
-Cloudflare 的 [PTC mode](https://blog.cloudflare.com/ptc/) 提出了一种替代方案，基于一个简单的观察：LLM（大语言模型）编写代码的能力优于发出工具调用，因为它们见过数百万行真实代码，而人为构造的工具调用 trace 相对很少。模型不再每步发出一次工具调用，而是针对工具生成的 API 编写一段 TypeScript 程序，程序在沙箱运行时中执行，模型只筛选返回的内容——仅限它 print 或 return 的部分——而非所有中间结果。
+Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一种替代方案，基于一个简单的观察：LLM（大语言模型）编写代码的能力优于发出工具调用，因为它们见过数百万行真实代码，而人为构造的工具调用 trace 相对很少。模型不再每步发出一次工具调用，而是针对工具生成的 API 编写一段 TypeScript 程序，程序在沙箱运行时中执行，模型只筛选返回的内容——仅限它 print 或 return 的部分——而非所有中间结果。
 
 工具呈现属于掌管工具可见性的注册表：如果把第二种呈现方式实现为事后的 waterfall（瀑布式事件）变换，正确性将依赖监听器顺序，并与[可重建请求](../architecture/2026-07-05-reconstructable-requests.zh.md)冲突。执行基底同样属于基础设施而非占位实现：Node `worker_threads` 提供独立 isolate、空环境、堆上限以及对热同步循环的终止能力，同时契合 harness 既有的信任模型（§信任姿态）。
 

From a718d1f0a16102e73d6823d8b69bc5e46344099f Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:31:04 +0800
Subject: [PATCH 26/37] docs(client): record conversation performance
 boundaries

---
 ...-web-input-machine-and-slash-pipeline.i18n.yaml |  4 ++--
 ...6-07-25-web-input-machine-and-slash-pipeline.md |  3 ++-
 ...7-25-web-input-machine-and-slash-pipeline.zh.md |  3 ++-
 ...ected-token-usage-and-request-context.i18n.yaml |  4 ++--
 ...29-projected-token-usage-and-request-context.md |  4 ++--
 ...projected-token-usage-and-request-context.zh.md |  4 ++--
 ...-09-client-conversation-node-assembly.i18n.yaml |  4 ++--
 ...2026-08-09-client-conversation-node-assembly.md | 14 +++++++-------
 ...6-08-09-client-conversation-node-assembly.zh.md | 14 +++++++-------
 ...jectory-conversation-context-assembly.i18n.yaml |  4 ++--
 ...-11-trajectory-conversation-context-assembly.md |  2 +-
 ...-trajectory-conversation-context-assembly.zh.md |  2 +-
 ...client-session-conversation-ownership.i18n.yaml |  4 ++--
 ...-08-20-client-session-conversation-ownership.md |  2 +-
 ...-20-client-session-conversation-ownership.zh.md |  2 +-
 .../feature/2026-08-03-web-turn-run-time.i18n.yaml |  4 ++--
 .../feature/2026-08-03-web-turn-run-time.md        |  6 +++---
 .../feature/2026-08-03-web-turn-run-time.zh.md     |  6 +++---
 .../2026-08-14-web-turn-process-folding.i18n.yaml  |  4 ++--
 .../feature/2026-08-14-web-turn-process-folding.md |  6 ++++--
 .../2026-08-14-web-turn-process-folding.zh.md      |  6 ++++--
 .../src/client/slot-catalog.ts                     | 12 ++++++------
 22 files changed, 60 insertions(+), 54 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
index 3e59e7e702..28ab0da3dd 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.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 .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
-2026-07-25-web-input-machine-and-slash-pipeline.md: 69899efcda42eb1087aaa68d1eba8c08dd14f361
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 7e37dd67a2d5a7943a8c601a890d2de7489b227d
+2026-07-25-web-input-machine-and-slash-pipeline.md: 200761cc9e648eea80bdae9d7b363246c816e5d1
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 673d0ee4bd0916b20ee74226f50240e3904fe06c
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
index 69899efcda..200761cc9e 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
@@ -55,7 +55,7 @@ A trigger/menu/pick pipeline with zero knowledge of "commands":
 
 - The hub (trigger/decoration registries + send orchestration) takes the slash/command services as optional `ctx.get()` dependencies: without ui-input-trigger or the command surfaces, input still sends and receives normally — graceful degradation.
 - Each materialized Session has exactly one `SessionInputShell` (the facade), created and torn down with the session scope; with no session, no input machine is built. `ConversationRoot` is itself the `session-maybe` resident shell, holding HeroShell, the Workspace picker, the composer stack, and the chain-fallback frame. It always owns the same scrollport and composer seat; separate strict-session header and body outlets fill those fixed regions after a Session appears.
-- The composer bar is one `session-maybe` slot entry rendered unconditionally: with no session the same InputBar renders inert (machine faces absent, `disabled` owner prop), and once `connectWorkspace` returns a blank session the same instance goes live — the composer surface DOM survives the no-session → blank transition and every later phase flip; `ConversationRoot`, the Hero, and the layout skeleton hold throughout.
+- The composer bar is one `session-maybe` slot entry rendered unconditionally: with no session the same InputBar renders inert (machine faces absent, `disabled` owner prop), and once `connectWorkspace` returns a blank session the same instance goes live — the composer surface DOM survives the no-session → blank transition and every later phase flip; `ConversationRoot`, the Hero, and the layout skeleton hold throughout. The memoized InputBar renders its overlay, left, right, and dock child slots after the renderer has bound their standard props; `ConversationRoot` passes only scalar data and callbacks, so an unrelated shell render does not create fresh ReactNode owner props or invalidate the bar.
 - ConversationRoot's Hero criterion is `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || summaryBlank === true))`: a summary-proven blank Session remains Hero in every open state, while an unproven Session settles during loading. The first submit enters engaging synchronously, and a failure keeps the composer and the error context rather than falling back to the blank Hero; the sidebar's blank bit flips false only after a prompt is successfully accepted.
 - Sending unifies in the hub defaultSink: after an optimistic draft clear it goes only through `session.prompt` with `mode:'queue'` (the Web UI has no steer entry; host-wire `mode:'steer'` remains outside this machine); backfill happens only when it fails and the live draft is still empty — a user who has kept typing is never overwritten. No Draft materialize or attach transaction exists.
 - When the blank Hero re-picks the Workspace, the shell calls `connectWorkspace`; if the target session differs, the non-empty draft moves from the current shell to the target shell before the new id is opened, and the old blank session survives but is no longer current.
@@ -105,6 +105,7 @@ The state machine's entire behavior is covered by pure-JS unit tests (event sequ
 | Dual draft persistence {text, occurrences} | The mirror writing the clipboard projection adds zero new concepts; chip degradation across refresh is acceptable |
 | The native textarea undo stack | Unreliable under controlled + programmatic writes; the paste two-step undo semantics can only be self-managed — both sides retired with the textarea itself; Lexical's history owns undo now |
 | The InputBar receiving a 16-member wiring-callback bundle | The consumption matrix proved 11 members InputBar-exclusive and 1 a dead member; the standard-kit channel lets components fetch their own, with the keyboard surface passed privately in-package |
+| `ConversationRoot` rendering InputBar's child slots into owner props | Fresh React elements defeat the bar's memo boundary; the bar already receives `renderSlot` and owns the exact positions |
 | Space adjudication also claiming execute-kind commands | The misfire defense: after a space the whole line is an ordinary prompt; irreversible side effects keep explicit entry points only |
 | A generic tokenPattern decoration mechanism | Structured occurrence records replace pattern scanning |
 | A placeholder select resident in the tool row | Named seats stay empty until registration; a placeholder clashing with the real implementation is two sources of truth |
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
index 7e37dd67a2..673d0ee4bd 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
@@ -55,7 +55,7 @@ Status: implemented
 
 - hub（trigger/decoration 注册表 + 发送编排）对 slash/command 服务是可选 `ctx.get()` 依赖：无 ui-input-trigger/命令面时输入正常收发，优雅降级。
 - 每个实体会话只有一个 `SessionInputShell`（facade），随会话作用域创建和拆除；无会话时不造 input machine。`ConversationRoot` 自身是 `session-maybe` 常驻外壳，持有 HeroShell、Workspace picker、composer stack 与 chain fallback 外框。它始终拥有同一个 scrollport 与 composer seat；会话出现后，彼此独立的严格会话 header 和 body outlet 只填入这些固定区域。
-- composer bar 是一个无条件渲染的 `session-maybe` slot entry：无会话时同一个 InputBar 以惰性态渲染（machine face 缺席、`disabled` owner prop），`connectWorkspace` 返回 blank 会话后同一实例转为 live——编辑器表面 DOM 在无会话 → blank 切换及其后每次 phase 翻转中都不重建；`ConversationRoot`、Hero 与布局骨架全程保持。
+- composer bar 是一个无条件渲染的 `session-maybe` slot entry：无会话时同一个 InputBar 以惰性态渲染（machine face 缺席、`disabled` owner prop），`connectWorkspace` 返回 blank 会话后同一实例转为 live——编辑器表面 DOM 在无会话 → blank 切换及其后每次 phase 翻转中都不重建；`ConversationRoot`、Hero 与布局骨架全程保持。memoized InputBar 在 renderer 绑定各 child slot 的标准 props 后自行渲染 overlay、left、right 与 dock；`ConversationRoot` 只传标量数据和回调，因此无关 shell render 不会制造新的 ReactNode owner prop 或使 bar 失效。
 - ConversationRoot 的 Hero 判据是 `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || summaryBlank === true))`：summary 已证实为空的会话在任何 open state 下都保持 Hero，未经证实的会话则在 loading 期间进入 settling。首次 submit 同步进入 engaging，失败也保留 composer 与错误上下文，不退回 blank Hero；sidebar 的 blank 位只在提示词成功受理后翻 false。
 - 发送统一在 hub defaultSink：乐观清稿后只走 `session.prompt` 且固定 `mode:'queue'`（Web UI 无 steer 入口；host 线缆上的 `mode:'steer'` 不经此 machine）；失败且 live draft 仍为空才回填，用户已经继续输入则不覆盖。不存在 Draft materialize 或 attach 事务。
 - blank Hero 改选 Workspace 时，外壳调用 `connectWorkspace`；目标会话不同时把非空 draft 从当前 shell 搬到目标 shell，再 open 新 id，旧 blank 会话留存但不再 current。
@@ -105,6 +105,7 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——纯文本引
 | draft 双持久化 {text, occurrences} | mirror 写剪贴板投影零新概念；chip 跨刷新降级可接受 |
 | 原生 textarea undo 栈 | 受控 + 程序化写入下不可靠；粘贴两段 undo 语义只能自管——两侧都随 textarea 一并退役；undo 现归 Lexical history |
 | InputBar 收 16 员 wiring 回调包 | 消费矩阵实证 11 员 InputBar 独占、1 员死成员；标准件通道让组件自取，键盘面包内私递 |
+| 由 `ConversationRoot` 把 InputBar child slot 渲染为 owner prop | 新 React element 会击穿 bar 的 memo 边界；bar 已收到 `renderSlot`，也拥有这些位置 |
 | 空格裁决也认领即执行型命令 | 误触发防线：空格后整行是普通提示词；不可逆副作用只留显式入口 |
 | 通用 tokenPattern 装饰机制 | 结构化 occurrence 记录取代模式扫描 |
 | 占位 select 常驻工具行 | 具名 slot 在注册前保持为空；占位件与真实现冲突时是两个真源 |
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
index 8baf8386d1..2e41d77dd7 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.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 .agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
-2026-07-29-projected-token-usage-and-request-context.md: 75a05e5a0e8f0183fef1e7d80701ce6d81041cd6
-2026-07-29-projected-token-usage-and-request-context.zh.md: 7cce5989d719156f1d66c48937780ff8aed02a42
+2026-07-29-projected-token-usage-and-request-context.md: 7c984012b7a4b387f1ff24279567fe15aa34cf77
+2026-07-29-projected-token-usage-and-request-context.zh.md: b34fb7702898f4a51524a24ad27927c48220bfad
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
index 75a05e5a0e..7c984012b7 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
@@ -26,7 +26,7 @@ Capacity deliberately stays out of `EpochHeader`. That type is the reconstructio
 
 Both units ride the standard projection lifecycle: history tail baselines, `session/projection` live frames, higher-seq-wins client storage, JSON checkpoints, cache recovery, and unit unload. There is no token-specific history field, mux frame, projector, revision counter, or client fence.
 
-The Web `StatsLine` reads both through the standard `useProjection` seat. Window nodes still supply turn and step counts plus LLM and tool wall times — those answer "what is on screen" and are correctly window-scoped. Durable token and context groups remain when compaction leaves no visible assistant step. Cache writes count in billed input and in the cache-hit denominator. A deployment without token-meter drops the token groups; occupancy stays hidden until both pressure and capacity are known.
+The Web `StatsLine` reads both through the standard `useProjection` seat. Window nodes still supply turn and step counts plus LLM and tool wall times — those answer "what is on screen" and are correctly window-scoped. Durable token and context groups remain when compaction leaves no visible assistant step. Cache writes count in billed input and in the cache-hit denominator. A deployment without token-meter drops the token groups; occupancy stays hidden until both pressure and capacity are known. The exact-overflow tooltip mounts its measuring child only for a non-empty line and retains one `ResizeObserver` while values change; text changes perform one direct measurement without replacing the observer.
 
 ## Context occupancy is approximate, and that is the decision
 
@@ -58,4 +58,4 @@ Token totals stay stable across pagination, compaction, replay, restart, and rec
 
 Occupancy is approximate in the ways documented above. It is available immediately after restore or reconnect, since both fields are durable, at the cost of describing the last recorded request rather than an exact current boundary.
 
-Each session log gains one small `request/context` record per route or advertised-capacity change. Token-meter is the canonical owner of durable usage semantics, including retry-attempt separation in the cumulative projection and the reusable exact attempt/Turn fold; Web Chat only selects a complete loaded Turn and renders the fold result. The TUI retains its live per-step map because it does not mount the generic projection seam, and the standalone browser fixture mirrors the unit. Connection and API Gateway carry no token-specific code, own no per-session metrics cache, and perform no measurement. The browser keeps two generic projection values and no connection-local telemetry, and streaming text deltas still do not force the stats line to recompute.
+Each session log gains one small `request/context` record per route or advertised-capacity change. Token-meter is the canonical owner of durable usage semantics, including retry-attempt separation in the cumulative projection and the reusable exact attempt/Turn fold; Web Chat only selects a complete loaded Turn and renders the fold result. The TUI retains its live per-step map because it does not mount the generic projection seam, and the standalone browser fixture mirrors the unit. Connection and API Gateway carry no token-specific code, own no per-session metrics cache, and perform no measurement. The browser keeps two generic projection values and no connection-local telemetry; streaming text deltas do not force the stats line to recompute or churn layout-observer subscriptions.
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
index 7cce5989d7..b34fb77028 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
@@ -26,7 +26,7 @@ token-meter 还拥有在持久事件上运行的共享纯 attempt／Turn fold。
 
 两个单元都沿用标准投影生命周期：历史尾页基线、`session/projection` 实时帧、seq 高者胜的客户端存储、JSON 检查点、缓存恢复和单元卸载。系统没有任何 token 专用的历史字段、mux 帧、投影器、修订计数器或客户端栅栏。
 
-Web `StatsLine` 通过标准 `useProjection` 席位读取两者。窗口内节点仍提供轮次和步骤计数，以及 LLM（大语言模型）与工具的墙钟时间：它们回答的是「屏幕上有什么」，按窗口作用域正是正确的。压缩使可见 assistant 步骤归零后，持久 token 与上下文分组仍会保留。缓存写入会计入计费输入和缓存命中率分母。未部署 token-meter 时会去掉 token 分组；只有压力与容量都已知时才显示占用率。
+Web `StatsLine` 通过标准 `useProjection` 席位读取两者。窗口内节点仍提供轮次和步骤计数，以及 LLM（大语言模型）与工具的墙钟时间：它们回答的是「屏幕上有什么」，按窗口作用域正是正确的。压缩使可见 assistant 步骤归零后，持久 token 与上下文分组仍会保留。缓存写入会计入计费输入和缓存命中率分母。未部署 token-meter 时会去掉 token 分组；只有压力与容量都已知时才显示占用率。精确 overflow tooltip 只在统计行非空时挂载测量子组件，并在值变化期间保留同一个 `ResizeObserver`；文本变化只直接测量一次，不替换 observer。
 
 ## 上下文占用率是近似值，而这正是决策本身
 
@@ -58,4 +58,4 @@ token 总量在分页、压缩、回放、重启和重连期间保持稳定，
 
 占用率在上文记录的意义上是近似值。由于两个字段都是持久的，它在恢复或重连后立即可用；代价是它描述的是最后一条已记录的请求，而不是精确的当前边界。
 
-每个会话日志会为每次路由或已公布容量变化增加一条小型 `request/context` 记录。token-meter 是持久用量语义的正典所有方，包括累计投影中的重试 attempt 分离，以及可复用的精确 attempt／Turn fold；Web Chat 只选择已完整加载的 Turn 并渲染 fold 结果。TUI 未挂载通用投影 seam，因此保留自己的实时逐步骤 map，而独立浏览器 fixture（测试前置数据）会镜像该单元。Connection 与 API Gateway 不携带任何 token 专用代码，不拥有逐会话指标缓存，也不执行测量。浏览器只保留两个通用投影值，不保留连接本地的遥测数据；流式文本增量仍不会迫使统计行重新计算。
+每个会话日志会为每次路由或已公布容量变化增加一条小型 `request/context` 记录。token-meter 是持久用量语义的正典所有方，包括累计投影中的重试 attempt 分离，以及可复用的精确 attempt／Turn fold；Web Chat 只选择已完整加载的 Turn 并渲染 fold 结果。TUI 未挂载通用投影 seam，因此保留自己的实时逐步骤 map，而独立浏览器 fixture（测试前置数据）会镜像该单元。Connection 与 API Gateway 不携带任何 token 专用代码，不拥有逐会话指标缓存，也不执行测量。浏览器只保留两个通用投影值，不保留连接本地的遥测数据；流式文本增量不会迫使统计行重新计算或反复替换布局 observer 订阅。
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index 7d17815ffa..23f634a3fe 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 28b21480de60a17fdc141c3a2b20271f2bdaedbf
-2026-08-09-client-conversation-node-assembly.zh.md: f2ae267a1d385283b6fc51396d24b42ec2300469
+2026-08-09-client-conversation-node-assembly.md: 0aac5056e2cbe22359f8064b1bf4aa0b015a35c8
+2026-08-09-client-conversation-node-assembly.zh.md: b06a92113f91e6297da986866dce097b11bab45f
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 28b21480de..0aac5056e2 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -315,21 +315,21 @@ The shell synchronously resolves the persisted selection when a Session binding
 
 Ordinary prepend and append flushes call `apply({ upserts, timeline })` only for active targets. Complete window replacement and Registry rebuild call `replace()` only for active targets. Unsubscription does not remove a target, so returning to an opened View does not rebuild it.
 
-[`ChatSnapshotBuilder`](../../../../packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store, the turn/step `locations` index, `timeline`, and the `legacy` slice used by StatsLine and mirrored into top-level public compatibility fields.
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store with identity-stable Node and Turn-process sources, the turn/step `locations` index, `timeline`, and the `legacy` slice used by StatsLine and mirrored into top-level public compatibility fields.
 
-Only a new key or a change to `anchorSeq`, visibility, or Location identity makes a Chat update structural. An ordinary content change does not rebuild `order`; the keyed Node store replaces only that key's value.
+Only a new key or a change to `anchorSeq`, visibility, or Location identity makes a Chat update structural. An ordinary content change does not rebuild `order`; the keyed Node store replaces that key's value and publishes only its source. The Turn-process projector recalculates cross-Node presentation only for a Turn whose structure, specification, or status changed, then publishes only that Turn's process sources.
 
 For a structural change, the Builder computes visible order from current store values and reuses unchanged index arrays by reference. Prepend may add earlier history keys, append may add a key at the tail or its business anchor, and ordering never renames existing keys.
 
-[`ChatView`](../../../../packages/client/ui-chat/src/client/chat/ChatView.tsx) only traverses `order`. Each [`ChatNodeSeat`](../../../../packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx) remains in the same parent list under its Context key and dispatches the `'conversation.chat.node'` keyed slot by `node.kind`.
+[`ChatView`](../../../../packages/client/ui-chat/src/client/chat/ChatView.tsx) only traverses `order` and resolves the two stable sources for each key. Each [`ChatNodeSeat`](../../../../packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx) remains in the same parent list under its Context key, subscribes only to its Node and Turn-process sources, and dispatches the `'conversation.chat.node'` keyed slot by `node.kind`.
 
 [`ChatNodeDataMap`](../../../../packages/client/ui-chat/src/client/contract/chat-nodes.ts) is a declaration-merged renderer payload registry. Each business module registers its own Definition and keyed renderer; `registerConversationNodes()` and `registerChatNodeRenderers()` only assemble those independent contributions and do not interpret business through a closed union or central switch. Built-ins live in `ui-chat`, and this type and registration boundary allows a business to move into an independent package without changing the Chat dispatcher.
 
-The Chat entry in `conversation.view` registers `ChatNodeTurnDataInjected` once when it declares the `conversation.chat.node` child slot. `ChatNodeSeat` passes only the stable Node key as `hookContext`; the Slot renderer combines that key with `useSession` from the official standard props to construct `useTurnData(businessKey)`. Every keyed Chat renderer therefore reads strongly typed, read-only data from its own Node's Turn, and the Assistant renderer has no special injection authority.
+The Chat entry in `conversation.view` registers `ChatNodeTurnDataInjected` once when it declares the `conversation.chat.node` child slot. `ChatNodeSeat` passes the Node's stable Turn data store as `hookContext`; the Slot renderer binds `useTurnData(businessKey)` directly to that store. Every keyed Chat renderer therefore reads strongly typed, read-only data from its own Node's Turn, and the Assistant renderer has no special injection authority.
 
-Slot-level contextual Hooks and entry-owned `inject.hooks` remain independent paths. The latter continues to bind only registration-owned Observables. The former caches definitions by stable slot-inject-face identity and binds its factory and Hook per stable render occurrence. The selector inside `useTurnData()` returns only the current Node's `turn.data.get(key)`, so selector equality filters unrelated Session publications.
+Slot-level contextual Hooks and entry-owned `inject.hooks` remain independent paths. The latter continues to bind only registration-owned Observables. The former caches definitions by stable slot-inject-face identity and binds its factory and Hook per stable render occurrence. `useTurnData()` subscribes to `turn.data.source(key)`, so another Location-data key or Session snapshot publication does not notify it.
 
-The standard `useSession` remains available to every session-scoped slot renderer. `useTurnData()` narrows the common read path rather than acting as a permission sandbox. Whole-window statistics or arbitrary object indexes may still read the Session snapshot explicitly, but they are not modeled as current-Node Turn data.
+The standard `useSession` remains available to every session-scoped slot renderer, although `ChatNodeSeat` needs neither it nor aggregate `useChat`. `useTurnData()` narrows the common read path rather than acting as a permission sandbox. Whole-window statistics or arbitrary object indexes may still read the Session snapshot explicitly, but they are not modeled as current-Node Turn data.
 
 Assistant streaming to final and Tool running to settled stay in one Seat while updating its data and necessary ordering properties. Settlement therefore does not reset component-local State through a parent move.
 
@@ -418,7 +418,7 @@ Separating State updates from publication cadence folds every live Assistant del
 
 An inactive target retains Definition State and a target Context index but no builder, materialized Nodes, or snapshot. The mounted built-in or third-party View activates its own target through normal subscription; previously opened targets continue receiving incremental updates.
 
-Steps and Turns are stable homes for cross-business aggregates. Turn Tail and Deliverables derive their values without renderer scans of global Nodes; slot-level `useTurnData()` narrows common reads to the current Node's Turn and uses selector equality to isolate unrelated updates.
+Steps and Turns are stable homes for cross-business aggregates. Turn Tail and Deliverables derive their values without renderer scans of global Nodes; slot-level `useTurnData()` narrows common reads to the current Node's Turn, and keyed Location sources isolate unrelated updates.
 
 Inbox Context retention grows with splice count and claimed message count rather than their cumulative prefixes. This removes duplicate state growth but does not deduplicate message content in durable Session events or bound the loaded event window.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index f2ae267a1d..b06a92113f 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -315,21 +315,21 @@ Session binding 可用、缓存的 binding 成为 current 或 View roster 变化
 
 普通 prepend 与 append flush 只对 active target 调用 `apply({ upserts, timeline })`。完整 window replace 与 Registry rebuild 只对 active target 调用 `replace()`。取消订阅不会移除 target，因此返回已打开的 View 不会重建。
 
-[`ChatSnapshotBuilder`](../../../../packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、keyed `nodes` store、turn/step `locations` index、`timeline`，以及由 StatsLine 使用并镜像到顶层公共兼容字段的 `legacy` slice。
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、带身份稳定 Node 与 Turn-process source 的 keyed `nodes` store、turn/step `locations` index、`timeline`，以及由 StatsLine 使用并镜像到顶层公共兼容字段的 `legacy` slice。
 
-Chat 结构变化只由新 key、`anchorSeq`、visibility 或 Location identity 变化触发。普通内容变化不重建 `order`；keyed Node store 只替换该 key 的 value。
+Chat 结构变化只由新 key、`anchorSeq`、visibility 或 Location identity 变化触发。普通内容变化不重建 `order`；keyed Node store 只替换该 key 的 value 并发布其 source。Turn-process projector 仅为结构、规格或状态发生变化的 Turn 重算跨 Node 呈现，再只发布该 Turn 的 process source。
 
 Builder 遇到结构变化时从 store 的当前 values 计算 visible order，并按未变化引用复用索引数组。Prepend 可以增加前部历史 key，append 可以增加尾部或按业务 anchor 落位，既有 key 不因排序变化而重命名。
 
-[`ChatView`](../../../../packages/client/ui-chat/src/client/chat/ChatView.tsx) 只遍历 `order`。每个 [`ChatNodeSeat`](../../../../packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx) 以 Context key 固定在同一个父列表中，并按 `node.kind` 分发 `'conversation.chat.node'` keyed slot。
+[`ChatView`](../../../../packages/client/ui-chat/src/client/chat/ChatView.tsx) 只遍历 `order`，并为每个 key 解析两份稳定 source。每个 [`ChatNodeSeat`](../../../../packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx) 以 Context key 固定在同一个父列表中，只订阅自身的 Node 与 Turn-process source，并按 `node.kind` 分发 `'conversation.chat.node'` keyed slot。
 
 [`ChatNodeDataMap`](../../../../packages/client/ui-chat/src/client/contract/chat-nodes.ts) 是 declaration-merged 的 renderer payload registry。每个业务模块分别注册自己的 Definition 和 keyed renderer；`registerConversationNodes()` 与 `registerChatNodeRenderers()` 只负责装配这些独立贡献，不通过 closed union 或中心 switch 解释业务。内建实现位于 `ui-chat`，且该类型和注册边界允许业务迁入独立 package 而不修改 Chat dispatcher。
 
-`conversation.view` 的 Chat entry 在声明 `conversation.chat.node` child slot 时统一注册 `ChatNodeTurnDataInjected`。`ChatNodeSeat` 只把稳定 Node key 作为 `hookContext` 传给 slot；Slot renderer 用官方 standard props 中的 `useSession` 和该 key 构造 `useTurnData(businessKey)`，因此每个 keyed Chat renderer 都能读取自己 Node 所属 Turn 的强类型只读 data，Assistant renderer 不拥有特殊注入权限。
+`conversation.view` 的 Chat entry 在声明 `conversation.chat.node` child slot 时统一注册 `ChatNodeTurnDataInjected`。`ChatNodeSeat` 把 Node 所属 Turn 的稳定 data store 作为 `hookContext` 传给 slot；Slot renderer 直接在该 store 上绑定 `useTurnData(businessKey)`，因此每个 keyed Chat renderer 都能读取自己 Node 所属 Turn 的强类型只读 data，Assistant renderer 不拥有特殊注入权限。
 
-Slot-level contextual Hook 与 entry-owned `inject.hooks` 是两条独立路径。后者继续只绑定 registration-owned Observable；前者按稳定 slot inject face 缓存定义，并按稳定 render occurrence 绑定 factory 和 Hook。`useTurnData()` 内部 selector 只返回当前 Node 的 `turn.data.get(key)`，无关 Session publication 会被 selector equality 截断。
+Slot-level contextual Hook 与 entry-owned `inject.hooks` 是两条独立路径。后者继续只绑定 registration-owned Observable；前者按稳定 slot inject face 缓存定义，并按稳定 render occurrence 绑定 factory 和 Hook。`useTurnData()` 订阅 `turn.data.source(key)`，其他 Location-data key 或 Session snapshot 的发布不会通知它。
 
-标准 `useSession` 仍属于所有 session-scoped slot renderer 的公开能力，`useTurnData()` 是收窄常见读取方式而不是权限沙箱。全窗口统计或任意对象索引仍可显式使用 Session snapshot；它们不能伪装成“当前 Node 的 Turn data”。
+标准 `useSession` 仍属于所有 session-scoped slot renderer 的公开能力，但 `ChatNodeSeat` 不再需要它或聚合 `useChat`。`useTurnData()` 是收窄常见读取方式而不是权限沙箱。全窗口统计或任意对象索引仍可显式使用 Session snapshot；它们不能伪装成“当前 Node 的 Turn data”。
 
 Assistant streaming 到 final、Tool running 到 settled 始终留在同一个 Seat，只更新 data 和必要的排序属性。结算不会因跨 parent 移动而重置组件内部 State。
 
@@ -418,7 +418,7 @@ State update 与 publication cadence 分离后，Assistant 的每条 live delta
 
 inactive target 会保留 Definition State 和 target Context 索引，但不保留 builder、已物化 Node 或 snapshot。已挂载的内建或第三方 View 通过正常订阅激活自己的 target；已经打开的 target 则继续接收增量更新。
 
-Step/Turn 是业务间共享聚合的稳定宿主。Turn Tail 和 Deliverables 无需由 renderer 扫描全局 Nodes 即可派生值；Slot-level `useTurnData()` 把常见读取限制到当前 Node 所属 Turn，并通过 selector equality 隔离无关更新。
+Step/Turn 是业务间共享聚合的稳定宿主。Turn Tail 和 Deliverables 无需由 renderer 扫描全局 Nodes 即可派生值；Slot-level `useTurnData()` 把常见读取限制到当前 Node 所属 Turn，并通过 keyed Location source 隔离无关更新。
 
 Inbox Context 的保留量随 splice 数和已 claim 消息数增长，不再随其累计前缀增长。该结构消除了重复 state 增长，但不会对持久 Session event 中的消息正文去重，也不会限制已加载 event window。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.i18n.yaml
index 0c56c30caf..321dd79463 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.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 .agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md
-2026-08-11-trajectory-conversation-context-assembly.md: 6a8c41598533d1b277548b04e003c9eaa956f0b0
-2026-08-11-trajectory-conversation-context-assembly.zh.md: 1f5b5eb7ab086adf9f6c91f670ac99ad2c897a1b
+2026-08-11-trajectory-conversation-context-assembly.md: fd246922b0ecce146da00e212ecb8053a939017d
+2026-08-11-trajectory-conversation-context-assembly.zh.md: 2568de889fc3b6c227d9faa51166186b388de18f
diff --git a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md
index 6a8c415985..fd246922b0 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.md
@@ -100,7 +100,7 @@ Trajectory Definition and Builder tests pin Assistant streaming and interruption
 
 Trajectory business assembly now scales with the changed page or keyed Context instead of restarting from the complete raw Event window. Target-owned Definitions can evolve independently from Chat while retaining one Session window and one set of lifecycle rules. Steering becomes a first-class Trajectory record at its actual Step position without adding steering-specific state to Session.
 
-After first activation, the retained stage-oriented Builder still performs work proportional to materialized Trajectory contributions and may sort on publication. Before activation, the target retains Context State and one target index but no Builder, materialized Node, or snapshot. Each Trajectory view mount anchors React layout, timeline, and search data to 50 target Nodes at the current tail; live appends extend that window, and the existing earlier-history action extends its prefix before it requests another Session page. Request numbering and cumulative usage remain derived from the complete resident snapshot. The search index still performs a light linear signature pass when its input layout changes.
+After first activation, the retained stage-oriented Builder still performs work proportional to materialized Trajectory contributions and may sort on publication. Before activation, the target retains Context State and one target index but no Builder, materialized Node, or snapshot. Each Trajectory view mount anchors React layout, timeline, and search data to 50 target Nodes at the current tail; live appends extend that window, and the existing earlier-history action extends its prefix before it requests another Session page. If a replacement window no longer contains the previous tail anchor, the same render uses the replacement's latest Node as its bound and adopts that anchor for subsequent appends. Request numbering and cumulative usage remain derived from the complete resident snapshot. The search index still performs a light linear signature pass when its input layout changes.
 
 Definition authors must provide stable protocol identities. Old Events without a required ID can disappear from the affected Trajectory business view, which is preferable to joining unrelated records or failing history load; producers that require faithful display must log the identity.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.zh.md
index 1f5b5eb7ab..2568de889f 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-11-trajectory-conversation-context-assembly.zh.md
@@ -100,7 +100,7 @@ Trajectory Definition 与 Builder 测试固定 Assistant streaming 与 interrupt
 
 Trajectory 业务组装的成本随变化页面或 keyed Context 增长，不再从完整原始 Event 窗口重新开始。target 自有 Definition 可以独立于 Chat 演进，同时继续共享一份 Session 窗口和一套生命周期规则。steering 会在实际所属 Step 位置成为一等 Trajectory record，不需要向 Session 增加 steering 专属状态。
 
-首次激活后，保留的 stage-oriented Builder 仍会执行与已物化 Trajectory contribution 数量成正比的工作，并可能在发布时排序。激活前，target 保留 Context State 和一个 target 索引，但不保留 Builder、已物化 Node 或 snapshot。每次挂载 Trajectory 视图时，React layout、timeline 与搜索数据都锚定在当前尾部的 50 个 target Node；实时 append 会扩展该窗口，现有更早历史操作则先扩展其前缀，再请求下一个 Session 页面。请求编号与累计用量仍从完整的驻留 snapshot 派生。输入 layout 变化时，搜索索引仍会执行一次轻量线性签名检查。
+首次激活后，保留的 stage-oriented Builder 仍会执行与已物化 Trajectory contribution 数量成正比的工作，并可能在发布时排序。激活前，target 保留 Context State 和一个 target 索引，但不保留 Builder、已物化 Node 或 snapshot。每次挂载 Trajectory 视图时，React layout、timeline 与搜索数据都锚定在当前尾部的 50 个 target Node；实时 append 会扩展该窗口，现有更早历史操作则先扩展其前缀，再请求下一个 Session 页面。如果 replacement window 不再包含先前的尾锚，同一次 render 会以替换窗口的最新 Node 为边界，并把该节点采纳为后续 append 的新锚。请求编号与累计用量仍从完整的驻留 snapshot 派生。输入 layout 变化时，搜索索引仍会执行一次轻量线性签名检查。
 
 Definition 作者必须提供稳定的协议标识。缺少必要 ID 的旧 Event 可能不会出现在受影响的 Trajectory 业务视图中；与合并无关记录或让历史加载失败相比，这是更安全的退化方式。要求完整展示的生产方必须记录该标识。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.i18n.yaml
index a1245a8831..6de3fe99ef 100644
--- a/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.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 .agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.md
-2026-08-20-client-session-conversation-ownership.md: 12e137209bb43d21c3437d2ce5e9d2f9180bbc77
-2026-08-20-client-session-conversation-ownership.zh.md: f0d9861eeafc07481c536b85f5ba9667573a66ef
+2026-08-20-client-session-conversation-ownership.md: 34848b3d9be4046993f11290a96f963d9cc78bba
+2026-08-20-client-session-conversation-ownership.zh.md: 48557a2fc81a71858cc38c96fea630c0aa190c89
diff --git a/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.md b/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.md
index 12e137209b..34848b3d9b 100644
--- a/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.md
@@ -298,7 +298,7 @@ Draft and input state belong to Conversation UI and do not enter the Session sna
 
 `client/ui-chat` registers target id `chat` and owns the Chat snapshot builder, Conversation Node definitions, keyed node renderers, selection, details, statistics, locale, and Tool-inspection collaboration.
 
-It registers the `chat` target source through `ctx.uiSession.provide()`. `ChatNodeSeat` and internal Chat consumers use `useChat` instead of passing `useConversation(snapshot => snapshot.views.get('chat'))`.
+It registers the `chat` target source through `ctx.uiSession.provide()`. `ChatView` uses `useChat` for aggregate order, navigation, and timeline reads; each `ChatNodeSeat` receives identity-stable Node and Turn-process sources from that snapshot and does not subscribe to the aggregate source.
 
 Only visible non-command Chat Nodes activate Chat. Ordinary command-only history keeps the Hero visible; the `/goal` `command-input` Node activates a fresh Conversation.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.zh.md
index f0d9861eea..48557a2fc8 100644
--- a/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.zh.md
@@ -298,7 +298,7 @@ Draft 与输入状态属于 Conversation UI，不进入 Session snapshot。Queue
 
 `client/ui-chat` 注册 target id `chat`，并拥有 Chat snapshot builder、Conversation Node definitions、keyed node renderers、selection、details、stats、locale 和 tool inspection 协作。
 
-它通过 `ctx.uiSession.provide()` 注册 `chat` target source。`ChatNodeSeat` 和 Chat 内部消费者使用 `useChat`，不再传递 `useConversation(snapshot => snapshot.views.get('chat'))`。
+它通过 `ctx.uiSession.provide()` 注册 `chat` target source。`ChatView` 使用 `useChat` 读取聚合 order、navigation 与 timeline；每个 `ChatNodeSeat` 从该 snapshot 接收身份稳定的 Node 与 Turn-process source，不订阅聚合 source。
 
 Chat activity 只由可见且非 command 的 Chat Node 激活。普通 command-only history 保持 Hero，`/goal` 的 `command-input` Node 激活 fresh Conversation。
 
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.i18n.yaml
index ea99a814e6..997bc12db6 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.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 .agents/notes/implemented/feature/2026-08-03-web-turn-run-time.md
-2026-08-03-web-turn-run-time.md: b6e79b34f45ebe46d9ce752b6333cdfce6fc4dd6
-2026-08-03-web-turn-run-time.zh.md: 73d9be4d2119278f8a78c6858bae353a4ef5d62f
+2026-08-03-web-turn-run-time.md: c77a365d66ea03b50275be21754f38ee449be14f
+2026-08-03-web-turn-run-time.zh.md: ca7fdc6ef12def71efaa3b4267d8833e78cdc548
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.md b/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.md
index b6e79b34f4..c77a365d66 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.md
@@ -12,7 +12,7 @@ The Web chat shows when a message arrived but not how long the agent worked on i
 
 Turn wall time uses the existing logged `turn/start` and `turn/end` timestamps, with no new session events. The client Session folds each in-window pair into `turnTimings`; the actions-owning assistant footer renders `endTime - startTime` as a localized `Ran for {duration}` label after the turn ends. The running `TurnStatus` clock uses the latest timing without an end, so reload preserves elapsed time, steering does not reset it, and a retry starts from its own logged boundary. Both readings use the same localized formatter and whole-second floor. The clock appears only after 15 seconds and is hidden from the live region so screen readers announce the activity status without replaying every tick.
 
-Time chrome (clock and run time) is hover-revealed: message containers opt in with a `data-time-hover-root` attribute, and `MessageIconActions.module.css` fades the time label in on container `:hover`/`:focus-within`. The rule is scoped to `@media (hover: hover)`, so touch devices keep the always-visible label; opacity (not display) keeps the layout stable. Copy/branch icons stay always visible.
+Action chrome is recency-gated on hover-capable devices: the latest user-authored row and latest Turn tail remain visible, while each earlier row fades the complete actions line in on `:hover` or `:focus-within`. Turn tails publish an explicit recency attribute. User and steering rows use a CSS following-sibling selector over their existing flow-kind attributes, so no mounted message subscribes to and reverse-scans the aggregate Chat snapshot. Touch devices keep every action line visible, and opacity preserves layout.
 
 ## Alternatives considered
 
@@ -20,8 +20,8 @@ Time chrome (clock and run time) is hover-revealed: message containers opt in wi
 
 **Anchoring the live clock to component mount.** Simpler, but a mid-turn reload would restart the clock at zero and disagree with the eventual footer label. Mount time remains only the fallback when `turn/start` is outside the loaded window.
 
-**Hiding the whole actions row until hover.** Copy and branch are affordances worth discovering, and row-level show/hide risks layout shift. Only the passive time text is hover-gated.
+**Compute the latest user-authored row inside every message renderer.** Rejected because each mounted row would subscribe to the aggregate Chat snapshot and reverse-scan its order whenever any Chat value changed. The flow already expresses row order and kind in the DOM, so CSS owns this visual recency rule.
 
 ## Consequences
 
-Turn duration is visible live and after settlement without new session events, and both readings share exact log boundaries and formatting. The settled duration includes activity after the last assistant text up to `turn/end`; the label is absent when `turn/start` is outside the loaded window. Time chrome no longer competes with message content at rest, and the ticking clock remains visual rather than repeatedly announced.
+Turn duration is visible live and after settlement without new session events, and both readings share exact log boundaries and formatting. The settled duration includes activity after the last assistant text up to `turn/end`; the label is absent when `turn/start` is outside the loaded window. Earlier action rows do not compete with message content at rest, their hidden opacity still reserves layout, and the ticking clock remains visual rather than repeatedly announced.
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.zh.md
index 73d9be4d21..ca7fdc6ef1 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-turn-run-time.zh.md
@@ -12,7 +12,7 @@ Web 聊天界面会显示消息的到达时间，却不显示 agent（智能体
 
 轮次实际耗时（wall time）采用日志中已有的 `turn/start` 和 `turn/end` 时间戳，不新增任何会话事件。客户端 Session 将加载窗口内的每对边界归并到 `turnTimings` 中；轮次结束后，承载操作图标的 assistant 页脚把 `endTime - startTime` 渲染为本地化的 `Ran for {duration}` 标签。运行中的 `TurnStatus` 时钟采用最新一条没有结束时间的计时记录，因此重新加载会保留已用时长，steering（中途引导）不会重置计时，重试也从自身的日志边界开始。两处读数共用同一个本地化格式化器，并向下取整到整秒。该时钟在 15 秒后才出现，并从实时区域中隐藏，因此屏幕阅读器会播报活动状态而不会重复播报每次时钟跳动。
 
-时钟与运行时长这类时间附属元素（time chrome）在悬停时才显示：消息容器通过 `data-time-hover-root` 属性显式启用该行为，`MessageIconActions.module.css` 在容器处于 `:hover`/`:focus-within` 时以淡入方式显示时间标签。该规则限定在 `@media (hover: hover)` 之内，触屏设备因此保持标签始终可见；显隐通过 opacity（而非 display）实现，布局保持稳定。复制与分支图标始终可见。
+在支持 hover 的设备上，操作附属元素按新近程度显示：最新的用户消息行与最新 Turn 尾部保持可见，每个更早的行只在 `:hover` 或 `:focus-within` 时淡入完整操作行。Turn 尾部发布显式的新近属性；用户与 steering 行通过既有 flow-kind 属性上的 CSS 后继兄弟选择器判定，因此每个已挂载消息都无需订阅并反向扫描聚合 Chat snapshot。触屏设备保持每条操作行可见，opacity 则保持布局稳定。
 
 ## 考虑过的替代方案
 
@@ -20,8 +20,8 @@ Web 聊天界面会显示消息的到达时间，却不显示 agent（智能体
 
 **将实时时钟锚定到组件挂载时刻。** 更简单，但轮次进行中重新加载会让时钟从零重新计时，并与最终的页脚标签不一致。仅当 `turn/start` 位于已加载窗口之外时，才回退到挂载时刻。
 
-**将整个操作行隐藏至悬停时才显示。** 复制与分支是值得让用户发现的操作入口，而整行级别的显隐切换有布局偏移的风险。只有被动的时间文本由悬停控制显隐。
+**在每个消息 renderer 内计算最新的用户消息行。** 不采用：每个已挂载行都会订阅聚合 Chat snapshot，并在任意 Chat 值变化时反向扫描 order。现有 DOM flow 已表达行顺序和 kind，因此该视觉新近规则归 CSS 所有。
 
 ## 后果
 
-轮次时长在运行中和结束后都可见，且不需要新的会话事件；两处读数共用精确的日志边界和格式化方式。结束后的时长包括最后一条 assistant 文本之后、直至 `turn/end` 的活动；若 `turn/start` 位于已加载窗口之外，则不显示标签。未交互时，时间附属元素不再与消息内容争夺注意力，持续跳动的时钟也只保留视觉呈现，不会被重复播报。
+轮次时长在运行中和结束后都可见，且不需要新的会话事件；两处读数共用精确的日志边界和格式化方式。结束后的时长包括最后一条 assistant 文本之后、直至 `turn/end` 的活动；若 `turn/start` 位于已加载窗口之外，则不显示标签。较早的操作行在未交互时不与消息内容争夺注意力，透明隐藏仍保留布局，持续跳动的时钟也只保留视觉呈现，不会被重复播报。
diff --git a/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.i18n.yaml b/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.i18n.yaml
index 81672750b0..8c89cd5ed6 100644
--- a/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.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 .agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.md
-2026-08-14-web-turn-process-folding.md: fd0015dc915a296725344cd3f4ae05124089adf6
-2026-08-14-web-turn-process-folding.zh.md: 47b1a36bd75695a2f04dfed654d45ec81d2b8bc9
+2026-08-14-web-turn-process-folding.md: e0d666a0e5c744347ecb0f769aa4354481406ce4
+2026-08-14-web-turn-process-folding.zh.md: cacf7ecfdc37f0f155b0eedb894550fe9740dd0d
diff --git a/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.md b/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.md
index fd0015dc91..e0d666a0e5 100644
--- a/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.md
+++ b/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.md
@@ -14,11 +14,13 @@ The Host-backed `ui-chat.transcriptView` preference selects `normal` or `compact
 
 In Compact mode, a Turn remains fully expanded while it is open. At `turn/end`, its latest Step becomes a final-answer boundary only when it contains user-facing Assistant reply content—non-blank text, an image, or an unknown visible block—and contains no Tool-call block. The answer remains visible. Context injection, reasoning, earlier Assistant material, Tool rows, and Retry rows before that boundary form one process disclosure. System prompt, User, and steering rows remain independent and never join the group. Completed, aborted, interrupted, failed, and max-token Turns use the same terminal projection; error, max-token, and turn-tail rows remain outside the group. A closed Turn with no final answer keeps all process evidence visible.
 
-The Turn-scoped `turn-process` Definition derives the first model or Tool evidence, the latest Step's finalized answer boundary, reply-bearing durable Assistant-message count before that answer, and Tool-call counts from log events plus Step Location data. Shipped subagent delegation names (`subagent` and `subagent_*`) increment the subagent count instead of the ordinary Tool-call count, so the categories never overlap. Context injection remains process evidence without incrementing a summary count; System prompt is independent, stays visible, and remains before the opening User. It publishes an encoded scalar so unchanged facts retain value identity during streaming and contributes one stable control Chat Node. The Chat target positions opening User or steering input before process candidates from their first projection, then inserts the synthetic control between that input and the process rows. Without opening human input, the control stays before the earliest process candidate from its first appearance. Answer finalization, Retry, later Steps, completion, and manual expansion therefore change visibility without changing existing nodes' relative order, as specified by [stable Turn-process ordering](../bug-fix/2026-08-26-stable-turn-process-order.md). Each process member classifies itself from the Turn specification. Only the control and answer Seats subscribe to their Turn's content-revisioned Location key list and derive external process evidence plus independent-input spacing from that bounded list, so data-only updates refresh layout without rebuilding the global order. Turn status and loaded-window completeness then gate foldability: an open Turn never folds, and a partial history exposes neither the control nor hidden members. The control Node exists from the first process evidence onward but its Seat remains hidden until the closed Turn has a final answer and complete history. Once visible, it omits every zero-valued segment, uses `Thought for a while` when all three counts are zero, and places a full-width divider below the summary.
+The Turn-scoped `turn-process` Definition derives the first model or Tool evidence, the latest Step's finalized answer boundary, reply-bearing durable Assistant-message count before that answer, and Tool-call counts from log events plus Step Location data. Shipped subagent delegation names (`subagent` and `subagent_*`) increment the subagent count instead of the ordinary Tool-call count, so the categories never overlap. Context injection remains process evidence without incrementing a summary count; System prompt is independent, stays visible, and remains before the opening User. The Definition publishes one immutable `TurnProcessSpec` directly to both Turn Location data and its stable control Chat Node; continuing open-stream updates reuse both values while their fields remain unchanged. The Chat target positions opening User or steering input before process candidates from their first projection, then inserts the synthetic control between that input and the process rows. Without opening human input, the control stays before the earliest process candidate from its first appearance. Answer finalization, Retry, later Steps, completion, and manual expansion therefore change visibility without changing existing nodes' relative order, as specified by [stable Turn-process ordering](../bug-fix/2026-08-26-stable-turn-process-order.md).
+
+`ChatTurnProcessProjector` owns the cross-Node presentation facts. It scans only an affected Turn when Node structure, `TurnProcessSpec`, or Turn status changes, retains an equal presentation by reference, and publishes a stable process source only to Seats in a changed Turn. Each Seat classifies its own membership and answer role from that shared presentation without reading the global Chat snapshot, scanning the Turn, or encoding and decoding a signature. Turn status and loaded-window completeness gate foldability: an open Turn never folds, and a partial history exposes neither the control nor hidden members. The control Node exists from the first process evidence onward but its Seat remains hidden until the closed Turn has a final answer and complete history. Once visible, it omits every zero-valued segment, uses `Thought for a while` when all three counts are zero, and places a full-width divider below the summary.
 
 The Chat target binds the durable transcript preference through the shared settings scope and keeps per-Turn interaction state in its session-scoped Chat store. `ChatView` renders each business Node through one stable keyed `ChatNodeSeat`; adding the process control does not reorder existing keys, and Compact mode changes the Seat wrapper's `hidden` attribute without reparenting or unmounting a Tool, Assistant, Context, or Retry renderer. The Seat passes the same process state through `ChatNodeOwnerProps`, so the final Assistant renderer hides reasoning blocks from its own Step while leaving reply blocks visible; wrapper visibility and inline reasoning therefore share one UI-state source.
 
-Closed process members use `hidden="until-found"`. A `beforematch` event on any member opens the shared group in supporting browsers. The Chat column applies spacing only between visible siblings because hidden-until-found members retain searchable zero-height boxes; the control's divider spans the content width, and a closed process control uses an 8px answer gap only when no independent input intervenes, while expansion restores the ordinary 16px row spacing. In Compact mode, the non-persisted session store contains only manually expanded Turn-and-answer-Step generations; absence means collapsed, and a different answer generation starts collapsed. Every eligible closed Turn therefore uses the same default regardless of whether it completed live, appeared after Load earlier, or closed while the reader was away from the tail. This can reflow content above the reader when a Turn closes or history becomes complete. An automatic collapse that would hide a focused process descendant opens the shared group instead, leaving keyboard focus in place; a manual close focuses the process control before hiding its members. If Load earlier is present, every process remains expanded and its control stays hidden; once history is complete, eligible groups immediately use the collapsed default. A fresh page load restores the durable Normal or Compact preference; per-Turn manual expansion survives only view remounts within the same page lifetime. Switching to Normal reveals every process row, while switching back to Compact reapplies the page-lifetime manual overrides over the collapsed default.
+Closed process members use `hidden="until-found"`. A `beforematch` event on any member opens the shared group in supporting browsers. The Chat column applies spacing only between visible siblings because hidden-until-found members retain searchable zero-height boxes; the control's divider spans the content width, and a closed process control uses an 8px answer gap only when no independent input intervenes, while expansion restores the ordinary 16px row spacing. A collapsed Think row follows the latest streamed line through CSS, has one font-axis-adjusted fixed row height, and applies size and layout containment; expansion removes that containment and restores natural prose height. In Compact mode, the non-persisted session store contains only manually expanded Turn-and-answer-Step generations; absence means collapsed, and a different answer generation starts collapsed. Every eligible closed Turn therefore uses the same default regardless of whether it completed live, appeared after Load earlier, or closed while the reader was away from the tail. This can reflow content above the reader when a Turn closes or history becomes complete. An automatic collapse that would hide a focused process descendant opens the shared group instead, leaving keyboard focus in place; a manual close focuses the process control before hiding its members. If Load earlier is present, every process remains expanded and its control stays hidden; once history is complete, eligible groups immediately use the collapsed default. A fresh page load restores the durable Normal or Compact preference; per-Turn manual expansion survives only view remounts within the same page lifetime. Switching to Normal reveals every process row, while switching back to Compact reapplies the page-lifetime manual overrides over the collapsed default.
 
 This presentation composes with [Conversation Node assembly](../architecture/2026-08-09-client-conversation-node-assembly.md): Definitions own deterministic process facts, the Seat owns shared interaction state, and keyed renderers remain independent. The [log-ordered human transcript](../bug-fix/2026-07-30-web-transcript-log-ordered-projection.md) remains complete because folding changes no session event or model input.
 
diff --git a/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.zh.md b/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.zh.md
index 47b1a36bd7..cacf7ecfdc 100644
--- a/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-14-web-turn-process-folding.zh.md
@@ -14,11 +14,13 @@ Status: implemented
 
 在 Compact 模式下，轮次打开期间始终完整展开。到 `turn/end` 时，只有当最近步骤包含面向用户的 Assistant 回复内容——非空文本、图片或未知可见块——并且不含工具调用块时，该步骤才成为最终正文边界。正文保持可见。边界之前的上下文注入、推理、较早 Assistant 内容、工具行与重试行统一进入一条过程 disclosure。系统提示词、用户消息与 steering 消息保持独立，绝不加入过程组。已完成、已取消、已中断、失败和达到最大 token 的轮次使用同一终态投影；错误、最大 token 与 turn-tail 行留在过程组外。关闭时没有最终正文的轮次会保留全部过程证据。
 
-轮次作用域的 `turn-process` Definition 根据日志事件与步骤 Location data 推导首条模型或工具证据、最近步骤的已定稿正文边界、该正文之前带回复内容的持久 Assistant 消息数和工具调用计数。随产品交付的 subagent 委派名称（`subagent` 与 `subagent_*`）只增加 subagent 计数，不增加普通工具调用计数，因此两类不会重叠。上下文注入仍是过程证据但不增加摘要计数；系统提示词保持独立、持续可见，并始终位于开场 User 上方。它发布编码后的标量，使未变化的事实在流式期间保持值相等，并贡献一个稳定控制 Chat Node。Chat target 从首次投影起就把开场 User 或 steering 输入放在过程候选之前，再把合成控制行插入该输入与过程行之间。没有开场人工输入时，控制行从首次出现起就位于最早的过程候选之前。因此正文定稿、Retry、后续步骤、完成状态与手动展开只改变可见性，不改变既有节点的相对顺序，具体规则由[稳定的轮次过程排序](../bug-fix/2026-08-26-stable-turn-process-order.zh.md)说明。每个过程成员根据轮次规格判断自身归属。只有控制 Seat 与正文 Seat 订阅所属轮次在内容变化时更新的 Location key 列表，并在这份受限列表内推导外部过程证据和独立输入间距，因此纯数据更新会刷新布局，而不必重建全局顺序。轮次状态与已加载窗口是否完整随后共同决定能否折叠：打开中的轮次绝不折叠，历史不完整时也既不显示控件又不隐藏成员。控制 Node 从首条过程证据出现起一直存在，但其 Seat 会保持隐藏，直至关闭的轮次拥有最终正文且历史完整；显示后，它会省略每个值为 0 的分段，三项全为 0 时使用「已思考」（英文为 `Thought for a while`），并在摘要下方绘制通栏分隔线。
+轮次作用域的 `turn-process` Definition 根据日志事件与步骤 Location data 推导首条模型或工具证据、最近步骤的已定稿正文边界、该正文之前带回复内容的持久 Assistant 消息数和工具调用计数。随产品交付的 subagent 委派名称（`subagent` 与 `subagent_*`）只增加 subagent 计数，不增加普通工具调用计数，因此两类不会重叠。上下文注入仍是过程证据但不增加摘要计数；系统提示词保持独立、持续可见，并始终位于开场 User 上方。Definition 把同一份不可变 `TurnProcessSpec` 直接发布到 Turn Location data 与稳定控制 Chat Node；持续 open stream 的更新在字段不变时复用两份值。Chat target 从首次投影起就把开场 User 或 steering 输入放在过程候选之前，再把合成控制行插入该输入与过程行之间。没有开场人工输入时，控制行从首次出现起就位于最早的过程候选之前。因此正文定稿、Retry、后续步骤、完成状态与手动展开只改变可见性，不改变既有节点的相对顺序，具体规则由[稳定的轮次过程排序](../bug-fix/2026-08-26-stable-turn-process-order.zh.md)说明。
+
+`ChatTurnProcessProjector` 拥有跨 Node 的呈现事实。只有 Node 结构、`TurnProcessSpec` 或 Turn 状态变化时，它才扫描受影响的 Turn；相等的呈现会按引用保留，且只有变化 Turn 内的 Seat 会收到稳定 process source 的发布。每个 Seat 从共享呈现判断自身的过程成员与正文角色，无需读取全局 Chat snapshot、扫描 Turn 或编码再解码签名。Turn 状态与已加载窗口是否完整共同决定能否折叠：打开中的 Turn 绝不折叠，历史不完整时也既不显示控件又不隐藏成员。控制 Node 从首条过程证据出现起一直存在，但其 Seat 会保持隐藏，直至关闭的 Turn 拥有最终正文且历史完整；显示后，它会省略每个值为 0 的分段，三项全为 0 时使用「已思考」（英文为 `Thought for a while`），并在摘要下方绘制通栏分隔线。
 
 Chat target 通过共享 settings scope 绑定持久化的 transcript 偏好，并把逐轮交互状态保存在会话作用域的 Chat store 中。`ChatView` 通过稳定的 keyed `ChatNodeSeat` 直接渲染每个业务 Node；加入过程控件不会重排既有 key，Compact 模式只改变 Seat wrapper 的 `hidden` 属性，不会重新挂接或卸载工具、Assistant、上下文或重试 renderer。Seat 通过 `ChatNodeOwnerProps` 传递同一份过程状态，因此最终 Assistant renderer 会隐藏自身步骤中的推理块，同时保留回复块；wrapper 可见性与行内推理共用一个 UI 状态真源。
 
-收起的过程成员使用 `hidden="until-found"`。在支持该能力的浏览器中，任一成员触发 `beforematch` 都会打开共享过程组。由于 hidden-until-found 成员会保留可搜索的零高度 box，Chat 列只在可见的相邻成员之间设置间距；控件分隔线横跨内容宽度，只有中间没有独立输入时，收起的过程控件才与正文相隔 8px，展开后恢复普通的 16px 行间距。在 Compact 模式下，不持久化的会话 store 只保存用户手动展开的「轮次 + 正文步骤」generation；没有记录即为收起，不同正文 generation 默认收起。因此，每个合格的已关闭轮次都使用相同默认状态，不区分实时完成、在「加载更早」后出现，或在读者离开尾部时结束。这可能在轮次关闭或历史变完整时让读者上方的内容重排。若自动收起会隐藏过程成员中的键盘焦点，则改为打开共享过程组并把焦点留在原处；手动收起会先把焦点移到过程控件，再隐藏成员。存在「加载更早」时，每个过程保持展开且控件隐藏；历史加载完整后，合格过程立即使用默认收起状态。页面重新加载会恢复持久化的 Normal 或 Compact 偏好；逐轮手动展开只在同一页面生命周期内的 view remount 之间保留。切换到 Normal 会显示所有过程行，切回 Compact 时会在默认收起状态上重新应用当前页面生命周期内的手动展开记录。
+收起的过程成员使用 `hidden="until-found"`。在支持该能力的浏览器中，任一成员触发 `beforematch` 都会打开共享过程组。由于 hidden-until-found 成员会保留可搜索的零高度 box，Chat 列只在可见的相邻成员之间设置间距；控件分隔线横跨内容宽度，只有中间没有独立输入时，收起的过程控件才与正文相隔 8px，展开后恢复普通的 16px 行间距。收起的 Think 行通过 CSS 跟随最新流式文本行，具有随字号轴变化的单行固定高度，并启用 size 与 layout containment；展开时移除 containment，正文恢复自然高度。在 Compact 模式下，不持久化的会话 store 只保存用户手动展开的「Turn + 正文 Step」generation；没有记录即为收起，不同正文 generation 默认收起。因此，每个合格的已关闭 Turn 都使用相同默认状态，不区分实时完成、在「加载更早」后出现，或在读者离开尾部时结束。这可能在 Turn 关闭或历史变完整时让读者上方的内容重排。若自动收起会隐藏过程成员中的键盘焦点，则改为打开共享过程组并把焦点留在原处；手动收起会先把焦点移到过程控件，再隐藏成员。存在「加载更早」时，每个过程保持展开且控件隐藏；历史加载完整后，合格过程立即使用默认收起状态。页面重新加载会恢复持久化的 Normal 或 Compact 偏好；逐 Turn 手动展开只在同一页面生命周期内的 view remount 之间保留。切换到 Normal 会显示所有过程行，切回 Compact 时会在默认收起状态上重新应用当前页面生命周期内的手动展开记录。
 
 这项展示与 [Conversation Node 组装](../architecture/2026-08-09-client-conversation-node-assembly.zh.md)共同成立：Definition 持有确定性的过程事实，Seat 持有共享交互状态，keyed renderer 保持独立。[按日志顺序投影的人工 transcript](../bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md)保持完整，因为折叠不改变任何会话事件或模型输入。
 
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index e6faea81ac..2d341e1897 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -204,7 +204,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.assistant-actions\', () => ctx.slots.register(\n      { name: \'conversation.chat.assistant-actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:205',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:206',
   },
   {
     key: 'conversation.chat.commandview',
@@ -249,7 +249,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.commandview\', () => ctx.slots.register(\n      { name: \'conversation.chat.commandview\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:193',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:194',
   },
   {
     key: 'conversation.chat.node',
@@ -313,7 +313,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.node\', () => ctx.slots.register(\n      { name: \'conversation.chat.node\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:174',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:175',
   },
   {
     key: 'conversation.chat.turnTail',
@@ -358,7 +358,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.turnTail\', () => ctx.slots.register(\n      { name: \'conversation.chat.turnTail\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:199',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:200',
   },
   {
     key: 'conversation.composer',
@@ -532,7 +532,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.details.tool\', () => ctx.slots.register(\n      { name: \'conversation.details.tool\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:211',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:212',
   },
   {
     key: 'conversation.hero.agentPreset',
@@ -1010,7 +1010,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.message.images\', () => ctx.slots.register(\n      { name: \'conversation.message.images\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:187',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:188',
   },
   {
     key: 'conversation.session',

From de07b4c05bd105356eddad1c907224e5c0d8a70d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:46:08 +0800
Subject: [PATCH 27/37] chore(ui-chat): document local keyed sources

---
 .../src/client/conversation-nodes/chat-snapshot-builder.ts  | 2 ++
 .../client/conversation-nodes/turn-process-presentation.ts  | 6 +++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
index 1ef2b16d3f..6fa7671da6 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -38,6 +38,7 @@ function cachedSource<Key, Source>(
   return source
 }
 
+/* jscpd:ignore-start -- Chat Node sources keep publication state inside the keyed Chat store. */
 class MutableChatSource<Value> {
   private readonly listeners = new Set<() => void>()
   private published: Value
@@ -63,6 +64,7 @@ class MutableChatSource<Value> {
     notifySubscribers(this.listeners, this.label)
   }
 }
+/* jscpd:ignore-end */
 
 class MutableChatNodeStore implements ChatNodeStore {
   private readonly byKey = new Map<string, ChatConversationViewNode>()
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts
index 1c9a4acf81..a49ae6031b 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts
@@ -74,7 +74,11 @@ function derivePresentation(
 export class ChatTurnProcessProjector {
   private presentations = new Map<number, ChatTurnProcessPresentation>()
 
-  /** @param node - current Chat Node. @returns its Turn's process presentation, when present. */
+  /**
+   * Read the retained process presentation for a Node's Turn.
+   * @param node - Current Chat Node.
+   * @returns The Turn's process presentation, when present.
+   */
   get(node: ChatNode | undefined): ChatTurnProcessPresentation | undefined {
     const turn = nodeTurn(node)
     return turn === undefined ? undefined : this.presentations.get(turn)

From b8a19413e94c49451a6df81eb36baa7915ed2415 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 22:01:18 +0800
Subject: [PATCH 28/37] fix(client): satisfy strict observable contracts

---
 .../ui-chat/src/client/contract/snapshot.ts   |  8 ++---
 .../tests/chat-node-source.client.spec.ts     |  2 +-
 .../src/client/contract/conversation.ts       | 33 +++++++++++--------
 3 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/packages/client/ui-chat/src/client/contract/snapshot.ts b/packages/client/ui-chat/src/client/contract/snapshot.ts
index b6526a60c3..c7544d4a16 100644
--- a/packages/client/ui-chat/src/client/contract/snapshot.ts
+++ b/packages/client/ui-chat/src/client/contract/snapshot.ts
@@ -15,17 +15,17 @@ export type {
 /** Per-key observable used by one mounted Chat Node Seat. */
 export interface ChatNodeSource {
   /** @returns the current Node for this source's stable key. */
-  getSnapshot(): ChatConversationViewNode | undefined
+  readonly getSnapshot: () => ChatConversationViewNode | undefined
   /** @param listener - callback for changes to this key. @returns the unsubscribe function. */
-  subscribe(listener: () => void): () => void
+  readonly subscribe: (listener: () => void) => () => void
 }
 
 /** Per-key observable for the Turn-process presentation surrounding one Chat Node. */
 export interface ChatNodeProcessSource {
   /** @returns the current presentation, or absence outside a projected Turn process. */
-  getSnapshot(): ChatTurnProcessPresentation | undefined
+  readonly getSnapshot: () => ChatTurnProcessPresentation | undefined
   /** @param listener - callback for presentation changes. @returns the unsubscribe function. */
-  subscribe(listener: () => void): () => void
+  readonly subscribe: (listener: () => void) => () => void
 }
 
 /** Stable live per-key reader for Chat nodes. */
diff --git a/packages/client/ui-chat/tests/chat-node-source.client.spec.ts b/packages/client/ui-chat/tests/chat-node-source.client.spec.ts
index 71f2cecf12..1209380799 100644
--- a/packages/client/ui-chat/tests/chat-node-source.client.spec.ts
+++ b/packages/client/ui-chat/tests/chat-node-source.client.spec.ts
@@ -24,7 +24,7 @@ function userNode(index: number, text = `message ${String(index)}`): ChatConvers
       content: [{ type: 'text', text }],
       source: null,
     },
-  } as ChatConversationViewNode
+  }
 }
 
 describe('Chat Node keyed sources', () => {
diff --git a/packages/client/ui-conversation/src/client/contract/conversation.ts b/packages/client/ui-conversation/src/client/contract/conversation.ts
index d37ace2fd4..9cdad209cf 100644
--- a/packages/client/ui-conversation/src/client/contract/conversation.ts
+++ b/packages/client/ui-conversation/src/client/contract/conversation.ts
@@ -16,9 +16,9 @@ export interface ConversationStepDataMap {}
 /** Observable value for one independently owned Location-data key. */
 export interface ConversationLocationDataSource<Value> {
   /** @returns the current value. */
-  getSnapshot(): Value
+  readonly getSnapshot: () => Value
   /** @param listener - callback for value changes. @returns the unsubscribe function. */
-  subscribe(listener: () => void): () => void
+  readonly subscribe: (listener: () => void) => () => void
 }
 
 /** Stable keyed reader for independently owned Location business values. */
@@ -47,30 +47,35 @@ interface ConversationLocationDataValue {
   readonly value: unknown
 }
 
-type RegisteredTurnData = {
-  [Key in keyof ConversationTurnDataMap & string]: {
+type RegisteredTurnData<DataMap extends object> = {
+  [Key in Extract<keyof DataMap, string>]: {
     readonly kind: 'turn'
     readonly turn: number
     readonly key: Key
-    readonly value: ConversationTurnDataMap[Key]
+    readonly value: DataMap[Key]
   }
-}[keyof ConversationTurnDataMap & string]
+}[Extract<keyof DataMap, string>]
 
-type RegisteredStepData = {
-  [Key in keyof ConversationStepDataMap & string]: {
+type RegisteredStepData<DataMap extends object> = {
+  [Key in Extract<keyof DataMap, string>]: {
     readonly kind: 'step'
     readonly turn: number
     readonly step: number
     readonly key: Key
-    readonly value: ConversationStepDataMap[Key]
+    readonly value: DataMap[Key]
   }
-}[keyof ConversationStepDataMap & string]
+}[Extract<keyof DataMap, string>]
+
+type ConversationLocationDataOf<TurnData extends object, StepData extends object> =
+  [keyof TurnData | keyof StepData] extends [never]
+    ? ConversationLocationDataValue
+    : RegisteredTurnData<TurnData> | RegisteredStepData<StepData>
 
 /** One Definition-owned value attached to an Engine-owned Turn or Step. */
-export type ConversationLocationData =
-  [keyof ConversationTurnDataMap | keyof ConversationStepDataMap] extends [never]
-    ? ConversationLocationDataValue
-    : RegisteredTurnData | RegisteredStepData
+export type ConversationLocationData = ConversationLocationDataOf<
+  ConversationTurnDataMap,
+  ConversationStepDataMap
+>
 
 /** Immutable resolved boundary for one Agent step. */
 export interface StepLocation {

From 577f0cf7d9f4f88c794c3d2d82c61e3550827b62 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 22:20:08 +0800
Subject: [PATCH 29/37] refactor(client): bind keyed chat sources in renderer

---
 packages/client/ui-chat/src/client/apply.ts   | 10 ++-
 .../ui-chat/src/client/chat/ChatNodeSeat.tsx  | 17 ++--
 .../ui-chat/src/client/chat/ChatView.tsx      | 10 ++-
 .../ui-chat/src/client/contract/slots.ts      | 23 +++++-
 .../ui-chat/tests/chat-view.client.spec.tsx   | 81 ++++++++++++++-----
 .../ui-renderer/src/client/scoped-slots.tsx   | 26 +++---
 .../tests/scoped-slots.client.spec.tsx        | 35 ++++++++
 packages/client/ui-slots/src/index.ts         | 37 ++++++++-
 8 files changed, 185 insertions(+), 54 deletions(-)

diff --git a/packages/client/ui-chat/src/client/apply.ts b/packages/client/ui-chat/src/client/apply.ts
index f36ba12728..0c7d87f344 100644
--- a/packages/client/ui-chat/src/client/apply.ts
+++ b/packages/client/ui-chat/src/client/apply.ts
@@ -104,10 +104,16 @@ export function apply(ctx: Context): void {
       },
       store: chatStore,
       inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => {
-        const session = ctx.sessions.binding(sessionId)?.session
-        if (session === undefined) throw new Error(`ui-chat: unknown session "${sessionId}"`)
+        const binding = ctx.sessions.binding(sessionId)
+        if (binding === undefined) throw new Error(`ui-chat: unknown session "${sessionId}"`)
+        const session = binding.session
+        const chat = chatSource(binding)
         return {
           hooks: { transcriptView: transcriptView.mode },
+          keyedHooks: {
+            chatNode: key => chat.getSnapshot().nodes.source(key),
+            chatNodeProcess: key => chat.getSnapshot().nodes.processSource(key),
+          },
           openDetails: (target) => {
             actions.select(target)
             ctx.layout.openDetails()
diff --git a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
index 0476b71132..4f51486398 100644
--- a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
@@ -1,17 +1,17 @@
-import { memo, useCallback, useMemo, useSyncExternalStore } from 'react'
+import { memo, useCallback, useMemo } from 'react'
 import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ConversationLocationDataStore, ConversationTurnDataMap } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts'
 import type { ChatNode } from '../contract/chat-nodes.ts'
-import type { ChatNodeProcessSource, ChatNodeSource } from '../contract/snapshot.ts'
 import { TURN_PROCESS_INDEPENDENT_KINDS } from '../contract/turn-process.ts'
 import { storedTurnProcessEntry } from '../stores.ts'
 import { useSearchableHidden } from './searchable-hidden.ts'
 import css from './ChatView.module.css'
 
 interface ChatNodeSeatProps extends ChatNodeOwnerProps {
-  readonly nodeSource: ChatNodeSource
-  readonly processSource: ChatNodeProcessSource
+  readonly nodeKey: string
+  readonly useChatNode: ChatViewSlotProps['useChatNode']
+  readonly useChatNodeProcess: ChatViewSlotProps['useChatNodeProcess']
   readonly historyIncomplete: boolean
   readonly compactTranscript: boolean
   readonly useStore: ChatViewSlotProps['useStore']
@@ -36,17 +36,14 @@ function turnOf(node: ChatNode | undefined): number | undefined {
 
 /** Subscribe, apply Turn-process visibility, and dispatch one stable Context key. */
 export const ChatNodeSeat = memo(function ChatNodeSeat({
-  nodeSource, processSource, historyIncomplete, compactTranscript,
+  nodeKey, useChatNode, useChatNodeProcess, historyIncomplete, compactTranscript,
   selectedCallId, cwd, openFile, inspectCall, forkAt,
   renderMessageImages, fileMentions, useStore, actions, renderSlot, t,
 }: ChatNodeSeatProps) {
-  const node = useSyncExternalStore(nodeSource.subscribe, nodeSource.getSnapshot)
+  const node = useChatNode(nodeKey)
   const routedNode = node as ChatNode | undefined
   const turn = turnOf(routedNode)
-  const processPresentation = useSyncExternalStore(
-    processSource.subscribe,
-    processSource.getSnapshot,
-  )
+  const processPresentation = useChatNodeProcess(nodeKey)
   const processSpec = processPresentation?.spec
   const storedEntry = useStore(state => processSpec === undefined
     ? undefined
diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index 28f789afad..bf58d4c0c7 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -204,8 +204,9 @@ function TurnStatus({ startTime, t }: {
  * ordered business Node crosses the keyed renderer seat.
  */
 export function ChatView({
-  useSession, useChat, useSessions, useStore, actions, renderSlot, sessionId, openFile, loadOlder, loadThrough,
-  loadImage, openView, chatScroll, forkAt, fileMentions, useTranscriptView, useProjection, t,
+  useSession, useChat, useChatNode, useChatNodeProcess, useSessions, useStore, actions, renderSlot,
+  sessionId, openFile, loadOlder, loadThrough, loadImage, openView, chatScroll, forkAt, fileMentions,
+  useTranscriptView, useProjection, t,
 }: ChatViewSlotProps) {
   const order = useChat(s => s.order)
   const nodeStore = useChat(s => s.nodes)
@@ -745,8 +746,9 @@ export function ChatView({
           {order.map(nodeKey => (
             <ChatNodeSeat
               key={nodeKey}
-              nodeSource={nodeStore.source(nodeKey)}
-              processSource={nodeStore.processSource(nodeKey)}
+              nodeKey={nodeKey}
+              useChatNode={useChatNode}
+              useChatNodeProcess={useChatNodeProcess}
               historyIncomplete={hasMore}
               compactTranscript={compactTranscript}
               useStore={useStore}
diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts
index 405a94238f..16daf32b2b 100644
--- a/packages/client/ui-chat/src/client/contract/slots.ts
+++ b/packages/client/ui-chat/src/client/contract/slots.ts
@@ -6,22 +6,31 @@ import type {
   MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, TurnLocation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
-  InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SlotHookFactory,
-  SnapshotSelectorHook,
+  InjectFace, KeyedSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore,
+  SlotHookFactory, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { createChatStore } from '../stores.ts'
 import type { ToolCallId, SelectionTarget } from './store.ts'
-import type { ChatNode, ChatNodeKind } from './chat-nodes.ts'
-import type { ChatSnapshot, CommandNode, CompactionSummaryNode, ToolCallBlock } from './snapshot.ts'
+import type { ChatConversationViewNode, ChatNode, ChatNodeKind } from './chat-nodes.ts'
+import type {
+  ChatNodeProcessSource, ChatNodeSource, ChatSnapshot, ChatTurnProcessPresentation, CommandNode,
+  CompactionSummaryNode, ToolCallBlock,
+} from './snapshot.ts'
 import type { TurnProcessSpec } from './turn-process.ts'
 import type { TranscriptViewMode } from '../../chat-settings.ts'
 
 /** Selector hook over the current Conversation binding's Chat target. */
 export type UseChat = SnapshotSelectorHook<ChatSnapshot>
 
+/** Per-key selector hook over one Chat Node. */
+export type UseChatNode = KeyedSnapshotSelectorHook<ChatConversationViewNode | undefined>
+
+/** Per-key selector hook over one Chat Node's Turn-process presentation. */
+export type UseChatNodeProcess = KeyedSnapshotSelectorHook<ChatTurnProcessPresentation | undefined>
+
 /** Owner currency of the completed-Turn extension chain. */
 export interface TurnTailOwnerProps {
   turn: TurnLocation
@@ -117,6 +126,12 @@ export interface ChatViewInjected {
     /** Persisted completed-Turn transcript presentation. */
     transcriptView: SnapshotStore<TranscriptViewMode>
   }
+  keyedHooks: {
+    /** Resolve the stable source for one Chat Node key. */
+    chatNode: (key: string) => ChatNodeSource
+    /** Resolve the stable Turn-process source for one Chat Node key. */
+    chatNodeProcess: (key: string) => ChatNodeProcessSource
+  }
   openDetails: (target: SelectionTarget) => void
   openFile: (path: string) => Promise<void>
   loadOlder: () => void
diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
index eac7cf3a8b..83d0dc6b9a 100644
--- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
@@ -19,8 +19,9 @@ import type {
 import type { WorkspaceSnapshot } from '@deepseek-ai/dsh-api-workspace-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SessionPendingInteractionSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
+import type { KeyedSnapshotSelectorHook, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import { EMPTY_CONVERSATION_SNAPSHOT } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { createChatStore } from '../src/client/stores.ts'
@@ -204,6 +205,21 @@ function emptyWorkspaces() {
   return bindSnapshotSelector(store)
 }
 
+function bindKeyedSnapshotSelector<Value>(
+  resolve: (key: string) => ObservableSnapshot<Value>,
+): KeyedSnapshotSelectorHook<Value> {
+  const hooks = new WeakMap<object, SnapshotSelectorHook<Value>>()
+  return ((key: string, selector?: (value: Value) => unknown, equal?: (left: unknown, right: unknown) => boolean) => {
+    const source = resolve(key)
+    let useValue = hooks.get(source)
+    if (useValue === undefined) {
+      useValue = bindSnapshotSelector(source)
+      hooks.set(source, useValue)
+    }
+    return useValue(selector ?? ((value: Value) => value), equal)
+  }) as KeyedSnapshotSelectorHook<Value>
+}
+
 function makeHarness(
   init: HarnessUpdate = {},
   sessionOverrides: Partial<SessionSnapshot> = {},
@@ -223,6 +239,12 @@ function makeHarness(
   }
   const session = makeSessionSource({ ...sessionInit, ...sessionOverrides })
   const chatSource = makeChatSource(chatSlice, initialChat ?? chatSnapshot)
+  const useChatNode = bindKeyedSnapshotSelector(
+    key => chatSource.source.getSnapshot().nodes.source(key),
+  )
+  const useChatNodeProcess = bindKeyedSnapshotSelector(
+    key => chatSource.source.getSnapshot().nodes.processSource(key),
+  )
   const openDetails = vi.fn<(t: SelectionTarget) => void>()
   const openFile = vi.fn<(path: string) => Promise<void>>().mockResolvedValue(undefined)
   const loadOlder = vi.fn()
@@ -344,6 +366,8 @@ function makeHarness(
     sessionId: SID,
     useSession: bindSnapshotSelector(session.source),
     useChat: bindSnapshotSelector(chatSource.source),
+    useChatNode,
+    useChatNodeProcess,
     useConversation: bindSnapshotSelector(createSnapshotStore(EMPTY_CONVERSATION_SNAPSHOT)),
     useTrajectory: (() => { throw new Error('unused') }),
     useSessions: emptySessions(),
@@ -421,7 +445,11 @@ function turnProcessControl(container: HTMLElement): HTMLButtonElement | null {
   return container.querySelector<HTMLButtonElement>('[data-turn-process]')
 }
 
-function withSystemPrompt(snapshot: ChatSnapshot, text = '# System'): ChatSnapshot {
+function withSystemPrompt(
+  snapshot: ChatSnapshot,
+  builder = new ChatSnapshotBuilder(),
+  text = '# System',
+): ChatSnapshot {
   const turn = snapshot.timeline.turns.get(1)
   if (turn === undefined) throw new Error('fixture lacks Turn 1')
   const prompt: ChatNode<'system-prompt'> = {
@@ -434,7 +462,7 @@ function withSystemPrompt(snapshot: ChatSnapshot, text = '# System'): ChatSnapsh
     visibility: 'visible',
     data: { text },
   }
-  return new ChatSnapshotBuilder().replace({
+  return builder.replace({
     nodes: [prompt, ...snapshot.nodes.values()],
     timeline: snapshot.timeline,
   })
@@ -1315,25 +1343,10 @@ describe('ChatView', () => {
   })
 
   it('keeps the first System prompt above User and outside Process through completion and expansion', () => {
+    const builder = new ChatSnapshotBuilder()
     const initial = withSystemPrompt(chatSnapshotFixture({
       nodes: [userInTurn(2, 'question', 1), context(3, 'runtime policy', 1)],
-    }))
-    const running = withSystemPrompt(chatSnapshotFixture({
-      nodes: [
-        userInTurn(2, 'question', 1),
-        context(3, 'runtime policy', 1),
-        reasoningAssistant(4, 'inspect', 1, 1),
-      ],
-    }))
-    const completed = withSystemPrompt(chatSnapshotFixture({
-      nodes: [
-        userInTurn(2, 'question', 1),
-        context(3, 'runtime policy', 1),
-        reasoningAssistant(4, 'inspect', 1, 1),
-        assistant(6, 'final answer', 1, 2),
-      ],
-      turnEnds: new Map([[1, 7]]),
-    }))
+    }), builder)
     const h = makeHarness({ chat: initial }, { running: true })
     const view = render(<h.ChatView {...h.props} />)
     const promptRow = view.container.querySelector<HTMLElement>('[data-chat-flow-kind="system-prompt"]')!
@@ -1342,14 +1355,38 @@ describe('ChatView', () => {
     expect(promptRow.getAttribute('hidden')).toBeNull()
     expect(promptRow.hasAttribute('data-turn-process-member')).toBe(false)
 
-    act(() => { h.set({ chat: running, running: true }) })
+    act(() => {
+      h.set({
+        chat: withSystemPrompt(chatSnapshotFixture({
+          nodes: [
+            userInTurn(2, 'question', 1),
+            context(3, 'runtime policy', 1),
+            reasoningAssistant(4, 'inspect', 1, 1),
+          ],
+        }), builder),
+        running: true,
+      })
+    })
     expect(renderedFlowKinds(view.container)).toEqual([
       'system-prompt', 'user', 'turn-process', 'context', 'assistant-step',
     ])
     expect(view.container.querySelector('[data-chat-flow-kind="system-prompt"]')).toBe(promptRow)
     expect(promptRow.getAttribute('hidden')).toBeNull()
 
-    act(() => { h.set({ chat: completed, running: false }) })
+    act(() => {
+      h.set({
+        chat: withSystemPrompt(chatSnapshotFixture({
+          nodes: [
+            userInTurn(2, 'question', 1),
+            context(3, 'runtime policy', 1),
+            reasoningAssistant(4, 'inspect', 1, 1),
+            assistant(6, 'final answer', 1, 2),
+          ],
+          turnEnds: new Map([[1, 7]]),
+        }), builder),
+        running: false,
+      })
+    })
     const toggle = turnProcessControl(view.container)!
     const members = [...view.container.querySelectorAll<HTMLElement>('[data-turn-process-member]')]
     expect(renderedFlowKinds(view.container)).toEqual([
diff --git a/packages/client/ui-renderer/src/client/scoped-slots.tsx b/packages/client/ui-renderer/src/client/scoped-slots.tsx
index 05ae2684d7..3a5ecb8373 100644
--- a/packages/client/ui-renderer/src/client/scoped-slots.tsx
+++ b/packages/client/ui-renderer/src/client/scoped-slots.tsx
@@ -5,7 +5,7 @@
 import { Component, useMemo, useState, useSyncExternalStore, type FC, type ReactNode } from 'react'
 import {
   SlotOwnershipError, StaleAuthorizationError, standardHookPropName,
-  type ChainRenderOpts, type HostObservable, type LocaleFace, type RenderOpts,
+  type ChainRenderOpts, type HostObservable, type KeyedStandardSource, type LocaleFace, type RenderOpts,
   type ScopedStandardSourceBinding, type SessionAreaProps, type SessionProviderComponent, type SlotRenderer,
   type SlotRendererHost, type SlotScope, type SlotScopeAdapter, type StandardSourceBinding,
   type StoredEntry, type Translate,
@@ -109,22 +109,28 @@ function runInject(entry: StoredEntry, binding: StandardSourceBinding | undefine
   const args: unknown[] = []
   if (binding !== undefined) args.push(binding.key)
   if (actions !== undefined) args.push(actions)
-  return bindInjectHooks((inject as (...args: unknown[]) => InjectedProps)(...args))
+  return bindInjectSources((inject as (...args: unknown[]) => InjectedProps)(...args))
 }
 
-/**
- * Normalize one entry-owned inject face on its existing cache axis. Its hooks
- * compartment remains the original Observable-only contract.
- */
-function bindInjectHooks(face: InjectedProps): InjectedProps {
+/** Bind one entry-owned inject face on its existing cache axis. */
+function bindInjectSources(face: InjectedProps): InjectedProps {
   const sources = face['hooks']
-  if (sources === undefined) return face
-  const { hooks: _hooks, ...rest } = face
+  const keyedSources = face['keyedHooks']
+  if (sources === undefined && keyedSources === undefined) return face
+  const { hooks: _hooks, keyedHooks: _keyedHooks, ...rest } = face
   const bound: InjectedProps = rest
-  for (const [name, source] of Object.entries(sources as Record<string, HostObservable<unknown>>)) {
+  for (const [name, source] of Object.entries(
+    (sources ?? {}) as Record<string, HostObservable<unknown>>,
+  )) {
     const hookName = standardHookPropName(name)
     bound[hookName] = observableHook(source)
   }
+  for (const [name, source] of Object.entries(
+    (keyedSources ?? {}) as Record<string, KeyedStandardSource>,
+  )) {
+    const hookName = standardHookPropName(name)
+    bound[hookName] = keyedObservableHook(source)
+  }
   return bound
 }
 
diff --git a/packages/client/ui-renderer/tests/scoped-slots.client.spec.tsx b/packages/client/ui-renderer/tests/scoped-slots.client.spec.tsx
index d4360d1914..1052bc0105 100644
--- a/packages/client/ui-renderer/tests/scoped-slots.client.spec.tsx
+++ b/packages/client/ui-renderer/tests/scoped-slots.client.spec.tsx
@@ -930,6 +930,41 @@ describe('inject: execution point, parameter derivation, cache granularity', ()
     expect(seen.at(-1)!['read']).toBe('hot')
   })
 
+  it('binds the inject keyedHooks compartment without exposing source resolvers', () => {
+    const h = makeHost()
+    h.declare('k.single', SINGLE_ROOT)
+    const badges = new Map([
+      ['first', observable('cold')],
+      ['second', observable('idle')],
+    ])
+    const seen: Record<string, unknown>[] = []
+    h.add('k.single', {
+      component: (props: {
+        useBadge?: (key: string) => string | undefined
+        keyedHooks?: unknown
+        plain?: string
+      }) => {
+        seen.push({
+          keyedHooks: props.keyedHooks,
+          plain: props.plain,
+          read: props.useBadge!('first'),
+        })
+        return null
+      },
+      inject: () => ({
+        plain: 'kept',
+        keyedHooks: { badge: (key: string) => badges.get(key) },
+      }),
+    })
+    mountRoot(h, { 'k.single': SINGLE_ROOT }, renderSlot => renderSlot('k.single', {}))
+
+    expect(seen.at(-1)).toEqual({ keyedHooks: undefined, plain: 'kept', read: 'cold' })
+    act(() => { badges.get('second')!.set('ignored') })
+    expect(seen).toHaveLength(1)
+    act(() => { badges.get('first')!.set('hot') })
+    expect(seen.at(-1)!['read']).toBe('hot')
+  })
+
   it('session inject receives sessionId and caches per (entry x session): switch-back reuses', () => {
     const h = makeHost()
     h.declare('k.session', SINGLE_SESSION)
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 6d63eb64a2..56a8234ce1 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -17,7 +17,7 @@ import type { ReactNode } from 'react'
 import type {
   BoundActions, HandleOf, PropsStore, SnapshotSelectorHook, StoreDecl,
 } from '@deepseek-ai/dsh-client-store'
-import type { HostObservable } from './renderer.ts'
+import type { HostObservable, KeyedStandardSource } from './renderer.ts'
 
 export * from './store.ts'
 export * from './renderer.ts'
@@ -375,6 +375,26 @@ export type SlotComponent<P> = (props: P) => ReactNode
  */
 export type HooksSources = Record<string, HostObservable<unknown>>
 
+/** Registrant keyed-hooks compartment: stable key-to-observable resolvers. */
+export type KeyedHooksSources = Record<string, KeyedStandardSource>
+
+/** Selector Hook over an open family of keyed observable sources. */
+export type KeyedSnapshotSelectorHook<Snapshot> = {
+  /** @param key - source key. @returns the current value, or absence when the source is unavailable. */
+  (key: string): Snapshot | undefined
+  /**
+   * @param key - source key.
+   * @param selector - projection over the current keyed value.
+   * @param equal - optional selected-value equality.
+   * @returns the selected value.
+   */
+  <Selected>(
+    key: string,
+    selector: (value: Snapshot | undefined) => Selected,
+    equal?: (left: Selected, right: Selected) => boolean,
+  ): Selected
+}
+
 /** Framework-owned props visible while a slot-level contextual Hook is bound. */
 export type StandardPropsOf<K extends keyof SlotMap & string> =
   (ScopeOf<K> extends 'session' ? SessionStandardProps
@@ -421,13 +441,26 @@ export type PropsHooks<HS extends HooksSources> = {
   SnapshotSelectorHook<HS[N] extends HostObservable<infer T> ? T : never>
 }
 
+/** Selector-hook share synthesized from an entry inject keyed-hooks compartment. */
+export type PropsKeyedHooks<HS extends KeyedHooksSources> = {
+  [N in keyof HS & string as `use${Capitalize<N>}`]: KeyedSnapshotSelectorHook<
+    HS[N] extends (key: string) => HostObservable<infer T> | undefined ? T : never
+  >
+}
+
 /**
  * The component-side view of an inject face: the reserved `hooks`
  * compartment (when declared) arrives as bound `use<Name>` selector hooks;
  * every other member passes through verbatim.
  */
 export type InjectFace<I extends object> =
-  I extends { hooks: infer HS extends HooksSources } ? Omit<I, 'hooks'> & PropsHooks<HS> : I
+  I extends { hooks: infer HS extends HooksSources }
+    ? I extends { keyedHooks: infer KS extends KeyedHooksSources }
+      ? Omit<I, 'hooks' | 'keyedHooks'> & PropsHooks<HS> & PropsKeyedHooks<KS>
+      : Omit<I, 'hooks'> & PropsHooks<HS>
+    : I extends { keyedHooks: infer KS extends KeyedHooksSources }
+      ? Omit<I, 'keyedHooks'> & PropsKeyedHooks<KS>
+      : I
 
 /**
  * The composed component props intersection: runtime share (SlotMap) +

From 0e90d47d19d8b689ebd62981c37496ae25d44945 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 22:29:46 +0800
Subject: [PATCH 30/37] perf(chat): skip stable node list mapping

---
 .../ui-chat/src/client/chat/ChatView.tsx      | 51 +++++++++++--------
 1 file changed, 29 insertions(+), 22 deletions(-)

diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index bf58d4c0c7..7374af1293 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -1,7 +1,7 @@
 // An enclosing `[data-conversation-scroll]` owns scrolling when present;
 // otherwise this view owns it. Each row subscribes to one stable node key.
 
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ComponentProps } from 'react'
 import type {
   ConversationTimelineSnapshot, RenderMessageImages,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -199,6 +199,16 @@ function TurnStatus({ startTime, t }: {
   )
 }
 
+type ChatNodeListProps = Omit<ComponentProps<typeof ChatNodeSeat>, 'nodeKey'> & {
+  readonly order: readonly string[]
+}
+
+const ChatNodeList = memo(function ChatNodeList({ order, ...seatProps }: ChatNodeListProps) {
+  return order.map(nodeKey => (
+    <ChatNodeSeat key={nodeKey} nodeKey={nodeKey} {...seatProps} />
+  ))
+})
+
 /**
  * The chat view slot entry: pure component over the composed props; each
  * ordered business Node crosses the keyed renderer seat.
@@ -743,27 +753,24 @@ export function ChatView({
               </button>
             </div>
           )}
-          {order.map(nodeKey => (
-            <ChatNodeSeat
-              key={nodeKey}
-              nodeKey={nodeKey}
-              useChatNode={useChatNode}
-              useChatNodeProcess={useChatNodeProcess}
-              historyIncomplete={hasMore}
-              compactTranscript={compactTranscript}
-              useStore={useStore}
-              actions={actions}
-              selectedCallId={selectedCallId}
-              cwd={cwd}
-              openFile={requestOpenFile}
-              inspectCall={inspectCall}
-              forkAt={forkAt}
-              renderMessageImages={renderMessageImages}
-              fileMentions={fileMentions}
-              renderSlot={renderSlot}
-              t={t}
-            />
-          ))}
+          <ChatNodeList
+            order={order}
+            useChatNode={useChatNode}
+            useChatNodeProcess={useChatNodeProcess}
+            historyIncomplete={hasMore}
+            compactTranscript={compactTranscript}
+            useStore={useStore}
+            actions={actions}
+            selectedCallId={selectedCallId}
+            cwd={cwd}
+            openFile={requestOpenFile}
+            inspectCall={inspectCall}
+            forkAt={forkAt}
+            renderMessageImages={renderMessageImages}
+            fileMentions={fileMentions}
+            renderSlot={renderSlot}
+            t={t}
+          />
           {/* No pending placeholders: questions (ui-user-questions) and approvals
               (ApprovalPanel) both take over the composer, so a flow card would
               double-render the same wait. */}

From 9ef0e280007f735e7678c7ca8379aae5ae1c0eb7 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 22:36:05 +0800
Subject: [PATCH 31/37] test(web): await streamed text before snapshot

---
 apps/web/tests/live-interactions.e2e.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/web/tests/live-interactions.e2e.ts b/apps/web/tests/live-interactions.e2e.ts
index 53c84ba989..827c4cd02f 100644
--- a/apps/web/tests/live-interactions.e2e.ts
+++ b/apps/web/tests/live-interactions.e2e.ts
@@ -158,6 +158,9 @@ describe('web e2e: live-turn interactions (cancel / error / retry)', () => {
       () => page.getByRole('status').filter({ hasText: 'Deep diving...' }).isVisible(),
       { timeout: 10_000 },
     ).toBe(true)
+    await page.locator('[data-streaming="true"]')
+      .getByText('partial', { exact: true })
+      .waitFor({ timeout: 30_000 })
     const loadingSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold!.workspaceCwd)
     await compareOrRefreshGolden(LOADING_EXPECTED, loadingSnapshot, MODE)
 

From e427d5746ebc9166136e231598115e1333a7503f Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 22:37:58 +0800
Subject: [PATCH 32/37] fix: ci

---
 .../src/client/api-catalog.ts                  | 18 +++++++++++++++++-
 .../src/client/slot-catalog.ts                 | 12 ++++++------
 2 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
index 00c7b4a4b2..0fc5aded9a 100644
--- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
@@ -551,7 +551,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InjectFace',
-    declaration: 'export type InjectFace<I extends object> = I extends {\n    hooks: infer HS extends HooksSources;\n} ? Omit<I, \'hooks\'> & PropsHooks<HS> : I;',
+    declaration: 'export type InjectFace<I extends object> = I extends {\n    hooks: infer HS extends HooksSources;\n} ? I extends {\n    keyedHooks: infer KS extends KeyedHooksSources;\n} ? Omit<I, \'hooks\' | \'keyedHooks\'> & PropsHooks<HS> & PropsKeyedHooks<KS> : Omit<I, \'hooks\'> & PropsHooks<HS> : I extends {\n    keyedHooks: infer KS extends KeyedHooksSources;\n} ? Omit<I, \'keyedHooks\'> & PropsKeyedHooks<KS> : I;',
   },
   {
     name: 'InjectParams',
@@ -561,6 +561,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ISession',
     declaration: 'export interface ISession {\n    readonly sessionId: SessionId;\n    readonly projections: ProjectionsFace;\n    beginSubmission(input: BeginSubmissionInput): SubmissionHandle;\n    prompt(content: PromptContentPart[], mode: \'queue\' | \'steer\', signal?: AbortSignal, requestId?: SessionRequestId): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    readAttachment(attachmentId: AttachmentIdType): Promise<RemoteResult<{\n        attachment: ImageAttachmentRef;\n        data: Uint8Array;\n    }>>;\n    updateQueue(itemId: MessageId, action: QueueAction): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    cancel(): Promise<RemoteResult<{\n        accepted: true;\n    }>>;\n    rename(title: string): Promise<RemoteResult<{\n        title: string;\n        seq: SessionSeq;\n    }>>;\n    loadOlder(): Promise<void>;\n    loadThrough(seq: SessionSeq): Promise<void>;\n    command(line: string): Promise<RemoteResult<{\n        matched: boolean;\n    }>>;\n}',
   },
+  {
+    name: 'KeyedHooksSources',
+    declaration: 'export type KeyedHooksSources = Record<string, KeyedStandardSource>;',
+  },
+  {
+    name: 'KeyedSnapshotSelectorHook',
+    declaration: 'export type KeyedSnapshotSelectorHook<Snapshot> = {\n    (key: string): Snapshot | undefined;\n    <Selected>(key: string, selector: (value: Snapshot | undefined) => Selected, equal?: (left: Selected, right: Selected) => boolean): Selected;\n};',
+  },
+  {
+    name: 'KeyedStandardSource',
+    declaration: 'export type KeyedStandardSource = (key: string) => HostObservable<unknown> | undefined;',
+  },
   {
     name: 'KeyPropsOf',
     declaration: 'export type KeyPropsOf<K extends keyof SlotMap & string, EntryKey extends EntryKeyOf<K>> = SlotMap[K] extends {\n    kind: \'keyed\';\n    keyProps: infer P extends object;\n} ? EntryKey extends keyof P ? P[EntryKey] extends object ? P[EntryKey] : never : never : object;',
@@ -645,6 +657,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'PropsHooks',
     declaration: 'export type PropsHooks<HS extends HooksSources> = {\n    [N in keyof HS & string as `use${Capitalize<N>}`]: SnapshotSelectorHook<HS[N] extends HostObservable<infer T> ? T : never>;\n};',
   },
+  {
+    name: 'PropsKeyedHooks',
+    declaration: 'export type PropsKeyedHooks<HS extends KeyedHooksSources> = {\n    [N in keyof HS & string as `use${Capitalize<N>}`]: KeyedSnapshotSelectorHook<HS[N] extends (key: string) => HostObservable<infer T> | undefined ? T : never>;\n};',
+  },
   {
     name: 'PropsLocale',
     declaration: 'export type PropsLocale<N> = N extends keyof LocaleNamespaceMap & string ? {\n    t: TranslateNS<N>;\n} : object;',
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index 2d341e1897..b339379ec0 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -204,7 +204,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.assistant-actions\', () => ctx.slots.register(\n      { name: \'conversation.chat.assistant-actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:206',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:221',
   },
   {
     key: 'conversation.chat.commandview',
@@ -249,7 +249,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.commandview\', () => ctx.slots.register(\n      { name: \'conversation.chat.commandview\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:194',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:209',
   },
   {
     key: 'conversation.chat.node',
@@ -313,7 +313,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.node\', () => ctx.slots.register(\n      { name: \'conversation.chat.node\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:175',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:190',
   },
   {
     key: 'conversation.chat.turnTail',
@@ -358,7 +358,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.turnTail\', () => ctx.slots.register(\n      { name: \'conversation.chat.turnTail\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:200',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:215',
   },
   {
     key: 'conversation.composer',
@@ -532,7 +532,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.details.tool\', () => ctx.slots.register(\n      { name: \'conversation.details.tool\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:212',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:227',
   },
   {
     key: 'conversation.hero.agentPreset',
@@ -1010,7 +1010,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.message.images\', () => ctx.slots.register(\n      { name: \'conversation.message.images\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:188',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:203',
   },
   {
     key: 'conversation.session',

From 0cdcc9c3c5b6d947b67b3364e1c5d8b8f3a8342a Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Tue, 1 Sep 2026 22:44:58 +0800
Subject: [PATCH 33/37] feat(presets): omit workflow from PTC mode

---
 ...26-09-01-ptc-omits-workflow-tool.i18n.yaml |  6 +++
 .../2026-09-01-ptc-omits-workflow-tool.md     | 29 +++++++++++++
 .../2026-09-01-ptc-omits-workflow-tool.zh.md  | 29 +++++++++++++
 .../created.expected.md                       |  2 +-
 .../damaged.expected.md                       |  2 +-
 .../section.expected.md                       |  2 +-
 .../agent-preset-selection/menu.expected.md   |  2 +-
 apps/web/tests/ptc-round.e2e.ts               |  2 +-
 apps/web/tests/shipped-composition.e2e.ts     | 22 +++++++++-
 .../ui-agent-preset/src/client/locales.ts     |  4 +-
 .../presets/ptc/agent.cordis.yml              | 11 +++--
 .../agent-presets/presets/ptc/preset.yml      |  2 +-
 .../agent-presets/tests/shipped-root.spec.ts  | 43 +++++++++++++++++--
 snapshots/web/ptc-round/session.jsonl         |  2 +-
 .../web/ptc-round/system-prompt.expected.md   | 34 ---------------
 snapshots/web/ptc-round/ui.expected.md        |  2 +-
 16 files changed, 141 insertions(+), 53 deletions(-)
 create mode 100644 .agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.i18n.yaml
 create mode 100644 .agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.md
 create mode 100644 .agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.zh.md

diff --git a/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.i18n.yaml b/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.i18n.yaml
new file mode 100644
index 0000000000..a7fa5b5186
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.md
+2026-09-01-ptc-omits-workflow-tool.md: 7453e06187690fe7fa1eec157ffad8b474c95cf8
+2026-09-01-ptc-omits-workflow-tool.zh.md: 71f64c11048d85c562432cdd51b3b717966fea29
diff --git a/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.md b/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.md
new file mode 100644
index 0000000000..7453e06187
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.md
@@ -0,0 +1,29 @@
+# Agent Note: PTC preset omits the general workflow tool
+
+Status: implemented
+
+English | [中文](2026-09-01-ptc-omits-workflow-tool.zh.md)
+
+## Problem
+
+The shipped Web `ptc` preset exposed the general `workflow` tool through its generated SDK. PTC mode already makes `run_code` the model-authored composition interface, so `workflow` added a second orchestration language with different execution semantics. The preset description also claimed complete parity with Standard mode and could not state this intentional difference.
+
+## Decision
+
+The shipped Web `ptc` preset disables its `tool-workflow` row. Its generated PTC mode SDK therefore omits the `workflow` binding, while the model-facing wire contract remains the single `run_code` tool.
+
+The preset retains `workflow-worker-thread` in its isolated workflow realm because `tool-ralph` consumes the same engine. `ralph` remains available through the PTC mode SDK. The Standard and Creator presets continue to expose `workflow`, and a user-authored preset may mount the tool explicitly.
+
+The workflow package and its durable Session event types remain installed. Existing workflow records continue to render; this default composition change only prevents new top-level workflow calls from agents using the shipped `ptc` preset.
+
+## Alternatives considered
+
+**Disable the complete workflow realm in PTC mode.** Rejected because that also removes the provider required by `ralph`, even though Ralph's fixed fresh-agent loop is not a second model-authored workflow language.
+
+**Hide `workflow` only in the generated SDK.** Rejected because presentation-only filtering would leave executable tool lookup and the declared preset composition out of agreement. Disabling the consumer row removes the binding from registration, lookup, and presentation together.
+
+**Keep `workflow` until `run_code` has feature parity.** Rejected because the shipped PTC default is intended to make `run_code` its composition interface. Users who require declarative workflow semantics can select Standard mode or an explicit custom preset while capability gaps are evaluated independently.
+
+## Consequences
+
+The PTC picker description states the exception instead of promising full Standard parity. A real Web Loader composition test pins the `run_code` wire catalog, the absent `workflow` SDK binding, and the retained `ralph` binding. The keyless recorded Web PTC session owns the assembled prompt evidence, while preset tests pin that Standard and Creator remain unchanged.
diff --git a/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.zh.md b/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.zh.md
new file mode 100644
index 0000000000..71f64c1104
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-01-ptc-omits-workflow-tool.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: PTC preset 不提供通用 workflow 工具
+
+Status: implemented
+
+[English](2026-09-01-ptc-omits-workflow-tool.md) | 中文
+
+## 问题
+
+Web 端随附的 `ptc` preset 会通过生成的 SDK 提供通用 `workflow` 工具。PTC mode 已经把 `run_code` 作为模型编写的组合接口，因此 `workflow` 又增加了一套执行语义不同的编排语言。preset 描述还声称与标准模式能力完全相同，无法说明这个有意的差异。
+
+## 决策
+
+Web 端随附的 `ptc` preset 禁用自身的 `tool-workflow` 配置项。因此，它生成的 PTC mode SDK 不包含 `workflow` 绑定，模型可见的协议约定仍然只有一个 `run_code` 工具。
+
+preset 在隔离的 workflow realm 中保留 `workflow-worker-thread`，因为 `tool-ralph` 使用同一个引擎。PTC mode SDK 继续提供 `ralph`。标准模式与创造模式继续提供 `workflow`，用户自定义 preset 也可以显式挂载该工具。
+
+workflow 包及其持久 Session 事件类型仍然随产品安装。现有 workflow 记录继续正常渲染；这次默认组合变更只会阻止使用随附 `ptc` preset 的 agent 发起新的顶层 workflow 调用。
+
+## 曾考虑的替代方案
+
+**在 PTC mode 中禁用整个 workflow realm。** 不予采用，因为这也会移除 `ralph` 所需的 provider，而 Ralph 固定的全新 agent 循环不是第二套由模型编写的 workflow 语言。
+
+**只在生成的 SDK 中隐藏 `workflow`。** 不予采用，因为只修改呈现会导致可执行工具查找与 preset 声明的组合不一致。禁用 consumer 配置项会同时从注册、查找与呈现中移除该绑定。
+
+**等到 `run_code` 功能完全对等后再移除 `workflow`。** 不予采用，因为随附的 PTC 默认模式就是要以 `run_code` 作为组合接口。在独立评估能力缺口期间，需要声明式 workflow 语义的用户可以选择标准模式或显式自定义 preset。
+
+## 后果
+
+PTC 选择器描述会说明这一例外，不再承诺与标准模式完全对等。真实 Web Loader 组合测试固定 `run_code` 协议工具清单、缺失的 `workflow` SDK 绑定和保留的 `ralph` 绑定。无密钥的 Web PTC 录制会话负责组装提示词证据，preset 测试则固定标准模式与创造模式保持不变。
diff --git a/apps/web/tests/expected/agent-preset-authoring/created.expected.md b/apps/web/tests/expected/agent-preset-authoring/created.expected.md
index 8827af14ad..37dc43d9a6 100644
--- a/apps/web/tests/expected/agent-preset-authoring/created.expected.md
+++ b/apps/web/tests/expected/agent-preset-authoring/created.expected.md
@@ -33,7 +33,7 @@
         - text: 复制
     - listitem:
       - 'button "设为默认: PTC 模式"':
-        - text: PTC 模式 内置 具备标准模式的全部能力，并通过 PTC 模式 SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。
+        - text: PTC 模式 内置 功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。
         - code: ptc
       - 'button "查看: PTC 模式"':
         - img
diff --git a/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md b/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md
index ed0ec29cc9..7f8537f392 100644
--- a/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md
+++ b/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md
@@ -33,7 +33,7 @@
         - text: 复制
     - listitem:
       - 'button "设为默认: PTC 模式"':
-        - text: PTC 模式 内置 具备标准模式的全部能力，并通过 PTC 模式 SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。
+        - text: PTC 模式 内置 功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。
         - code: ptc
       - 'button "查看: PTC 模式"':
         - img
diff --git a/apps/web/tests/expected/agent-preset-authoring/section.expected.md b/apps/web/tests/expected/agent-preset-authoring/section.expected.md
index ec0e49aece..e6c83143d7 100644
--- a/apps/web/tests/expected/agent-preset-authoring/section.expected.md
+++ b/apps/web/tests/expected/agent-preset-authoring/section.expected.md
@@ -33,7 +33,7 @@
         - text: 复制
     - listitem:
       - 'button "设为默认: PTC 模式"':
-        - text: PTC 模式 内置 具备标准模式的全部能力，并通过 PTC 模式 SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。
+        - text: PTC 模式 内置 功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。
         - code: ptc
       - 'button "查看: PTC 模式"':
         - img
diff --git a/apps/web/tests/expected/agent-preset-selection/menu.expected.md b/apps/web/tests/expected/agent-preset-selection/menu.expected.md
index d0a80be760..c89bfd50a5 100644
--- a/apps/web/tests/expected/agent-preset-selection/menu.expected.md
+++ b/apps/web/tests/expected/agent-preset-selection/menu.expected.md
@@ -2,7 +2,7 @@
   - menuitem "Standard mode Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows.":
     - text: Standard mode Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows.
     - img
-  - menuitem "PTC mode All Standard mode capabilities, with tools exposed through the PTC mode SDK so the model can combine multi-step operations in one TypeScript program."
+  - menuitem "PTC mode Full coding agent without the workflow tool; other tools are exposed through the PTC mode SDK so the model can combine multi-step operations in one TypeScript program."
   - menuitem "Minimal mode Two-tool coding agent with persistent bash and str_replace_editor."
   - menuitem "Creator mode Built for creating custom agent presets, with all Standard mode capabilities plus runtime inspection, plugin experiments, and preset-authoring guidance."
   - menuitem "Refusing mode Resolves, then refuses to start."
diff --git a/apps/web/tests/ptc-round.e2e.ts b/apps/web/tests/ptc-round.e2e.ts
index 1098f6c203..65ba4723fe 100644
--- a/apps/web/tests/ptc-round.e2e.ts
+++ b/apps/web/tests/ptc-round.e2e.ts
@@ -30,7 +30,7 @@ describe('web e2e: PTC mode round renders nested sub-calls', () => {
 
   beforeAll(async () => {
     scaffold = await launchWebScaffold({
-      toolsMode: 'ptc',
+      agentPresets: { roots: [], default: 'ptc' },
       compareReplaySession: true,
       ...(MODE === 'record' ? {} : { replayFixture: FIXTURE, paceMs: 15 }),
     })
diff --git a/apps/web/tests/shipped-composition.e2e.ts b/apps/web/tests/shipped-composition.e2e.ts
index ac882e2cd6..61acc027fd 100644
--- a/apps/web/tests/shipped-composition.e2e.ts
+++ b/apps/web/tests/shipped-composition.e2e.ts
@@ -10,8 +10,8 @@ import { afterEach, expect, it } from 'vitest'
 import { ToolCallId } from '@deepseek-ai/dsh-llm'
 import { canonicalPath, writableRoots } from '@deepseek-ai/dsh-sandbox'
 import { SessionId } from '@deepseek-ai/dsh-session'
-// Empty type imports carry the tools/sandboxPolicy/approval Context merges.
-import type {} from '@deepseek-ai/dsh-tools'
+// These imports carry the tools/sandboxPolicy/approval Context merges.
+import { RUN_CODE_NAME } from '@deepseek-ai/dsh-tools'
 import type {} from '@deepseek-ai/dsh-sandbox-policy'
 import type {} from '@deepseek-ai/dsh-user-approval'
 import type {} from '@deepseek-ai/dsh-permission-presets'
@@ -191,6 +191,24 @@ it('assembles the shipped Web transport, catalog, guidance, and defaults', async
   }
 }, 120_000)
 
+it('ships PTC with run_code but without the general workflow SDK binding', async () => {
+  scaffold = await launchWebScaffold({ deepSeekMissingCredential: true })
+  const ctx = scaffold.ctx
+  const handle = await ctx.agents.create({
+    sessionId: SessionId('shipped-ptc-composition'),
+    setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'ptc').then(() => undefined),
+  })
+  try {
+    const assembly = await ctx.systemPrompt.assemble({ scope: handle.agent })
+    expect(assembly.tools.map(tool => tool.name)).toEqual([RUN_CODE_NAME])
+    const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text ?? ''
+    expect(sdk).toContain('  ralph: {')
+    expect(sdk).not.toContain('  workflow: {')
+  } finally {
+    await handle.dispose()
+  }
+}, 120_000)
+
 it('lets a preset producer reach the background-job registry', async () => {
   scaffold = await launchWebScaffold()
   const ctx = scaffold.ctx
diff --git a/packages/client/ui-agent-preset/src/client/locales.ts b/packages/client/ui-agent-preset/src/client/locales.ts
index dff269686d..a4dbdd949b 100644
--- a/packages/client/ui-agent-preset/src/client/locales.ts
+++ b/packages/client/ui-agent-preset/src/client/locales.ts
@@ -36,7 +36,7 @@ export const en: Record<AgentPresetSettingsKey, string> = {
     'Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows.',
   presetPtcName: 'PTC mode',
   presetPtcDescription:
-    'All Standard mode capabilities, with tools exposed through the PTC mode SDK so the model can combine multi-step operations in one TypeScript program.',
+    'Full coding agent without the workflow tool; other tools are exposed through the PTC mode SDK so the model can combine multi-step operations in one TypeScript program.',
   presetMinimalName: 'Minimal mode',
   presetMinimalDescription:
     'Two-tool coding agent with persistent bash and str_replace_editor.',
@@ -96,7 +96,7 @@ export const zh: Record<AgentPresetSettingsKey, string> = {
   presetStandardName: '标准模式',
   presetStandardDescription: '功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。',
   presetPtcName: 'PTC 模式',
-  presetPtcDescription: '具备标准模式的全部能力，并通过 PTC 模式 SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。',
+  presetPtcDescription: '功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。',
   presetMinimalName: '极简模式',
   presetMinimalDescription: '仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。',
   presetCordisName: '创造模式',
diff --git a/packages/preset/agent-presets/presets/ptc/agent.cordis.yml b/packages/preset/agent-presets/presets/ptc/agent.cordis.yml
index 06a0a56664..a3771e6b71 100644
--- a/packages/preset/agent-presets/presets/ptc/agent.cordis.yml
+++ b/packages/preset/agent-presets/presets/ptc/agent.cordis.yml
@@ -1,9 +1,9 @@
 # The `ptc` agent preset: the standard coding agent, presented as PTC mode.
 #
-# Everything in `standard` is here unchanged. What is added is the `tool-presentation`
-# row: instead of one tool call per action, the model writes a TypeScript
-# program against a generated SDK and `run_code` executes it, so a sequence
-# that would be five round trips becomes one.
+# Most of `standard` is here unchanged. The deliberate exception is the
+# general-purpose `workflow` tool: PTC mode uses `run_code` as its model-authored
+# composition surface. The `tool-presentation` row turns the remaining registry
+# into a generated SDK, so a sequence that would be five round trips becomes one.
 #
 # The registry itself stays on the host plane — the agent loop's scheduler and
 # the API proxy's presenters are its consumers — so what this preset owns is
@@ -232,6 +232,9 @@
 
     - id: tool-workflow
       name: '@deepseek-ai/dsh-tool-workflow'
+      # Keep the engine above for `ralph`, but do not publish a second
+      # model-authored orchestration surface beside `run_code` in PTC mode.
+      disabled: true
 
     - id: tool-ralph
       name: '@deepseek-ai/dsh-tool-ralph'
diff --git a/packages/preset/agent-presets/presets/ptc/preset.yml b/packages/preset/agent-presets/presets/ptc/preset.yml
index e0351de114..4cd0bed863 100644
--- a/packages/preset/agent-presets/presets/ptc/preset.yml
+++ b/packages/preset/agent-presets/presets/ptc/preset.yml
@@ -1,3 +1,3 @@
 name: PTC 模式
-description: 具备标准模式的全部能力，并通过 PTC 模式 SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。
+description: 功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。
 order: 2
diff --git a/packages/preset/agent-presets/tests/shipped-root.spec.ts b/packages/preset/agent-presets/tests/shipped-root.spec.ts
index 7e74f421cd..323c56ee12 100644
--- a/packages/preset/agent-presets/tests/shipped-root.spec.ts
+++ b/packages/preset/agent-presets/tests/shipped-root.spec.ts
@@ -53,6 +53,34 @@ async function roster(config: Partial<Config> = {}): Promise<Context> {
   return ctx
 }
 
+interface ShippedEntry {
+  id?: unknown
+  disabled?: unknown
+  config?: unknown
+}
+
+/** Find one entry through the shipped composition's nested groups. */
+function findEntry(entries: unknown[], id: string): ShippedEntry | undefined {
+  for (const entry of entries) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const candidate = entry as ShippedEntry
+    if (candidate.id === id) return candidate
+    if (Array.isArray(candidate.config)) {
+      const nested = findEntry(candidate.config, id)
+      if (nested !== undefined) return nested
+    }
+  }
+  return undefined
+}
+
+/** Read and validate one shipped preset's Cordis entry list. */
+async function shippedEntries(id: string): Promise<unknown[]> {
+  const source = await readFile(join(SHIPPED_PRESET_ROOT, id, 'agent.cordis.yml'), 'utf8')
+  const entries: unknown = yaml.load(source, { schema: entryListSchema })
+  if (!Array.isArray(entries)) throw new TypeError(`${id} preset must contain a Cordis entry list`)
+  return entries.map((entry: unknown) => entry)
+}
+
 describe('the shipped preset root', () => {
   it('supplies the built-in presets from a bare roster, healthy and system-trusted', async () => {
     const ctx = await roster({ includeUserRoot: false })
@@ -99,9 +127,7 @@ describe('the shipped preset root', () => {
 
   it('enables web_fetch in each tool-bearing Web app preset', async () => {
     for (const id of ['cordis', 'ptc', 'standard']) {
-      const source = await readFile(join(SHIPPED_PRESET_ROOT, id, 'agent.cordis.yml'), 'utf8')
-      const entries: unknown = yaml.load(source, { schema: entryListSchema })
-      if (!Array.isArray(entries)) throw new TypeError(`${id} preset must contain a Cordis entry list`)
+      const entries = await shippedEntries(id)
       const toolWeb: unknown = entries.find((entry: unknown) =>
         typeof entry === 'object' && entry !== null && 'id' in entry && entry.id === 'tool-web')
       if (typeof toolWeb !== 'object' || toolWeb === null || !('config' in toolWeb)
@@ -111,4 +137,15 @@ describe('the shipped preset root', () => {
       expect(toolWeb.config.fetch, id).toBe(true)
     }
   })
+
+  it('omits the general workflow tool only from PTC while retaining Ralph infrastructure', async () => {
+    const ptc = await shippedEntries('ptc')
+    expect(findEntry(ptc, 'tool-workflow')?.disabled).toBe(true)
+    expect(findEntry(ptc, 'workflow-worker-thread')?.disabled).not.toBe(true)
+    expect(findEntry(ptc, 'tool-ralph')?.disabled).not.toBe(true)
+
+    for (const id of ['standard', 'cordis']) {
+      expect(findEntry(await shippedEntries(id), 'tool-workflow')?.disabled, id).not.toBe(true)
+    }
+  })
 })
diff --git a/snapshots/web/ptc-round/session.jsonl b/snapshots/web/ptc-round/session.jsonl
index f8b3b161a3..918a5ecc27 100644
--- a/snapshots/web/ptc-round/session.jsonl
+++ b/snapshots/web/ptc-round/session.jsonl
@@ -1,4 +1,4 @@
-{"type":"session","version":0,"id":"{{session:1}}","createdAt":1787736414061,"cwd":"{{cwd}}","agentPreset":"standard"}
+{"type":"session","version":0,"id":"{{session:1}}","createdAt":1787736414061,"cwd":"{{cwd}}","agentPreset":"ptc"}
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
diff --git a/snapshots/web/ptc-round/system-prompt.expected.md b/snapshots/web/ptc-round/system-prompt.expected.md
index 21bb420c3b..fc9cac9176 100644
--- a/snapshots/web/ptc-round/system-prompt.expected.md
+++ b/snapshots/web/ptc-round/system-prompt.expected.md
@@ -30,8 +30,6 @@ Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL (for ex
 
 Use goal tools for one long-running completion objective in the current session. create_goal may infer goal intent from a direct human request in any language; do not create a goal for routine single-turn work. Call get_goal before update_goal and copy its exact goal_id and revision. After session resume or fork, an active goal is disarmed: when a human asks to continue or resume in any wording or language, use update_goal action resume to rearm it. Mark complete only when the objective is actually achieved. Mark blocked only after the same blocking condition persists for at least 3 consecutive goal rounds, and report that concrete condition in blocked_reason; difficulty, uncertainty, or useful remaining work is not blocked.
 
-Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.
-
 Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.
 
 Use subagent in the background by default. Start independent delegations together in one assistant message and continue useful work while they run. Set `run_in_background: false` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message.
@@ -254,33 +252,6 @@ interface ToolArgsMap {
     /** Required search queries; accepts 1–4 items and merges their results. */
     queries: string[];
   } & Record<string, JsonValue>;
-  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */
-  workflow: {
-    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */
-    script: string;
-    /** The workflow identity block (plain JSON — never code). */
-    meta: {
-      /** Short kebab-case workflow name. */
-      name: string;
-      /** One-line description of what the workflow does. */
-      description: string;
-      /** Optional guidance on when this workflow applies. */
-      whenToUse?: string;
-      /** Optional phase declarations matched by phase() calls. */
-      phases?: ({
-        /** The phase title phase() calls match by exact string. */
-        title: string;
-        /** Optional one-line description of the phase. */
-        detail?: string;
-        /** Optional provider override this phase is expected to use. */
-        provider?: string;
-        /** Optional model override this phase is expected to use. */
-        model?: string;
-      } & Record<string, JsonValue>)[];
-    } & Record<string, JsonValue>;
-    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}). */
-    args?: Record<string, JsonValue>;
-  } & Record<string, JsonValue>;
   /** Create or fully replace a UTF-8 text file. */
   write: {
     /** Path to write, resolved by the filesystem backend. */
@@ -551,11 +522,6 @@ interface ToolOutputMap {
     }[];
     truncated: boolean;
   };
-  workflow: {
-    runId: string;
-    agentsStarted: number;
-    result: JsonValue;
-  };
   write: {
     path: string;
     operation: "create" | "update";
diff --git a/snapshots/web/ptc-round/ui.expected.md b/snapshots/web/ptc-round/ui.expected.md
index 6e590dabd7..80b8866505 100644
--- a/snapshots/web/ptc-round/ui.expected.md
+++ b/snapshots/web/ptc-round/ui.expected.md
@@ -2,7 +2,7 @@
   - navigation "Session hierarchy":
     - 'button "Using ONE run_code program: run" [disabled]'
   - img
-  - text: Standard mode
+  - text: PTC mode
   - button "Session log":
     - text: Session log
     - img

From 4e4733c50bc2462e7cd4f076dd0adcbe1859474a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 22:55:17 +0800
Subject: [PATCH 34/37] test(web): await turn-tail stream publication

---
 apps/web/tests/turn-tail-actions.e2e.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/web/tests/turn-tail-actions.e2e.ts b/apps/web/tests/turn-tail-actions.e2e.ts
index 5b5520f93d..d51d6c2528 100644
--- a/apps/web/tests/turn-tail-actions.e2e.ts
+++ b/apps/web/tests/turn-tail-actions.e2e.ts
@@ -139,6 +139,9 @@ describe('web e2e: assistant IconActions wait for the turn to end', () => {
       () => page.getByRole('status').filter({ hasText: 'Deep diving...' }).isVisible(),
       { timeout: 10_000 },
     ).toBe(true)
+    await page.locator('[data-streaming="true"]')
+      .getByText('partial', { exact: true })
+      .waitFor({ timeout: 10_000 })
     // Only the user bubble owns a footer (clock + copy; user bubbles carry no
     // branch action): the narration is not the answer yet.
     const copyButtons = page.getByRole('button', { name: 'Copy' })

From e32437d18b4aa2c9c4feda530b9cdda49dcb75f6 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 1 Sep 2026 23:06:52 +0800
Subject: [PATCH 35/37] perf(chat): throttle scroll geometry sampling

---
 .../ui-chat/src/client/chat/ChatView.tsx      | 29 ++++++++++++++++---
 .../ui-chat/tests/chat-view.client.spec.tsx   |  4 +++
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index 7374af1293..403eecd96f 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -17,6 +17,7 @@ import { formatRunDuration } from './message-chrome.ts'
 import css from './ChatView.module.css'
 
 const FOLLOW_THRESHOLD = 24
+const SCROLL_SAMPLE_INTERVAL_MS = 500
 
 /** Active column host when present; otherwise the view-local scroller. */
 function scrollerOf(from: HTMLElement): HTMLElement {
@@ -307,6 +308,8 @@ export function ChatView({
   // restores it and normalizes a floor-clamped position back to following.
   const [atBottom, setAtBottom] = useState(() => chatScroll.read() === null)
   const atBottomRef = useRef(atBottom)
+  const scrollSamplePendingRef = useRef(false)
+  const [, setScrollSampleTick] = useState(0)
   const [activeTurn, setActiveTurn] = useState<number | null>(
     () => turnNavigationItems.at(-1)?.turn ?? null,
   )
@@ -343,6 +346,7 @@ export function ChatView({
   const followSig = `${openState}:${firstSeq}:${lastKey}:${order.length}:${running ? 1 : 0}:${lastSteeringId ?? ''}:${lastSubmissionId ?? ''}`
 
   const syncActiveTurn = useCallback((): void => {
+    if (scrollSamplePendingRef.current) return
     const local = listRef.current
     const first = turnNavigationItems[0]
     if (local === null || first === undefined) {
@@ -461,6 +465,7 @@ export function ChatView({
   }
 
   useLayoutEffect(() => {
+    if (scrollSamplePendingRef.current) return
     const local = listRef.current
     /* v8 ignore next -- ref-null guard: React attaches the ref before layout effects run. */
     if (local === null) return
@@ -574,18 +579,33 @@ export function ChatView({
     scheduleActiveTurn()
   }
 
-  // Bind the scroll listener on the resolved scrollport once per mount;
-  // reader-input attribution rides the observed-top ledger, not per-device
-  // input listeners.
+  // Raw scroll events only schedule work. Geometry is sampled at most once
+  // per interval, with scrollend providing the final sample for a short burst.
   useEffect(() => {
     const local = listRef.current
     /* v8 ignore next -- ref-null guard: effect runs after the list node commits. */
     if (local === null) return
     const el = scrollerOf(local)
-    const onScroll = (): void => { onScrollRef.current() }
+    let sampleTimer: number | undefined
+    const sample = (): void => {
+      if (!scrollSamplePendingRef.current) return
+      scrollSamplePendingRef.current = false
+      if (sampleTimer !== undefined) window.clearTimeout(sampleTimer)
+      sampleTimer = undefined
+      onScrollRef.current()
+      setScrollSampleTick(tick => tick + 1)
+    }
+    const onScroll = (): void => {
+      scrollSamplePendingRef.current = true
+      sampleTimer ??= window.setTimeout(sample, SCROLL_SAMPLE_INTERVAL_MS)
+    }
     el.addEventListener('scroll', onScroll, { passive: true })
+    el.addEventListener('scrollend', sample, { passive: true })
     return () => {
       el.removeEventListener('scroll', onScroll)
+      el.removeEventListener('scrollend', sample)
+      if (sampleTimer !== undefined) window.clearTimeout(sampleTimer)
+      scrollSamplePendingRef.current = false
     }
   }, [])
 
@@ -593,6 +613,7 @@ export function ChatView({
   // initializer a function initial value would need never exists.
   const followRef = useRef<(() => void) | null>(null)
   followRef.current = () => {
+    if (scrollSamplePendingRef.current) return
     const local = listRef.current
     if (local !== null && atBottomRef.current) {
       const el = scrollerOf(local)
diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
index 83d0dc6b9a..9e0818f37c 100644
--- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
@@ -439,6 +439,7 @@ function makeHarness(
 function readerScroll(element: HTMLElement, top: number): void {
   element.scrollTop = top
   fireEvent.scroll(element)
+  fireEvent(element, new Event('scrollend'))
 }
 
 function turnProcessControl(container: HTMLElement): HTMLButtonElement | null {
@@ -2315,6 +2316,7 @@ describe('ChatView', () => {
     // lands exactly on the ledger's floor min, so it is not reader input.
     metrics.setLayout(800, 700)
     fireEvent.scroll(scroller)
+    fireEvent(scroller, new Event('scrollend'))
     expect(scroller.scrollTop).toBe(500)
     expect(view.queryByLabelText('回到底部')).toBeNull()
     expect(h.chatScroll.read()).toBeNull()
@@ -2337,6 +2339,7 @@ describe('ChatView', () => {
     // baseline sampled from already-moved raw geometry.
     scroller.scrollTop = 500
     fireEvent.scroll(scroller)
+    fireEvent(scroller, new Event('scrollend'))
     expect(view.getByLabelText('回到底部')).toBeTruthy()
   })
 
@@ -2359,6 +2362,7 @@ describe('ChatView', () => {
     Object.defineProperty(scroller, 'clientHeight', { value: 300, writable: true })
     scroller.scrollTop = 700
     fireEvent.scroll(scroller)
+    fireEvent(scroller, new Event('scrollend'))
     Object.defineProperty(scroller, 'scrollHeight', { value: 1_200, writable: true })
     act(() => { notify?.() })
     expect(scroller.scrollTop).toBe(1_200)

From bec6805d6af1cbb2a61f75c863d10a57371a58b3 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Fri, 28 Aug 2026 12:21:44 +0800
Subject: [PATCH 36/37] refactor(session-persistence)!: handle-based seam with
 a lifecycle-owned write path

The persistence seam is now create/open/stat/list returning per-session
SessionHandles (read/append/flush/close); every log read and write flows
through the owning handle. The seam package exports only the service and
handle contracts, consumer-visible errors, and pure durable-data
validation helpers; each backend owns its complete storage runtime, and
the shared contract suites pin equivalent observable behavior. The
backend routes published sessions' live events by id into the active
write handle; agent-loop only acquires, seeds, and closes the handle.
Resume appends interruptedTurnClosers through its write handle;
session-query owns the revision-keyed cold cache. Legacy-only surfaces
are removed in the same swap: locate/readRaw/supportsRawArtifacts, the
legacy event-shape read migration, zstd torn-frame salvage,
DSH_SESSION_JSONL, and hook transcript_path population; a torn final
zstd frame is discarded whole; the session-list cold blank probe returns
on stat metadata (eventCount derived from the last physical row,
sizeBytes). The WebUI ZIP export serializes the logical log from a read
handle, so both backends export identically.

Refs #3245
---
 ...ed-persistence-write-coordinator.i18n.yaml |    4 +-
 ...18-shared-persistence-write-coordinator.md |    1 +
 ...shared-persistence-write-coordinator.zh.md |    1 +
 .agents/notes/archived/manifest.json          |    3 +
 .../2026-06-14-session-persistence.i18n.yaml  |    4 +-
 .../2026-06-14-session-persistence.md         |   10 +-
 .../2026-06-14-session-persistence.zh.md      |   10 +-
 ...-19-zstandard-jsonl-session-logs.i18n.yaml |    4 +-
 ...2026-07-19-zstandard-jsonl-session-logs.md |    2 +-
 ...6-07-19-zstandard-jsonl-session-logs.zh.md |    2 +-
 ...7-24-project-session-directories.i18n.yaml |    4 +-
 .../2026-07-24-project-session-directories.md |    2 +-
 ...26-07-24-project-session-directories.zh.md |    2 +-
 .../2026-08-05-session-preparation.i18n.yaml  |    4 +-
 .../2026-08-05-session-preparation.md         |   49 +-
 .../2026-08-05-session-preparation.zh.md      |   49 +-
 ...ssion-persistence-write-batching.i18n.yaml |    4 +-
 ...nded-session-persistence-write-batching.md |   20 +-
 ...d-session-persistence-write-batching.zh.md |   20 +-
 ...6-08-10-message-feedback-sidecar.i18n.yaml |    4 +-
 .../2026-08-10-message-feedback-sidecar.md    |    4 +-
 .../2026-08-10-message-feedback-sidecar.zh.md |    4 +-
 ...sion-history-and-event-transport.i18n.yaml |    4 +-
 ...-18-session-history-and-event-transport.md |    2 +-
 ...-session-history-and-event-transport.zh.md |    2 +-
 ...nd-projection-owned-client-state.i18n.yaml |    4 +-
 ...tions-and-projection-owned-client-state.md |    6 +-
 ...ns-and-projection-owned-client-state.zh.md |    6 +-
 ...andle-based-session-persistence.i18n.yaml} |    6 +-
 ...-08-27-handle-based-session-persistence.md |   42 +
 ...-27-handle-based-session-persistence.zh.md |   42 +
 ...gnorable-external-session-events.i18n.yaml |    4 +-
 ...etain-ignorable-external-session-events.md |    2 +-
 ...in-ignorable-external-session-events.zh.md |    2 +-
 ...7-28-load-pre-identity-session-messages.md |   38 -
 ...8-load-pre-identity-session-messages.zh.md |   38 -
 ...resume-selector-batch-projection.i18n.yaml |    4 +-
 ...-07-31-resume-selector-batch-projection.md |    2 +-
 ...-31-resume-selector-batch-projection.zh.md |    2 +-
 ...2026-08-04-load-pre-react-loop-sessions.md |   40 -
 ...6-08-04-load-pre-react-loop-sessions.zh.md |   40 -
 ...-bounded-cold-blank-verification.i18n.yaml |    4 +-
 ...6-08-13-bounded-cold-blank-verification.md |   12 +-
 ...8-13-bounded-cold-blank-verification.zh.md |   12 +-
 ...ession-identity-and-log-location.i18n.yaml |    4 +-
 ...agent-session-identity-and-log-location.md |   46 +-
 ...nt-session-identity-and-log-location.zh.md |   46 +-
 ...ned-subagent-settlement-delivery.i18n.yaml |    4 +-
 ...ager-owned-subagent-settlement-delivery.md |    4 +
 ...r-owned-subagent-settlement-delivery.zh.md |    4 +
 ...026-08-10-web-session-log-export.i18n.yaml |    4 +-
 .../2026-08-10-web-session-log-export.md      |    4 +-
 .../2026-08-10-web-session-log-export.zh.md   |    6 +-
 ...standard-acp-automation-controls.i18n.yaml |    4 +-
 ...-08-22-standard-acp-automation-controls.md |    2 +-
 ...-22-standard-acp-automation-controls.zh.md |    2 +-
 ...ention-discovery-and-row-content.i18n.yaml |    4 +-
 ...eb-at-mention-discovery-and-row-content.md |    2 +-
 ...at-mention-discovery-and-row-content.zh.md |    2 +-
 ...-19-drop-mutable-session-summary.i18n.yaml |    4 +-
 ...2026-06-19-drop-mutable-session-summary.md |    2 +-
 ...6-06-19-drop-mutable-session-summary.zh.md |    2 +-
 ...ce-export-and-pre-release-trims.i18n.yaml} |    6 +-
 ...ersistence-export-and-pre-release-trims.md |   46 +
 ...istence-export-and-pre-release-trims.zh.md |   46 +
 ...0-jsonl-only-session-persistence.i18n.yaml |    4 +-
 ...26-08-30-jsonl-only-session-persistence.md |    2 +-
 ...08-30-jsonl-only-session-persistence.zh.md |    2 +-
 ...7-29-durable-last-activity-index.i18n.yaml |    4 +-
 .../2026-07-29-durable-last-activity-index.md |    6 +-
 ...26-07-29-durable-last-activity-index.zh.md |    6 +-
 ...-07-04-prune-dead-core-spine-api.i18n.yaml |    4 +-
 .../2026-07-04-prune-dead-core-spine-api.md   |    1 -
 ...2026-07-04-prune-dead-core-spine-api.zh.md |    1 -
 ...ld-session-persistence-interface.i18n.yaml |    4 +-
 ...6-20-fold-session-persistence-interface.md |    2 +-
 ...0-fold-session-persistence-interface.zh.md |    2 +-
 .../skills/dsh-find-simplifications/SKILL.md  |    2 +-
 .../headless/tests/coding-task.e2e.ts         |    2 +-
 .../profiles/headless/tests/compaction.e2e.ts |    2 +-
 .../profiles/headless/tests/full-loop.e2e.ts  |    2 +-
 .../tests/profiles/headless/tests/ptc.e2e.ts  |    2 +-
 .../tests/semantic-checkpoint.expected.e2e.ts |   15 +-
 .../session-format-guard.expected.e2e.ts      |   13 +-
 .../tests/subagent-diagnostic.expected.e2e.ts |   17 +-
 .../subagent-inheritance.expected.e2e.ts      |   12 +-
 .../profiles/headless/tests/todo-write.e2e.ts |    2 +-
 .../workspace-context-resume.expected.e2e.ts  |   13 +-
 apps/web/tests/agent-preset-selection.e2e.ts  |   31 +-
 apps/web/tests/cold-blank-session.e2e.ts      |   60 -
 .../cold-blank-session/sidebar.expected.md    |    1 -
 apps/web/tests/message-actions.e2e.ts         |   20 +-
 apps/web/tests/scaffold.ts                    |   57 +-
 apps/web/tests/schedule-after.e2e.ts          |   15 +-
 apps/web/tests/seeded-history.e2e.ts          |    2 +
 apps/web/tests/stats-paged-history.e2e.ts     |    7 +-
 apps/web/tests/subagent-conversation.e2e.ts   |   60 +-
 apps/web/tests/subagent-interrupt-ui.e2e.ts   |   10 +-
 apps/web/tests/subagent-interrupt.e2e.ts      |   10 +-
 apps/web/tests/workspace-management.e2e.ts    |   21 +-
 apps/web/tsconfig.json                        |    1 -
 docs/architecture.i18n.yaml                   |    4 +-
 docs/architecture.md                          |    3 +-
 docs/architecture.zh.md                       |    3 +-
 docs/config-catalog.i18n.yaml                 |    4 +-
 docs/config-catalog.md                        |   32 +-
 docs/config-catalog.zh.md                     |   32 +-
 docs/event-producer-consumer.i18n.yaml        |    4 +-
 docs/event-producer-consumer.md               |   12 +-
 docs/event-producer-consumer.zh.md            |   12 +-
 docs/module-graph.i18n.yaml                   |    4 +-
 docs/module-graph.md                          |   12 +-
 docs/module-graph.zh.md                       |   12 +-
 docs/persistence-catalog.i18n.yaml            |    4 +-
 docs/persistence-catalog.md                   |   26 +-
 docs/persistence-catalog.zh.md                |   26 +-
 docs/subsystems/core.i18n.yaml                |    4 +-
 docs/subsystems/core.md                       |    5 +-
 docs/subsystems/core.zh.md                    |    5 +-
 docs/subsystems/feedback.i18n.yaml            |    4 +-
 docs/subsystems/feedback.md                   |    4 +-
 docs/subsystems/feedback.zh.md                |    4 +-
 docs/subsystems/persistence.i18n.yaml         |    4 +-
 docs/subsystems/persistence.md                |  407 ++-
 docs/subsystems/persistence.zh.md             |  407 ++-
 docs/subsystems/session-projection.i18n.yaml  |    4 +-
 docs/subsystems/session-projection.md         |   10 +-
 docs/subsystems/session-projection.zh.md      |   10 +-
 docs/subsystems/session-query.i18n.yaml       |    4 +-
 docs/subsystems/session-query.md              |    4 +-
 docs/subsystems/session-query.zh.md           |    4 +-
 docs/subsystems/session.i18n.yaml             |    4 +-
 docs/subsystems/session.md                    |   10 +-
 docs/subsystems/session.zh.md                 |   10 +-
 docs/subsystems/subagent.i18n.yaml            |    4 +-
 docs/subsystems/subagent.md                   |    2 +-
 docs/subsystems/subagent.zh.md                |    2 +-
 packages/acp/acp/src/index.ts                 |    9 +-
 packages/acp/acp/tests/bridge.spec.ts         |   45 +-
 .../api/session-controller/README.i18n.yaml   |    4 +-
 packages/api/session-controller/README.md     |    3 +-
 packages/api/session-controller/README.zh.md  |    3 +-
 packages/api/session-controller/src/index.ts  |   22 +-
 packages/api/session-controller/src/list.ts   |   45 +-
 .../tests/agent.host.spec.ts                  |   60 +-
 .../tests/session-cold.host.spec.ts           |  574 ++--
 .../tests/session-projections.host.spec.ts    |   22 +-
 .../tests/session-search.host.spec.ts         |   43 +-
 .../session-controller/tests/test-remote.ts   |  148 +-
 .../tests/transport.host.spec.ts              |    9 +-
 .../tests/compaction-loop-repro.spec.ts       |    6 +-
 .../tests/manual-compaction.spec.ts           |    2 +-
 .../tests/agent-instructions.spec.ts          |    2 +-
 .../time-context/tests/time-context.spec.ts   |    4 +-
 packages/core/agent-loop/README.i18n.yaml     |    4 +-
 packages/core/agent-loop/README.md            |    6 +-
 packages/core/agent-loop/README.zh.md         |    6 +-
 packages/core/agent-loop/src/index.ts         |  222 +-
 .../agent-loop/tests/agent-initiator.spec.ts  |    6 +-
 packages/core/agent-loop/tests/agent.spec.ts  |   18 +-
 packages/core/agent-loop/tests/cancel.spec.ts |   58 +-
 .../tests/config-session-id.spec.ts           |  102 +-
 .../tests/contract-regressions.spec.ts        |   92 +-
 .../agent-loop/tests/coverage-edges.spec.ts   |   40 +-
 .../agent-loop/tests/interception.spec.ts     |   46 +-
 packages/core/agent-loop/tests/loop.spec.ts   |  121 +-
 .../core/agent-loop/tests/properties.spec.ts  |    6 +-
 .../agent-loop/tests/request-cache.e2e.ts     |    2 +-
 .../agent-loop/tests/request-error.spec.ts    |    8 +-
 .../tests/request-reconstruction.spec.ts      |   48 +-
 packages/core/agent-loop/tests/resume.spec.ts |  889 ++++--
 .../agent-loop/tests/scope-lifecycle.spec.ts  |   33 +-
 .../agent-loop/tests/shutdown-drain.spec.ts   |   69 +
 .../core/agent-loop/tests/tool-calls.spec.ts  |   36 +-
 .../core/agent-loop/tests/tool-order.spec.ts  |    4 +-
 packages/core/agent/src/index.ts              |   11 +-
 packages/core/session/src/index.ts            |    5 +-
 packages/core/session/src/types.ts            |    6 +-
 .../experimental/agent-team/src/mailbox.ts    |   10 +-
 .../experimental/agent-team/src/persisted.ts  |   33 +
 .../experimental/agent-team/src/roster.ts     |   11 +-
 .../agent-team/tests/persistence.spec.ts      |   62 +-
 .../agent-team/tests/team.spec.ts             |   49 +-
 .../agent-team/tests/test-session-query.ts    |   46 +
 .../tool-agent-team/tests/tool-team.spec.ts   |    2 +-
 .../extensions/tool-cordis/src/api-catalog.ts |  164 +-
 .../message-feedback/README.i18n.yaml         |    4 +-
 packages/feedback/message-feedback/README.md  |    7 +-
 .../feedback/message-feedback/README.zh.md    |    7 +-
 .../feedback/message-feedback/src/index.ts    |   72 +-
 .../message-feedback/tests/helpers.ts         |  147 +-
 .../tests/loader-composition.spec.ts          |   13 +-
 .../tests/message-feedback.spec.ts            |   59 +-
 packages/fs/tool-fs/tests/fs-tools.e2e.ts     |    2 +-
 .../tests/goal-round-driver.spec.ts           |    4 +-
 .../tests/repeat-tool-reminder.spec.ts        |   36 +-
 .../hooks/hooks-claude-code/README.i18n.yaml  |    4 +-
 packages/hooks/hooks-claude-code/README.md    |    6 +-
 packages/hooks/hooks-claude-code/README.zh.md |    6 +-
 packages/hooks/hooks-claude-code/package.json |    2 -
 packages/hooks/hooks-claude-code/src/index.ts |   47 +-
 .../hooks-claude-code/tests/bridge.spec.ts    |   24 +-
 .../hooks-claude-code/tests/coverage-cases.ts |   89 +-
 .../hooks/hooks-claude-code/tsconfig.json     |    3 -
 packages/hooks/hooks-codex/README.i18n.yaml   |    4 +-
 packages/hooks/hooks-codex/README.md          |    4 +-
 packages/hooks/hooks-codex/README.zh.md       |    4 +-
 packages/hooks/hooks-codex/package.json       |    2 -
 packages/hooks/hooks-codex/src/index.ts       |   15 +-
 .../hooks/hooks-codex/tests/bridge.spec.ts    |   16 +-
 .../hooks/hooks-codex/tests/coverage-cases.ts |  103 +-
 packages/hooks/hooks-codex/tsconfig.json      |    3 -
 .../tests/loader-composition.spec.ts          |    2 +-
 .../llm/llm-retry/tests/persistence.spec.ts   |   12 +-
 packages/llm/llm-retry/tests/retry.spec.ts    |   54 +-
 .../tests/transport-recovery.spec.ts          |   12 +-
 .../plan/plan-mode/tests/integration.spec.ts  |    6 +-
 .../schedule/tests/jsonl-restart.spec.ts      |   18 +-
 .../schedule/schedule/tests/plugin.spec.ts    |   68 +-
 .../session-log-export/README.i18n.yaml       |    4 +-
 .../session-log-export/README.md              |    5 +-
 .../session-log-export/README.zh.md           |    5 +-
 .../session-log-export/package.json           |    9 +-
 .../session-log-export/src/archive.ts         |  148 +-
 .../session-log-export/src/index.ts           |   26 +-
 .../tests/archive.host.spec.ts                |  421 +--
 .../tests/route.host.spec.ts                  |   33 +-
 .../session-query-sqlite/README.i18n.yaml     |    4 +-
 .../session-query-sqlite/README.md            |    7 +-
 .../session-query-sqlite/README.zh.md         |    7 +-
 .../session-query-sqlite/src/index.ts         |   68 +-
 .../tests/load-path.e2e.ts                    |   12 +-
 .../session-query-sqlite/tests/sqlite.spec.ts |  449 ++--
 .../session-query/README.i18n.yaml            |    4 +-
 .../session-query/session-query/README.md     |   13 +-
 .../session-query/session-query/README.zh.md  |   13 +-
 .../session-query/src/cold-read.ts            |   48 +
 .../session-query/session-query/src/config.ts |   15 +-
 .../session-query/session-query/src/corpus.ts |   39 +-
 .../session-query/session-query/src/index.ts  |   22 +-
 .../session-query/src/observation.ts          |  309 ++-
 .../session-query/session-query/src/types.ts  |    4 +-
 .../session-query/tests/observation.spec.ts   |  840 +++++-
 .../session-query/tests/session-query.spec.ts |  296 +-
 .../session-query/tests/tracing.spec.ts       |  186 +-
 .../tests/sqlite-integration.spec.ts          |   10 +-
 .../tests/crash-recovery.e2e.ts               |   13 +-
 .../tests/session-checkpoint-policy.spec.ts   |   29 +-
 .../README.i18n.yaml                          |    4 +-
 .../session-persistence-jsonl/README.md       |   19 +-
 .../session-persistence-jsonl/README.zh.md    |   19 +-
 .../session-persistence-jsonl/src/index.ts    |  741 +++--
 .../session-persistence-jsonl/src/storage.ts  |  497 ++++
 .../tests/jsonl.spec.ts                       | 1709 ++++++------
 .../tests/zstd.compat.spec.ts                 |    3 +-
 .../tests/zstd.spec.ts                        |  354 +--
 .../session-persistence/README.i18n.yaml      |    4 +-
 .../session/session-persistence/README.md     |   73 +-
 .../session/session-persistence/README.zh.md  |   75 +-
 .../session-persistence/src/coordinator.ts    | 1564 -----------
 .../session/session-persistence/src/errors.ts |  129 +-
 .../session/session-persistence/src/handle.ts |  106 +
 .../session/session-persistence/src/index.ts  |  399 +--
 .../session-persistence/src/preparations.ts   |  401 ---
 .../src/storage-contract.ts                   |  148 +
 .../session-persistence/src/write-behind.ts   |  159 --
 .../session-persistence/tests/contract.ts     |  772 +++---
 .../tests/coordinator-contract.ts             | 1593 -----------
 .../tests/live-write-contract.ts              |  275 ++
 .../tests/persistence.spec.ts                 | 2376 -----------------
 .../tests/preparations.spec.ts                |  432 ---
 .../tests/storage-contract.spec.ts            |  321 +++
 .../tests/write-behind.spec.ts                |  275 --
 .../session/session-projection/src/index.ts   |   10 +-
 .../session-telemetry/src/coordinator.ts      |    8 +-
 .../session-title/tests/persistence.spec.ts   |   54 +-
 packages/shell/shell-env/README.i18n.yaml     |    4 +-
 packages/shell/shell-env/README.md            |    9 +-
 packages/shell/shell-env/README.zh.md         |    9 +-
 packages/shell/shell-env/package.json         |    2 -
 packages/shell/shell-env/src/index.ts         |   21 +-
 .../shell/shell-env/tests/shell-env.spec.ts   |   34 +-
 packages/shell/shell-env/tsconfig.json        |    3 -
 .../shell/tool-bash/tests/integration.spec.ts |   20 +-
 packages/shell/tool-bash/tests/tools.spec.ts  |   90 +-
 .../tests/multi-subagent.spec.ts              |    2 +-
 .../tests/subagent-fork-in-process.spec.ts    |    2 +-
 .../tests/inheritance.spec.ts                 |    2 +-
 .../tests/structured.spec.ts                  |    2 +-
 .../tests/subagent-in-process-driver.spec.ts  |    6 +-
 .../tests/spawn-in-process.e2e.ts             |    2 +-
 .../tests/subagent-spawn-in-process.spec.ts   |    6 +-
 .../subagent/subagent/src/continuation.ts     |  143 +-
 .../tests/continuation-inheritance.spec.ts    |   19 +-
 .../subagent/tests/continuation.spec.ts       |  238 +-
 .../subagent/tests/list-children.spec.ts      |  175 +-
 .../subagent/tests/persistence-helpers.ts     |   33 +
 .../tests/list-agents.spec.ts                 |    2 +-
 .../tests/tool-subagent-control.spec.ts       |   19 +-
 .../tool-subagent/tests/tool-subagent.spec.ts |    9 +-
 .../loader-smoke/src/agent-turn.ts            |   19 +-
 .../loader-smoke/tests/agent-turn.spec.ts     |   24 +-
 .../fixtures/subagent-durability-failure.ts   |   10 +-
 .../todo/tool-todo/tests/integration.spec.ts  |    4 +-
 .../tests/integration.spec.ts                 |    2 +-
 packages/workspace/workspace/src/index.ts     |   14 +-
 .../workspace/tests/workspace.spec.ts         |   25 +-
 pnpm-lock.yaml                                |    9 -
 scripts/gen-cordis-catalog.ts                 |   12 +-
 scripts/package-dependency-policy.ts          |    1 +
 scripts/type-equiv.manifest.json              |   27 +-
 snapshots/web/navigation-panes/session.jsonl  |   20 +-
 snapshots/web/pwsh-terminal/session.jsonl     |    8 +-
 snapshots/web/seeded-history/session.jsonl    |   12 +-
 314 files changed, 9815 insertions(+), 13136 deletions(-)
 rename .agents/notes/{implemented => archived}/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml (66%)
 rename .agents/notes/{implemented => archived}/architecture/2026-06-18-shared-persistence-write-coordinator.md (99%)
 rename .agents/notes/{implemented => archived}/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md (99%)
 rename .agents/notes/implemented/{bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml => architecture/2026-08-27-handle-based-session-persistence.i18n.yaml} (55%)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
 rename .agents/notes/implemented/{bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml => simplification/2026-08-27-persistence-export-and-pre-release-trims.i18n.yaml} (52%)
 create mode 100644 .agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.md
 create mode 100644 .agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md
 delete mode 100644 apps/web/tests/cold-blank-session.e2e.ts
 delete mode 100644 apps/web/tests/expected/cold-blank-session/sidebar.expected.md
 create mode 100644 packages/core/agent-loop/tests/shutdown-drain.spec.ts
 create mode 100644 packages/experimental/agent-team/src/persisted.ts
 create mode 100644 packages/session-query/session-query/src/cold-read.ts
 create mode 100644 packages/session/session-persistence-jsonl/src/storage.ts
 delete mode 100644 packages/session/session-persistence/src/coordinator.ts
 create mode 100644 packages/session/session-persistence/src/handle.ts
 delete mode 100644 packages/session/session-persistence/src/preparations.ts
 create mode 100644 packages/session/session-persistence/src/storage-contract.ts
 delete mode 100644 packages/session/session-persistence/src/write-behind.ts
 delete mode 100644 packages/session/session-persistence/tests/coordinator-contract.ts
 create mode 100644 packages/session/session-persistence/tests/live-write-contract.ts
 delete mode 100644 packages/session/session-persistence/tests/persistence.spec.ts
 delete mode 100644 packages/session/session-persistence/tests/preparations.spec.ts
 create mode 100644 packages/session/session-persistence/tests/storage-contract.spec.ts
 delete mode 100644 packages/session/session-persistence/tests/write-behind.spec.ts
 create mode 100644 packages/subagent/subagent/tests/persistence-helpers.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
similarity index 66%
rename from .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
rename to .agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index a6f873d0f8..1d5dbfcc3e 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.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 .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
-2026-06-18-shared-persistence-write-coordinator.md: a61ceb9b2197a6dd8ed86c1c971373a2706607aa
-2026-06-18-shared-persistence-write-coordinator.zh.md: 777d5f5972ac1096c2e3434f9e0ac5aec27e8c26
+2026-06-18-shared-persistence-write-coordinator.md: 5c324f2c0c2b951f664bcf92725a36c4975fd3a1
+2026-06-18-shared-persistence-write-coordinator.zh.md: 51ef76189cb9276214bf05bbd1dbd8e3755daa35
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md b/.agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.md
similarity index 99%
rename from .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
rename to .agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.md
index a61ceb9b21..5c324f2c0c 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
+++ b/.agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.md
@@ -1,6 +1,7 @@
 # Agent Note: Shared persistence write coordinator
 
 Status: implemented
+Archived: 2026-08-31
 
 English | [中文](2026-06-18-shared-persistence-write-coordinator.zh.md)
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
similarity index 99%
rename from .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
rename to .agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index 777d5f5972..51ef76189c 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/archived/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 共享持久化写入协调器
 
 Status: implemented
+Archived: 2026-08-31
 
 [English](2026-06-18-shared-persistence-write-coordinator.md) | 中文
 
diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json
index 18173d7d3d..fa3abbea4f 100644
--- a/.agents/notes/archived/manifest.json
+++ b/.agents/notes/archived/manifest.json
@@ -10,6 +10,9 @@
     "architecture/2026-06-15-turn-enclosure-invariant.i18n.yaml": "sha256:7eb471a53b7bef104c57e9343b80d672763f062ecb086b01b318b65b488d3c02",
     "architecture/2026-06-15-turn-enclosure-invariant.md": "sha256:afefa3a268c84f26cf5461e08933245352a9e63cff688d3c398c8064a4ac6e85",
     "architecture/2026-06-15-turn-enclosure-invariant.zh.md": "sha256:c54fdac980abc922cdc252a8fef59e4bdd7567316c7fbb6f7dbc035e470d95fa",
+    "architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml": "sha256:3c5c22e9e6a63598ba648cad46d783af322cf3afd6021426a2d738f4b026bf65",
+    "architecture/2026-06-18-shared-persistence-write-coordinator.md": "sha256:d5242c770101086b6f0a0c40eab500d405ef4a98cae07e28d9ec21e89d94f90e",
+    "architecture/2026-06-18-shared-persistence-write-coordinator.zh.md": "sha256:3dce52e302600a0eea29b4821a2718b6bbc1ebe4c6c2ae372cd0cbe66cb05519",
     "architecture/2026-06-20-extract-example-app-packages.i18n.yaml": "sha256:d99b612cc1051c86d883d74737c72e921735e7a28e0b5e6351d3870c664bdcc4",
     "architecture/2026-06-20-extract-example-app-packages.md": "sha256:9c7aca3a1e9a1ccc3729961663bc649b90076e671cae23e3db8203305983ccce",
     "architecture/2026-06-20-extract-example-app-packages.zh.md": "sha256:19bd50232d9f25d35aa3f9dc72d9af0df457dd0eaca8b982d5aa625e5b95bcff",
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index 3bdde9ece6..34927aeae7 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.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 .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
-2026-06-14-session-persistence.md: 50ec79de83f0cef4a3ec94b689cc25937e334016
-2026-06-14-session-persistence.zh.md: 7b66aed6f077ac484802cfa1e23e1ba7ac3ae985
+2026-06-14-session-persistence.md: a7e06af78c4a372be7a68f3e0f6dc18e38cbead1
+2026-06-14-session-persistence.zh.md: 6d458d4f4c31793212d674bb406204c3882a25ed
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
index 50ec79de83..a7e06af78c 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
@@ -14,22 +14,22 @@ The [event-sourced model](2026-06-11-event-sourced-sessions.md) makes the append
 
 Persistence is a **capability seam** with an abstract Service Definition ([capability seams](2026-06-13-capability-seams.md), the `dsh-shell` template), not loop or core logic:
 
-1. **Interface** (`dsh-session-persistence`, `ctx.sessionPersistence`) — an abstract `SessionPersistence` service: `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`. Its persisted unit IS the existing `SessionEvent` (`{ type, seq, time, data }`), reused verbatim — no conversion type.
+1. **Interface** (`dsh-session-persistence`, `ctx.sessionPersistence`) — an abstract `SessionPersistence` service: `create`/`open`/`stat`/`list`/`export`, with `create`/`open` returning per-session `SessionHandle`s that carry `read`/`append`/`flush`/`close` ([handle-based seam](2026-08-27-handle-based-session-persistence.md)). Its persisted unit IS the existing `SessionEvent` (`{ type, seq, time, data }`), reused verbatim — no conversion type.
 2. **Implementation** (`dsh-session-persistence-jsonl`) — an append-only logical JSONL log per session: a `SessionHeader` line followed by storage records that losslessly represent the contiguous `SessionEvent` stream. Eligible `assistant/chunk` delta runs use packed rows by default; [checksummed Zstandard frames](2026-07-19-zstandard-jsonl-session-logs.md) are the default physical encoding, with raw lines configurable.
 
 Key durable, contested choices:
 
 - **The canonical durable log persists every `SessionEvent` losslessly, including `assistant/chunk`.** JSONL storage may encode a consecutive delta run as one packed row, but logical readers reconstruct the exact event boundaries, sequence numbers, and timestamps. `deriveMessages()` skips chunks, and a chunk-filtered rollout (Codex's `policy.rs`) is tempting — but `seq = log.length` and validation of `events[i].seq === i` require a *contiguous* logical log; filtering chunks out would leave holes and break both the contract and resume. A chunk-filtered projection is possible later as a derived view with its own renumbering, but it is NOT the canonical log.
-- **Append-only; a crashed turn is closed, never truncated.** Flushed events are never rewritten. The [semantic checkpoint policy](../bug-fix/2026-07-21-semantic-session-checkpoints.md) drains the request before model dispatch, a recorded top-level call before tool dispatch, and the complete response/result batch after a step; the loop drains the final turn boundary. Because one interrupted turn may contain substantial valid work, cold inspection preserves its contiguous, parseable events and adds risk-classified error results for unanswered assistant calls, a missing `step/end`, and `turn/end` with `{ kind: 'interrupted' }` to the in-memory logical view. `prepare` or `load` commits those closers before returning a recoverable view; the synthetic results keep resumed provider transcripts valid. Only an incomplete final record is discarded during committed repair; a parse error or sequence gap at or before the last real `turn/end` is corruption and makes the session unloadable.
-- **The file backend is canonical while the service remains extensible.** `dsh-session-persistence-jsonl` is the sole first-party provider and passes `runPersistenceContract`; the abstract service and coordinator remain available to out-of-tree providers. The [JSONL-only persistence decision](../simplification/2026-08-30-jsonl-only-session-persistence.md) owns removal of the first-party database provider and its deliberate compatibility cut.
+- **Append-only; a crashed turn is closed, never truncated.** Flushed events are never rewritten. The [semantic checkpoint policy](../bug-fix/2026-07-21-semantic-session-checkpoints.md) drains the request before model dispatch, a recorded top-level call before tool dispatch, and the complete response/result batch after a step; the loop drains the final turn boundary. Because one interrupted turn may contain substantial valid work, persistence returns its contiguous, parseable events unmodified; the reader owns balancing — resume computes risk-classified error results for unanswered assistant calls, a missing `step/end`, and `turn/end` with `{ kind: 'interrupted' }` (`interruptedTurnClosers`) and appends them through its write handle, while read-only observers add the same closers in memory. The synthetic results keep resumed provider transcripts valid. Only the incomplete fragment of a torn final append is discarded — complete records recovered from it are durably rewritten by the write path before its first new append; a parse error or sequence gap in the committed prefix is corruption and makes the session unloadable.
+- **The file backend is canonical while the service remains extensible.** `dsh-session-persistence-jsonl` is the sole first-party provider and passes `runPersistenceContract`; the abstract service remains available to out-of-tree providers. The [JSONL-only persistence decision](../simplification/2026-08-30-jsonl-only-session-persistence.md) owns removal of the first-party database provider and its deliberate compatibility cut.
 - **Metadata is out-of-log.** Format version, cwd, and lineage are storage concerns, not replayable conversation state, so they live in a `SessionHeader` owned by `dsh-session` and attached to a `Session` via a new readonly `session.header` — never in `SessionEventMap`, never reaching `deriveMessages()`. `createdAt` is non-negative safe-integer Unix epoch milliseconds: live creation and persistence registration reject fractional values, and JSONL validates the decoded header. The alternative (a merge-extensible `session/meta` event as log line 0) was rejected: an in-log event would ride along with a seeded/forked session for free, but metadata is not replayable state, so the explicit out-of-log header boundary is the cleaner cost. (The header was originally split into an immutable `SessionHeader` plus a mutable `SessionSummary` whose union was `SessionMeta`; the mutable summary was later removed as dead state — see [Drop the mutable session summary](../simplification/2026-06-19-drop-mutable-session-summary.md).)
-- **`ctx.agents.create()` and `ctx.agents.resume()` are async factories; resume additionally crosses the persistence boundary.** `ctx.agents.resume({ resumeSessionId })` obtains the exact unpublished Session through `ctx.sessionPersistence.prepare()`, publishes it under the persisted id, and continues its projections. The [Session preparation decision](2026-08-05-session-preparation.md) owns reuse between history inspection and resume. The agent-loop does NOT hard-inject `sessionPersistence` (that would pend non-persistent demos forever); `resume` rejects with a clear error when it is absent.
+- **`ctx.agents.create()` and `ctx.agents.resume()` are async factories; resume additionally crosses the persistence boundary.** `ctx.agents.resume({ resumeSessionId })` opens the session's write handle, reads the stored log, and publishes the prepared Session under the persisted id, continuing its projections. The [Session preparation decision](2026-08-05-session-preparation.md) owns the unpublished-Session ownership window. The agent-loop does NOT hard-inject `sessionPersistence` (that would pend non-persistent demos forever); `resume` rejects with a clear error when it is absent.
 
 ## Alternatives considered
 
 Each key choice above records its rejected alternative where the choice is stated: a **chunk-filtered canonical log** (Codex's `policy.rs` shape) — breaks the contiguous-seq contract; **truncating a crashed turn** — silently destroys a long autonomous run's real work; an **in-log `session/meta` event as log line 0** — metadata is not replayable state; **finite fractional `createdAt` values** — have no producer and diverge from integer Unix-millisecond storage; **hard-injecting `sessionPersistence` into the loop** — would pend non-persistent demos forever.
 
-Format versioning: the header carries a `version`; cold reads reject any non-current version. The pre-release session format stays pinned at `SESSION_FORMAT_VERSION = 0` and carries no broad compatibility promise, while the coordinator may own an explicit narrow import upgrade when persisted user data requires it ([pre-identity message recovery](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)). Append-only + flush is robust to partial trailing writes tolerated during cold preparation; a future provider or write-ahead log needs its own power-loss and recovery contract.
+Format versioning: the header carries a `version`; cold reads reject any non-current version. The pre-release session format stays pinned at `SESSION_FORMAT_VERSION = 0` and carries no compatibility promise: reads validate current v0 records only, and retired same-version shapes refuse fail-closed ([export and pre-release trims](../simplification/2026-08-27-persistence-export-and-pre-release-trims.md)). Append-only + flush is robust to partial trailing writes (tolerated during cold preparation) but not to fsync-less power loss mid-line; a DB/WAL backend is the stronger option there.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index 7b66aed6f0..6d458d4f4c 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -14,22 +14,22 @@ Status: implemented
 
 持久化是一个具有抽象 Service Definition 的**能力 seam**（[能力 seam](2026-06-13-capability-seams.zh.md)，`dsh-shell` 模板），而非循环或核心逻辑：
 
-1. **接口**（`dsh-session-persistence`，`ctx.sessionPersistence`）：一个抽象的 `SessionPersistence` 服务，提供 `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`。其持久化单元就是现有的 `SessionEvent`（`{ type, seq, time, data }`），原样复用，无转换类型。
+1. **接口**（`dsh-session-persistence`，`ctx.sessionPersistence`）：一个抽象的 `SessionPersistence` 服务，提供 `create`/`open`/`stat`/`list`/`export`，其中 `create`/`open` 返回逐会话的 `SessionHandle`，句柄承载 `read`/`append`/`flush`/`close`（[基于句柄的 seam](2026-08-27-handle-based-session-persistence.zh.md)）。其持久化单元就是现有的 `SessionEvent`（`{ type, seq, time, data }`），原样复用，无转换类型。
 2. **实现**（`dsh-session-persistence-jsonl`）：每个会话一个仅追加的逻辑 JSONL 日志：先是一行 `SessionHeader`，随后是无损表示连续 `SessionEvent` 流的存储记录。符合条件的 `assistant/chunk` 增量连续段默认使用打包行；[带校验和的 Zstandard 帧](2026-07-19-zstandard-jsonl-session-logs.zh.md)是默认物理编码，也可通过配置使用原始行。
 
 长期有效、存在争议的关键选择：
 
 - **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏约定和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
-- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.zh.md)会在调用模型前排空请求、在调用工具前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些收尾事件；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
-- **文件后端为规范实现，服务保持可扩展。** `dsh-session-persistence-jsonl` 是唯一 first-party provider，并通过 `runPersistenceContract`；抽象服务与 coordinator 继续供仓库外 provider 使用。[JSONL-only 持久化决策](../simplification/2026-08-30-jsonl-only-session-persistence.zh.md)负责 first-party 数据库 provider 的删除及其明确 compatibility cut。
+- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.zh.md)会在调用模型前排空请求、在调用工具前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，持久化会原样返回其连续、可解析的事件；配平是读方的职责——resume 会为未应答的 assistant 调用计算按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`（`interruptedTurnClosers`），并通过其写句柄追加它们，而只读观察方仅在内存中添加同样的收尾事件。合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有撕裂的最终 append 中不完整的碎片会被丢弃——从中恢复的完整记录由写路径在第一次新 append 之前持久重写；已提交前缀中的解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
+- **文件后端为规范实现，服务保持可扩展。** `dsh-session-persistence-jsonl` 是唯一 first-party provider，并通过 `runPersistenceContract`；抽象服务继续供仓库外 provider 使用。[JSONL-only 持久化决策](../simplification/2026-08-30-jsonl-only-session-persistence.zh.md)负责 first-party 数据库 provider 的删除及其明确 compatibility cut。
 - **元数据在日志之外。** 格式版本、cwd 和谱系是存储关注点，不是可回放的对话状态，因此它们存放在 `dsh-session` 拥有的 `SessionHeader` 中，并通过新的只读属性 `session.header` 附加到 `Session` 上——永远不进入 `SessionEventMap`，永远不到达 `deriveMessages()`。`createdAt` 是以 Unix epoch 毫秒表示的非负安全整数：运行时创建和持久化注册会拒绝小数值，JSONL 会验证解码后的 header。替代方案（一个可合并扩展的 `session/meta` 事件作为日志第 0 行）被否决：日志内事件会自然随 seed/fork 的会话携带，但元数据不是可回放状态，因此显式的日志外 header 边界是更清晰的取舍。（header 最初被拆分为不可变的 `SessionHeader` 加可变的 `SessionSummary`，二者的联合类型为 `SessionMeta`；可变 summary 后来因属于死状态而被移除——见 [移除可变会话摘要](../simplification/2026-06-19-drop-mutable-session-summary.zh.md)。）
-- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得精确的未发布 Session，以持久化 id 发布它，并继续其投影。[Session 准备阶段决策](2026-08-05-session-preparation.zh.md)定义历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
+- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 打开该会话的写句柄，读取已存储的日志，并以持久化 id 发布准备好的 Session，继续其投影。[Session 准备阶段决策](2026-08-05-session-preparation.zh.md)定义未发布 Session 的所有权窗口。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
 
 ## 曾考虑的替代方案
 
 上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 约定；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储不一致；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
 
-格式版本控制：header 携带一个 `version`；冷读取拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不承诺广泛兼容；当持久化用户数据确有需要时，协调器可以负责显式且范围受限的导入升级（[消息标识机制引入前的消息恢复](../bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md)）。仅追加 + 刷写能承受冷准备时可容忍的尾部不完整写入；未来 provider 或 write-ahead log 需要自有的断电与恢复约定。
+格式版本控制：header 携带一个 `version`；冷读取拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不作兼容承诺：读取只校验当前 v0 记录，已废弃的同版本形态会以 fail-closed 方式拒绝（[导出与预发布精简](../simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md)）。仅追加 + 刷写对尾部的不完整写入具有健壮性（冷准备时可容忍），但无法抵御未使用 fsync 时在行写入中途断电；数据库/WAL 后端是该场景下更强的选项。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
index f53ede9338..38f55f03e8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.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 .agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
-2026-07-19-zstandard-jsonl-session-logs.md: 93fc20f931c75552352834b9340e7d38680d4254
-2026-07-19-zstandard-jsonl-session-logs.zh.md: d58f89430ab91de6beabba83c2a31f43e4a7d275
+2026-07-19-zstandard-jsonl-session-logs.md: 33486251a8b018cda61a2845a55218f13c38072b
+2026-07-19-zstandard-jsonl-session-logs.zh.md: 5e6b4a1ed7cf5869e1700c2884898b9899452a30
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
index 93fc20f931..33486251a8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
@@ -32,7 +32,7 @@ A frame-boundary scanner reads the standard magic, variable header fields, block
 
 Listing reads in bounded chunks only until the first complete frame is available, validates and decompresses that header frame, and never reads an event frame. The dedicated header frame therefore preserves metadata-only listing even for very large session logs.
 
-EOF inside the final frame is a recoverable torn tail. After the scanner establishes that boundary, a dedicated prefix decoder uses `finishFlush: ZSTD_e_flush` so Node emits available plaintext without requiring frame or checksum completion; every complete newline-terminated event it emits is retained. Repair truncates from that frame's starting byte and appends one new checksummed frame containing the recovered complete events followed by the coordinator's synthetic tool, step, and turn closers. If the tear occurs before any complete event is decodable, repair drops the partial frame and retains all prior complete frames.
+EOF inside the final frame is a torn tail. The frame belongs to an append that never resolved, so none of its records were acknowledged durable: repair truncates from that frame's starting byte, retains all prior complete frames, and appends the coordinator's synthetic tool, step, and turn closers as one new checksummed frame ([export and pre-release trims](../simplification/2026-08-27-persistence-export-and-pre-release-trims.md) owns dropping the earlier partial-plaintext salvage).
 
 ### Consumers and verification
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
index d58f89430a..5e6b4a1ed7 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
@@ -32,7 +32,7 @@ JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量
 
 列举只按有界分片读取到第一个完整帧可用为止，验证并解压该头部帧，绝不读取事件帧。因此，即使会话日志很大，专用头部帧仍能维持仅元数据列举。
 
-最终帧内部遇到 EOF 属于可恢复的撕裂尾部。扫描器确定该边界后，专用前缀解码器会使用 `finishFlush: ZSTD_e_flush`，使 Node 不必等到帧结束或读到完整校验和就能产出已有明文；其中每个完整且以换行结束的事件都会保留。修复从该帧起始字节截断，再追加一个新的带校验和帧，其中依次包含恢复出的完整事件，以及协调器生成的工具、步骤与轮次闭合事件。如果撕裂位置尚不足以解码任何完整事件，修复会丢弃该不完整帧并保留此前全部完整帧。
+最终帧内部遇到 EOF 属于撕裂尾部。该帧属于一次从未完成结算的追加，因此其中没有任何记录被确认为持久：修复从该帧起始字节截断，保留此前全部完整帧，并把协调器生成的工具、步骤与轮次闭合事件作为一个新的带校验和帧追加（对早先部分明文抢救路径的移除由[导出与预发布精简](../simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md)负责）。
 
 ### 消费方与验证
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.i18n.yaml
index c20fc92181..e1483287f0 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.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 .agents/notes/implemented/architecture/2026-07-24-project-session-directories.md
-2026-07-24-project-session-directories.md: 0aa3f513d5a1bb3e44cf33a0ae1eb791ee3a46c2
-2026-07-24-project-session-directories.zh.md: 932b1d29c41d2a854abfc0bab0e47a0ff8c96fe9
+2026-07-24-project-session-directories.md: a37f9231167822e409308f8da60f6c1e837c74d5
+2026-07-24-project-session-directories.zh.md: 469567764219d7baabea89bd94aecd81bd0e5ab3
diff --git a/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.md b/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.md
index 0aa3f513d5..a37f923116 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.md
@@ -29,7 +29,7 @@ Case-insensitive filesystems can also make differently cased project keys refer
 
 The configured root remains a deployment choice. The layout neither selects a global root nor requires projects to share one. When a deployment does centralize storage, project paths remain recognizable; a project-local root uses the same deterministic structure.
 
-The encoded session id names an ownership directory rather than the transcript itself. `SessionPersistence.locate()` continues to return the fixed transcript path, preserving hook `transcript_path` and `DSH_SESSION_JSONL` semantics. Discovery ignores other entries inside the session directory so the backend can add session-owned artifacts without another layout change.
+The encoded session id names an ownership directory rather than the transcript itself. The backend's diagnostics-only `locate` hook resolves the fixed transcript path inside it for format-refusal messages ([export and pre-release trims](../simplification/2026-08-27-persistence-export-and-pre-release-trims.md) owns removing the consumer-facing path query). Discovery ignores other entries inside the session directory so the backend can add session-owned artifacts without another layout change.
 
 Lazy materialization remains tied to the transcript: `create()` performs no filesystem I/O, and the first append creates the project/session directories before collision-safe transcript publication. Empty directories are not listed as sessions. The backend rejects flat `<project>/<id>.jsonl*` artifacts with an explicit layout error; the pre-release format provides no automatic data migration.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.zh.md b/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.zh.md
index 932b1d29c4..4695677642 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-project-session-directories.zh.md
@@ -29,7 +29,7 @@ JSONL 后端按可读的项目键存储会话，并为每个会话提供独立
 
 根目录由部署配置决定。这种布局既不选择全局根目录，也不要求项目共享根目录。部署选择集中存储时，目录名仍能让项目路径易于辨认；使用项目本地根目录时，也采用同样的确定性结构。
 
-编码后的会话 id 用于命名归属目录，而不是 transcript 文件本身。`SessionPersistence.locate()` 仍返回固定的 transcript 路径，从而保持钩子 `transcript_path` 和 `DSH_SESSION_JSONL` 的语义不变。发现过程会忽略会话目录中的其他条目，因此后端以后添加会话自有产物时无需再次改变布局。
+编码后的会话 id 用于命名归属目录，而不是 transcript 文件本身。后端仅供诊断的 `locate` 钩子在其中解析固定的 transcript 路径，供格式拒绝消息使用（移除面向消费者的路径查询由[导出与预发布裁剪](../simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md)负责）。发现过程会忽略会话目录中的其他条目，因此后端以后添加会话自有产物时无需再次改变布局。
 
 延迟物化仍以 transcript 为界：`create()` 不执行文件系统 I/O，首次追加会先创建项目目录和会话目录，再以无冲突方式发布 transcript。空目录不会被列为会话。后端会显式报告布局错误并拒绝扁平的 `<project>/<id>.jsonl*` 产物；预发布格式不提供自动数据迁移。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
index 3e3b610f73..e96c1b2e6b 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.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 .agents/notes/implemented/architecture/2026-08-05-session-preparation.md
-2026-08-05-session-preparation.md: 50f1ea38e671c6aa7b0f4adaf2fecbf83decc23c
-2026-08-05-session-preparation.zh.md: cd918d126b56b081bcc1b6aa43a10d662668102d
+2026-08-05-session-preparation.md: 040c9f788173a7cedd91be33cbe7ced3ca758a06
+2026-08-05-session-preparation.zh.md: 44b609d488c6f8bb406370f9097eb2a085f7cc2b
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
index 50f1ea38e6..040c9f7881 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
@@ -6,63 +6,40 @@ English | [中文](2026-08-05-session-preparation.zh.md)
 
 ## Problem
 
-Cold history inspection and Agent resume independently materialized the same persisted session log. For a large compressed log, each operation repeated the full read, decompression, parse, validation, freezing, and Session construction. Pagination could therefore pay the cold-read cost again, while making a history query activate an Agent would couple a read lifecycle to a live Agent with no natural retirement point.
+Fresh creation and persisted resume reached the same publication boundary through different construction flows. This obscured the invariant that setup must finish against one unpublished Session before that exact Session and its Agent become visible together.
 
-Fresh creation and persisted resume also reached the same publication boundary through different construction flows. This obscured the invariant that setup must finish against one unpublished Session before that exact Session and its Agent become visible together.
+Cold history inspection and Agent resume also independently materialized the same persisted session log, which this note originally answered with a persistence-side prepared-Session cache; that half is superseded below.
 
 ## Decision
 
-`SessionPreparation` owns one exact unpublished `Session` until publication or rollback. It is a Session lifecycle object, not an Agent lifecycle or activation object. Fresh creation wraps the result of `SessionStore.prepare()`; persisted resume obtains a preparation from `SessionPersistence.prepare()`.
+`SessionPreparation` owns one exact unpublished `Session` until publication or rollback. It is a Session lifecycle object, not an Agent lifecycle or activation object. Fresh creation wraps the result of `SessionStore.prepare()`; persisted resume reads the stored log through the session's write handle, appends `interruptedTurnClosers`, and wraps `SessionStore.prepare(id, { seed, meta, seedSource: 'persistence' })` — the restoration branch that validates and freezes the transferred graphs in place.
 
 The Agent loop consumes both forms through one setup-and-publication pipeline: it acquires the preparation, builds the private Agent context around `preparation.session`, awaits optional setup, publishes that exact Session and Agent, and disposes the preparation on every exit. Publication transfers the live lifecycle to the existing Session and Agent stores; `SessionPreparation` itself owns no Agent behavior.
 
 This refines the publication boundary from the [Agent lifecycle and ownership decision](2026-06-18-agent-lifecycle-and-ownership-contracts.md) without replacing its ownership model.
 
-## Persisted preparation lifecycle
+## Superseded: the persistence-side preparation lifecycle
 
-A coordinator-backed persistence implementation loads one cold source into a prepared Session. The backend transfers fresh, mutually unaliased metadata and events together with the source-qualified revision that identifies those exact values; the Session restore path validates and freezes the graphs in place instead of cloning them. The coordinator computes interrupted-turn closers and constructs the exact unpublished Session once. Its immutable header and balanced logical event log form the `SessionInspection` borrowed by readers, while the revision remains internal to persistence.
-
-`inspect(id, signal?)` does not mutate storage. Synthetic closers exist only in the prepared in-memory view, and a torn physical tail remains untouched. Same-id callers share an in-flight cold read. Once ready, the preparation may remain in a per-coordinator LRU whose capacity defaults to five and is configurable by first-party backends. Before reusing a retained source, the coordinator reads that id's current revision; a mismatch evicts a ready source and repeats the cold materialization. A source already committing or reserved for resume remains exclusively owned, so concurrent inspection borrows that immutable view until publication or release.
-
-`prepare(id, signal?)` exclusively reserves the prepared Session. It confirms the retained revision before committing any torn-tail and interrupted-turn repair, establishes the durable cursor, then returns a disposable preparation. A stale source is discarded and reloaded instead of being repaired or published. A successful repair also discards the pre-repair source and materializes the committed log again before reservation, so a newer revision is never associated with an older event graph. Another same-id preparation waits until the reservation is published or released. Publication accepts only the exact reserved Session and attaches the committed cursor without rebuilding its history. Failed setup or cancellation returns an unchanged unpublished Session to the LRU; mutation or attachment consumes the reservation.
-
-The legacy `load(id)` API uses the same preparation and repair machinery, then discards its reservation and returns the immutable logical view. It remains a compatibility API, not the history-to-resume reuse path. This lifecycle extends the [shared persistence coordinator](2026-06-18-shared-persistence-write-coordinator.md) while preserving the storage and recovery rules owned by the [session persistence decision](2026-06-14-session-persistence.md).
-
-## History and resume reuse
-
-History reads use `inspect()`, so repeated pages borrow the same immutable prepared state without activating an Agent. A later resume uses `prepare()` and receives the exact Session retained by inspection; it does not read, decompress, parse, clone, validate, or freeze the complete log again.
-
-If the durable log changes after inspection, its revision changes. The next history read or resume discards a retained ready Session and materializes the new log, so an old event graph cannot be associated with a newer snapshot revision. A source already claimed by an in-flight resume is not evicted: its exclusive owner keeps it through publication or release, and concurrent history may borrow the same immutable view.
-
-Cold continuable-subagent access follows the same path. Descriptor authorization first inspects the child, then `ctx.agents.resume()` reserves and publishes the retained Session. This preserves the lifecycle and authorization rules in the [continuable subagent conversation decision](../feature/2026-07-28-continuable-subagent-conversations.md) while removing its duplicate cold read.
+This note originally also gave persistence a `prepare(id)`/`inspect(id)` lifecycle: a coordinator-backed bounded LRU of cold unpublished Sessions with exclusive reservations, revision-checked reuse, and repair committed inside `prepare`/`load`, so history pagination and a later resume shared one cold materialization. The [handle-based persistence seam](2026-08-27-handle-based-session-persistence.md) deletes all of it: persistence exposes handles only, resume reads the log through its write handle and owns repair, and read-only observers (session-query) own their cold-Session cache keyed by the `stat().revision` change token. The read-reuse goal survives in that cache; the exclusive-reservation machinery does not, because the write handle's single-writer ownership is the exclusion resume actually needs. Resume pays one whole-log read through the handle where the prepared cache sometimes served a warm Session — an accepted cost recorded in the handle note.
 
 ## Boundaries
 
-- `readFrom()` remains a detached physical-suffix API. It neither creates nor consumes a preparation, synthesizes logical closers, or joins the LRU.
-- HMR adoption keeps the live Session authoritative and reads the stored prefix directly. It may truncate a torn physical fragment but never closes the live open turn as interrupted.
-- The cache belongs to one persistence coordinator, not a process-global Session map. Live Sessions are owned by the existing stores and never occupy preparation capacity.
-- A fresh create never claims a cold persisted preparation with the same id. Persistence collisions continue to reject.
-- Third-party persistence implementations retain the abstract `prepare()` fallback through `load()`. They receive the same publication interface but gain exact-object reuse only when they override preparation.
-- Revision validation establishes freshness at the reuse and repair-commit points; it does not add cross-process writer exclusion to a backend. Retries converge after the durable log remains unchanged for one read/check round trip, so continuous external writers can delay preparation.
+- The preparation is one disposable ownership window, not a cache: disposal is synchronous and idempotent, and publication accepts only the exact prepared Session.
+- A fresh create never claims a persisted identity implicitly. Persistence collisions continue to reject (`SessionAlreadyExistsError`, `SessionAlreadyOwnedError`).
+- Live Sessions are owned by the existing stores; preparations hold only unpublished ones.
 
 ## Verification
 
-The shared persistence contract pins non-mutating balanced cold inspection and later repair. `persistence.spec.ts` and `preparations.spec.ts` pin same-id in-flight sharing, exact Session reuse across inspect and prepare, revision-triggered refresh before history and resume, single repair commit, exclusive reservation, release after failed setup, ready-entry LRU eviction, append rejection during reservation, and publication of only the reserved Session. Backend tests pin that full and lightweight reads use the same revision identity. Agent-loop and continuable-subagent tests pin the common publication pipeline and inspection-to-resume path across cancellation and teardown.
+Agent-loop tests pin the common publication pipeline across create, `createAgent`, and resume, including rollback on setup failure, cancellation, and teardown, and that disposal releases the write handle (reopening for write succeeds). Session-store tests pin the restoration branch's validate-and-freeze-in-place transfer.
 
 ## Alternatives considered
 
-**Activate an Agent for history reads.** Rejected because pagination would keep query-only Agents live and transfer cache retirement into the Agent lifecycle.
+**Activate an Agent for history reads.** Rejected because pagination would keep query-only Agents live and transfer cache retirement into the Agent lifecycle. This rationale still guards the session-query cold cache: observation never creates an Agent.
 
-**Cache only `{ meta, events }`.** Rejected because resume would still reconstruct, validate, freeze, and copy a Session from the cached values. The exact unpublished Session is the reusable unit.
+**Cache only `{ meta, events }`.** Rejected at the time because resume would still reconstruct a Session from the cached values. Under the handle seam this is exactly what the read side does — session-query caches a cold Session per revision for reads only — while resume rebuilds from the handle read, trading the warm-Session reuse for a single write-ownership door.
 
-**Keep a process-global Session map.** Rejected because it would cross backend and runtime ownership boundaries, retain unbounded identities, and duplicate the live Session store.
-
-**Add a restore transaction or coordinator to the Agent loop.** Rejected because cold reading, repair, reservation, and cursor attachment are persistence and Session concerns. The Agent loop only needs the uniform `SessionPreparation` ownership boundary.
-
-**Turn `readFrom()` into logical preparation.** Rejected because watermark consumers need a detached physical suffix and, on seek-capable backends, a bounded read. Recovery balancing and whole-Session reuse have different semantics.
+**Add a restore transaction or coordinator to the Agent loop.** Rejected because cold reading and Session construction are persistence and Session concerns. The Agent loop only needs the uniform `SessionPreparation` ownership boundary; the handle seam kept that split while moving repair to the loop's resume path.
 
 ## Consequences
 
-One cold materialization can serve history pagination, subagent descriptor inspection, and a later resume. Ownership transfer removes redundant restoration clones, while the bounded per-coordinator LRU limits memory and avoids creating live Agents for queries. Create and resume share one publication protocol without merging Agent and Session responsibilities.
-
-The first cold inspection now pays the complete validation and Session-construction cost and may retain that unpublished Session until eviction. Persistence must coordinate reservation, append, repair, and publication, and callers must treat inspection values as immutable borrowed state. Backends that rely on the default `prepare()` remain correct but do not receive the reuse optimization.
+Create and resume share one publication protocol without merging Agent and Session responsibilities, and every exit path disposes exactly one preparation. The persistence-side reuse consequences originally recorded here (shared cold materialization, LRU bounds, reservation coordination) now belong to the [handle note](2026-08-27-handle-based-session-persistence.md) and the session-query cache that replaced them.
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
index cd918d126b..44b609d488 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
@@ -6,63 +6,40 @@ Status: implemented
 
 ## 问题
 
-冷历史检查和 agent（智能体）恢复会分别实体化同一份持久会话日志。对于大型压缩日志，每次操作都会重新完整读取、解压、解析、验证、冻结并构造 Session。因此，历史分页可能反复承担冷读成本；如果改为由历史查询激活 agent，读取生命周期又会与缺少自然退出时机的实时 agent 耦合。
+新建和持久化恢复通过不同构造流程抵达相同的发布边界。这使一项关键不变量不够清楚：设置必须基于一个未发布的 Session 完成，之后系统才能同时公开这个精确 Session 及其 agent。
 
-新建和持久化恢复也通过不同构造流程抵达相同的发布边界。这使一项关键不变量不够清楚：设置必须基于一个未发布的 Session 完成，之后系统才能同时公开这个精确 Session 及其 agent。
+冷历史检查和 agent（智能体）恢复也曾分别实体化同一份持久会话日志，本 Note 最初以持久化侧的已准备 Session 缓存回答了这一半问题；那一半已在下文中被取代。
 
 ## 决策
 
-`SessionPreparation` 持有一个精确的未发布 `Session`，直至发布或回滚。它属于 Session 生命周期，不属于 agent 生命周期或激活机制。新建流程包装 `SessionStore.prepare()` 的结果；持久化恢复则从 `SessionPersistence.prepare()` 取得准备对象。
+`SessionPreparation` 持有一个精确的未发布 `Session`，直至发布或回滚。它属于 Session 生命周期，不属于 agent 生命周期或激活机制。新建流程包装 `SessionStore.prepare()` 的结果；持久化恢复通过该会话的写句柄读取已存储的日志、追加 `interruptedTurnClosers`，再包装 `SessionStore.prepare(id, { seed, meta, seedSource: 'persistence' })`——即就地验证并冻结转移对象图的恢复分支。
 
 agent loop（智能体循环）通过同一条设置与发布流水线消费这两种形式：先取得准备对象，围绕 `preparation.session` 构建私有 agent 上下文，等待可选设置完成，再发布该精确 Session 和 agent，并在所有退出路径上对准备对象执行 dispose（资源释放）。发布后，实时生命周期由现有 Session 与 agent 存储接管；`SessionPreparation` 本身不负责任何 agent 行为。
 
 该机制细化了 [agent 生命周期与所有权决策](2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md)中的发布边界，但不替换其所有权模型。
 
-## 持久化准备生命周期
+## 已被取代：持久化侧的准备生命周期
 
-使用协调器的持久化实现会将一个冷源加载为准备完成的 Session。后端转移新鲜、彼此无别名的元数据和事件，以及标识这些精确值的来源限定 revision；Session 恢复路径直接验证并冻结这些对象图，不再复制。协调器计算中断轮次的 closer，并且只构造一次精确的未发布 Session。其不可变 header 与已配平的逻辑事件日志构成读取方借用的 `SessionInspection`，revision 则保留在持久化内部。
-
-`inspect(id, signal?)` 不修改存储。合成 closer 只存在于准备完成的内存视图中，撕裂的物理尾部保持不变。同 id 调用方共享进行中的冷读。准备完成后，该对象可以进入每个协调器自己的 LRU；第一方后端可配置容量，默认保留五个。协调器复用保留源之前会读取该 id 的当前 revision；如果不匹配，就淘汰处于就绪阶段的源并重新完成冷实体化。已经进入提交或为恢复而预留的源仍由其所有者独占，因此并发检查会借用该不可变视图，直至发布或释放。
-
-`prepare(id, signal?)` 独占预留准备完成的 Session。它先确认保留的 revision，再提交撕裂尾部和中断轮次修复、建立持久游标，最后返回可 dispose 的准备对象。陈旧源会被丢弃并重新读取，不会参与修复或发布。修复成功后也会丢弃修复前的源，并在预留前重新实体化已提交日志，以免把较新的 revision 关联到较旧的事件对象图。同 id 的另一个准备请求会等待当前预留发布或释放。发布只接受精确的预留 Session，并直接附接已提交游标，无需重建历史。设置失败或取消时，未发生变化的未发布 Session 会返回 LRU；发生变更或完成附接后，系统会消费该预留。
-
-存量 `load(id)` API 使用相同的准备和修复机制，随后丢弃其预留并返回不可变逻辑视图。它保留为兼容 API，不承担历史到恢复的复用路径。该生命周期扩展了[共享持久化协调器](2026-06-18-shared-persistence-write-coordinator.zh.md)，同时继续遵循[会话持久化决策](2026-06-14-session-persistence.zh.md)所规定的存储与恢复规则。
-
-## 历史与恢复复用
-
-历史读取使用 `inspect()`，因此重复分页可以借用同一份不可变准备状态，而不会激活 agent。后续恢复调用 `prepare()`，直接取得检查阶段保留的精确 Session；系统不会再次完整读取、解压、解析、复制、验证或冻结日志。
-
-如果持久日志在检查后发生变化，其 revision 也会变化。下一次历史读取或恢复会丢弃保留且处于就绪阶段的 Session，并实体化新日志，因此旧事件对象图不会被关联到较新的快照 revision。已经由进行中恢复操作取得的源不会被淘汰：其独占所有者会持有它直至发布或释放，并发历史读取可以借用同一个不可变视图。
-
-冷 continuable subagent 访问沿用同一路径。系统先检查子会话并完成 descriptor 授权，再由 `ctx.agents.resume()` 预留并发布保留的 Session。这样既遵循 [continuable subagent 会话决策](../feature/2026-07-28-continuable-subagent-conversations.zh.md)中的生命周期与授权规则，也消除了重复冷读。
+本 Note 最初还赋予持久化一个 `prepare(id)`/`inspect(id)` 生命周期：由协调器支撑的、装有冷未发布 Session 的有界 LRU，带独占预留、按 revision 校验的复用，以及在 `prepare`/`load` 内部提交的修复，使历史分页与后续恢复共享一次冷实体化。[基于句柄的持久化 seam](2026-08-27-handle-based-session-persistence.zh.md) 删除了这一切：持久化只暴露句柄，恢复通过其写句柄读取日志并自行负责修复，只读观察方（session-query）拥有自己的冷 Session 缓存，以 `stat().revision` 变更令牌为键。读取复用的目标在该缓存中得以延续；独占预留机制则没有延续，因为写句柄的单写者所有权正是恢复真正需要的排他手段。在已准备缓存有时能提供温 Session 的场景下，恢复要为通过句柄的一次全日志读取付出代价——这是句柄 Note 中记录的、已被接受的成本。
 
 ## 边界
 
-- `readFrom()` 仍是脱离的物理后缀 API。它不会创建或消费准备对象，不会合成逻辑 closer，也不会进入 LRU。
-- HMR（热模块替换）接管继续以实时 Session 为权威，并直接读取已存储前缀。它可以截断撕裂的物理碎片，但绝不把实时开放轮次关闭为中断状态。
-- 缓存属于单个持久化协调器，而不是进程全局 Session map。实时 Session 由现有存储持有，绝不占用准备容量。
-- 新建流程绝不认领相同 id 的冷持久化准备对象。持久化冲突仍会被拒绝。
-- 第三方持久化实现继续获得通过 `load()` 实现的抽象 `prepare()` 回退。它们使用相同发布接口，但只有覆盖准备流程后才能复用精确对象。
-- Revision 校验在复用点和修复提交点建立新鲜度，但不会为后端增加跨进程 writer 排他。持久日志在一次读取与复核往返内保持不变后，重试才能收敛，因此持续的外部写入可能延迟准备。
+- 准备对象是一个可 dispose 的所有权窗口，而不是缓存：dispose 同步且幂等，发布只接受精确的已准备 Session。
+- 新建流程绝不隐式认领持久化身份。持久化冲突仍会被拒绝（`SessionAlreadyExistsError`、`SessionAlreadyOwnedError`）。
+- 实时 Session 由现有存储持有；准备对象只持有未发布的 Session。
 
 ## 验证
 
-共享持久化约定规定冷检查不得修改存储且须保持配平，并覆盖后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和清理期间从检查到恢复的路径。
+agent loop 测试覆盖 create、`createAgent` 与 resume 之间的统一发布流水线，包括设置失败时的回滚、取消与清理，以及 dispose 会释放写句柄（重新以写模式打开可以成功）。Session store 测试覆盖恢复分支的就地验证并冻结的所有权转移。
 
 ## 考虑过的替代方案
 
-**由历史读取激活 agent。** 不采用，因为分页会使仅用于查询的 agent 长期保持实时状态，并把缓存退出问题转移到 agent 生命周期。
+**由历史读取激活 agent。** 不采用，因为分页会使仅用于查询的 agent 长期保持实时状态，并把缓存退出问题转移到 agent 生命周期。该理由仍然守护着 session-query 冷缓存：观察绝不创建 agent。
 
-**只缓存 `{ meta, events }`。** 不采用，因为恢复仍需从缓存值重新构造、验证、冻结并复制 Session。真正可复用的单元是精确的未发布 Session。
+**只缓存 `{ meta, events }`。** 当时不采用，因为恢复仍需从缓存值重新构造 Session。在句柄 seam 下，这恰好是读取侧的做法——session-query 按 revision 为只读用途缓存一个冷 Session——而恢复则从句柄读取重建，以温 Session 复用换取唯一的写所有权之门。
 
-**维护进程全局 Session map。** 不采用，因为它会跨越后端和运行时所有权边界，无界保留身份，并与实时 Session 存储重复。
-
-**在 agent loop 中增加恢复事务或协调器。** 不采用，因为冷读、修复、预留和游标附接都属于持久化与 Session 职责。agent loop 只需要统一的 `SessionPreparation` 所有权边界。
-
-**把 `readFrom()` 改成逻辑准备流程。** 不采用，因为水位消费方需要脱离的物理后缀；对于可寻址后端，还需要限制实际读取范围。恢复平衡与完整 Session 复用具有不同语义。
+**在 agent loop 中增加恢复事务或协调器。** 不采用，因为冷读与 Session 构造属于持久化与 Session 职责。agent loop 只需要统一的 `SessionPreparation` 所有权边界；句柄 seam 保留了这一分工，同时把修复移入循环的恢复路径。
 
 ## 后果
 
-一次冷实体化可以同时服务历史分页、subagent descriptor 检查和后续恢复。所有权转移去除了恢复阶段的冗余复制；每个协调器的有界 LRU 限制内存占用，也避免查询创建实时 agent。新建和恢复共享同一发布协议，同时保持 agent 与 Session 职责分离。
-
-首次冷检查需要承担完整验证与 Session 构造成本，并可能保留该未发布 Session 直至淘汰。持久化层必须协调预留、append、修复和发布；调用方必须把检查结果视为借用的不可变状态。依赖默认 `prepare()` 的后端仍然正确，但无法获得复用优化。
+新建和恢复共享同一发布协议，同时保持 agent 与 Session 职责分离，且每条退出路径恰好 dispose 一个准备对象。本 Note 最初记录的持久化侧复用后果（共享冷实体化、LRU 上限、预留协调）如今归属于[句柄 Note](2026-08-27-handle-based-session-persistence.zh.md) 以及取代它们的 session-query 缓存。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
index 0ff8938b30..4a93d57022 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.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 .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
-2026-08-08-bounded-session-persistence-write-batching.md: 20c16991b0be30ffe546a94c257bc65f86cb57eb
-2026-08-08-bounded-session-persistence-write-batching.zh.md: ac0384f4e28175922f84d23296dfb13848cf5dd3
+2026-08-08-bounded-session-persistence-write-batching.md: 6fb44e494fc17bde08eb3132afe42ce73b5a4e47
+2026-08-08-bounded-session-persistence-write-batching.zh.md: 576764583dd8c465ae45866f62ef15773735961e
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
index 20c16991b0..6fb44e494f 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
@@ -20,19 +20,19 @@ The scheduling bound is deterministic. With an immediately resolving sink, the f
 
 ## Decision
 
-The JSONL provider exposes `writeBatchMaxDelayMs`, a positive integer no greater than Node's timer limit. Its default is `200`. The provider resolves the value at load and passes it to `PersistenceCoordinator`; the coordinator remains the single owner of batching behavior.
+The fixed window is the JSONL provider's constant `LIVE_WRITE_BATCH_MAX_DELAY_MS` (200 ms), an internal scheduling policy rather than configuration: the backend's own session listeners route live events by id into the active write handle's buffer, so batching never crosses the package boundary ([handle note](2026-08-27-handle-based-session-persistence.md)).
 
-Each live Session receives a package-private `SessionWriteBehind`. When its pending queue changes from empty to non-empty, the controller starts one fixed window. Later events join that batch without resetting the deadline: this is bounded coalescing, not debounce. When the deadline expires, the controller hands the complete pending prefix to the existing per-id serialization and `appendBatch` path. At most one write for a Session is active. Events admitted during that write form a new pending prefix with their own fixed deadline; if that deadline expires before the active write completes, the new prefix starts immediately after it.
+Each active write handle owns its buffer directly. A routed event lands in the handle's pending array, and the first event of an idle buffer arms one fixed timer. Later events join that batch without resetting the deadline: this is bounded coalescing, not debounce. When the deadline expires, a single-flight drain persists the pending prefix through the handle's mutation chain, which already serializes it against explicit appends. Events admitted during a drain pass coalesce into the next chained batch, in order.
 
-`writeBatchMaxDelayMs` bounds only the controller's intentional batching wait. Event-loop scheduling, initialization, an earlier serialized operation, and backend I/O can delay durable completion, so the option is not a hard fsync or crash-loss SLA.
+The window bounds only the controller's intentional batching wait. Event-loop scheduling, initialization, an earlier serialized operation, and backend I/O can delay durable completion, so the option is not a hard fsync or crash-loss SLA.
 
-`session/flush` cancels any remaining wait and becomes a shared quiescence barrier. It drains the active attempt and every event admitted while the barrier is running before it resolves. Session retirement and backend disposal use that same barrier, so lifecycle teardown never waits for the batching timer. The checkpoint policy continues to place mandatory barriers before model requests and top-level tool side effects.
+`session/flush` cancels any remaining wait and becomes a shared quiescence barrier. It drains the active attempt and every event admitted while the barrier is running before it resolves. Session retirement (`session/disposed`), the handle's close, and backend teardown's close sweep use that same barrier, so lifecycle teardown never waits for the batching timer. The checkpoint policy continues to place mandatory barriers before model requests and top-level tool side effects.
 
 Every event remains durable in its original order and shape. The controller copies each event on admission; no `assistant/chunk`, `seq`, `time`, surface metadata, or storage record is removed or rewritten. JSONL can therefore encode more events in one append frame without changing its on-disk format.
 
-A failed background append restores its complete batch before any newer pending events, reports the failure once, and pauses automatic retry. The next newly admitted event opens a fresh fixed window; an explicit flush, retirement, or disposal retries immediately and surfaces a repeated failure to its caller. This avoids a timer-driven failure loop while preserving the existing recoverable flush boundary.
+A failed background drain retains its complete batch in order ahead of newer pending events, reports the failure once, and pauses the automatic timer. The next explicit drain — a `session/flush` barrier, service-level `flush()`, or close — retries immediately and surfaces a repeated failure to its caller. This avoids a timer-driven failure loop while preserving the existing recoverable flush boundary.
 
-This decision supersedes only the immediate scheduling cadence in [Collapse live persistence into one flush controller](../simplification/2026-07-23-collapse-persistence-flush-state.md). That note remains authoritative for one controller per live Session, retained failed batches, per-id serialization, retirement, and quiescent disposal. The [shared persistence coordinator](2026-06-18-shared-persistence-write-coordinator.md) remains the owner of the backend hook boundary.
+This decision supersedes only the immediate scheduling cadence in [Collapse live persistence into one flush controller](../simplification/2026-07-23-collapse-persistence-flush-state.md). That note remains authoritative for one buffer owner per live Session, retained failed batches, retirement, and quiescent disposal. The coordinator and the separate write-behind controller that first hosted this behavior are deleted; the buffer, timer, and drain live on the provider's handle, and the [handle-based seam](2026-08-27-handle-based-session-persistence.md) owns the storage boundary they write through.
 
 ## Alternatives considered
 
@@ -42,11 +42,11 @@ This decision supersedes only the immediate scheduling cadence in [Collapse live
 
 **Debounce from the latest event.** Rejected: a continuously streaming response could postpone its first write indefinitely. A fixed window from the first pending event provides a real upper bound on intentional coalescing wait.
 
-**Implement the timer inside JSONL.** Rejected: scheduling, failure retention, flush races, and teardown are provider-neutral lifecycle concerns that belong in `PersistenceCoordinator`; an out-of-tree provider can reuse the same behavior.
+**A shared provider-neutral controller component.** Rejected after one iteration shipped it: the handle's mutation chain already serializes writes, so a separate controller duplicated that ordering machinery. Each provider implements the buffer on its own handle, and the shared live-write contract suite pins the equivalent observable behavior for any provider.
 
 ## Verification
 
-The controller tests use a fake clock to prove the fixed, non-resetting 200 ms window; immediate and shared flush barriers; events admitted during a barrier; an over-budget tail behind an active write; ordered failure retention; paused automatic retry; and explicit retry of an overlapping background failure. Coordinator tests run the controller through Session notifications, retirement, collision reclamation, and teardown. The JSONL suite retains storage-format, recovery, and shared persistence-contract coverage.
+The shared live-write contract suite (`runLiveWritePathContract`) uses a fake clock to prove the fixed, non-resetting 200 ms window; the `session/flush` barrier and its loud failure surfacing; ordered failure retention with exactly-once recovery; the service-level `flush()` sweep with per-session failure aggregation; and the disposed/close/teardown drains. The JSONL suite retains its storage-format, recovery, and shared persistence-contract coverage.
 
 ## Consequences
 
@@ -54,6 +54,6 @@ High-frequency event bursts normally produce fewer durable append operations whi
 
 This decision does not cap pending event count or bytes behind a slow provider, and it does not reduce the decoded logical log. A demonstrated memory bound or logical-retention policy would require its own failure and replay contract rather than another hidden timer rule.
 
-An admitted event can remain only in memory during the configured window, and then while scheduling or backend work is outstanding. Deployments choose a smaller value for a narrower ordinary loss window or a larger value for stronger batching. Explicit durability boundaries remain unchanged and bypass the wait.
+An admitted event can remain only in memory during the fixed window, and then while scheduling or backend work is outstanding. Explicit durability boundaries remain unchanged and bypass the wait.
 
-The deep module gives the timer, active write, pending prefix, retry pause, and barrier one owner. `PersistenceCoordinator` retains initialization and identity serialization; the provider retains only durable storage primitives. `SESSION_FORMAT_VERSION` remains unchanged.
+The handle gives the timer, active drain, pending prefix, retry pause, and barrier one owner; the backend's listeners own routing and lifecycle-driven drains. `SESSION_FORMAT_VERSION` remains unchanged.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
index ac0384f4e2..576764583d 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
@@ -20,19 +20,19 @@ JSONL 每个持久化追加批次会写入一个 Zstandard 帧并执行一次 fs
 
 ## 决策
 
-JSONL provider 公开 `writeBatchMaxDelayMs`，其值必须是一个不超过 Node 计时器上限的正整数，默认值为 `200`。provider 在加载时解析该值，再传给 `PersistenceCoordinator`；批处理行为仍只由协调器负责。
+固定窗口是 JSONL provider 的常量 `LIVE_WRITE_BATCH_MAX_DELAY_MS`（200 ms），它是内部调度策略而非配置：后端自己的会话监听器按 id 把实时事件路由进活跃写句柄的缓冲，因此批处理绝不跨越包边界（[句柄 Note](2026-08-27-handle-based-session-persistence.zh.md)）。
 
-每个活跃的会话都有一个包私有 `SessionWriteBehind`。当其待处理队列从空变为非空时，控制器会启动一个固定窗口。后续事件加入该批次但不会重置截止时间：这属于有界合并，而不是防抖。截止时间到达后，控制器会把完整的待处理前缀交给现有的按 id 串行化机制，并沿 `appendBatch` 路径写入。同一会话同时最多有一个活跃写入。该写入期间接纳的事件会形成新的待处理前缀，并拥有自己的固定截止时间；如果该截止时间在活跃写入完成前到期，新前缀会在前一次写入完成后立即开始写入。
+每个活跃写句柄直接拥有自己的缓冲。被路由的事件落入句柄的待处理数组，空闲缓冲收到的第一个事件会启动一个固定计时器。后续事件加入该批次但不会重置截止时间：这属于有界合并，而不是防抖。截止时间到达后，一次 single-flight 排空会把待处理前缀经由句柄的修改链持久化，该链本就将其与显式 append 串行化。排空进行期间接纳的事件会按顺序合并进下一个链上的批次。
 
-`writeBatchMaxDelayMs` 只限制控制器为批处理而主动等待的时间。事件循环调度、初始化、此前的串行化操作和后端 I/O 都可能延后持久化完成时间，因此该选项并不对 fsync 完成时间或崩溃数据丢失提供硬性 SLA。
+该窗口只限制控制器为批处理而主动等待的时间。事件循环调度、初始化、此前的串行化操作和后端 I/O 都可能延后持久化完成时间，因此该选项并不对 fsync 完成时间或崩溃数据丢失提供硬性 SLA。
 
-`session/flush` 会取消剩余等待，并充当共享的完全停稳屏障。它会在完成前等待活跃写入尝试，并排空屏障运行期间接纳的每个事件。会话退役与后端 dispose（资源释放）共用该屏障，因此生命周期 teardown 绝不会等待批处理计时器。检查点策略仍会在模型请求与顶层工具副作用之前设置强制屏障。
+`session/flush` 会取消剩余等待，并充当共享的完全停稳屏障。它会在完成前等待活跃写入尝试，并排空屏障运行期间接纳的每个事件。会话退役（`session/disposed`）、句柄的 close 与后端 teardown 的关闭清扫共用该屏障，因此生命周期 teardown 绝不会等待批处理计时器。检查点策略仍会在模型请求与顶层工具副作用之前设置强制屏障。
 
 每个事件仍会按原有顺序和形态持久化。控制器会在接纳时复制每个事件；任何 `assistant/chunk`、`seq`、`time`、surface 元数据或存储记录都不会被删除或重写。因此，JSONL 可以在一个追加帧中编码更多事件，而无需改变其磁盘格式。
 
-后台追加失败后，控制器会把完整批次恢复到所有较新的待处理事件之前，报告一次该失败，并暂停自动重试。随后新接纳的第一个事件会开启新的固定窗口；显式 flush、退役或 dispose 会立即重试，如果故障再次发生，则会向调用方暴露该故障。这可以避免计时器驱动的失败循环，同时保留现有可恢复的 flush 边界。
+后台排空失败后，其完整批次会按顺序保留在所有较新的待处理事件之前，该失败被报告一次，自动计时器随之暂停。下一次显式排空——`session/flush` 屏障、服务级 `flush()` 或 close——会立即重试，如果故障再次发生，则会向调用方暴露该故障。这可以避免计时器驱动的失败循环，同时保留现有可恢复的 flush 边界。
 
-本决策仅取代[将实时持久化归并到单个刷新控制器](../simplification/2026-07-23-collapse-persistence-flush-state.zh.md)中的即时调度节奏。对于每个活跃会话使用一个控制器、保留失败批次、按 id 串行化、退役和完全停稳的 dispose，原 Agent Note 仍是权威记录。后端钩子边界仍由[共享持久化协调器](2026-06-18-shared-persistence-write-coordinator.zh.md)定义。
+本决策仅取代[将实时持久化归并到单个刷新控制器](../simplification/2026-07-23-collapse-persistence-flush-state.zh.md)中的即时调度节奏。对于每个活跃会话使用一个缓冲所有者、保留失败批次、退役和完全停稳的 dispose，原 Agent Note 仍是权威记录。最初承载该行为的协调器与独立的 write-behind 控制器均已删除；缓冲、计时器和排空落在 provider 的句柄上，它们写入所经过的存储边界由[基于句柄的 seam](2026-08-27-handle-based-session-persistence.zh.md) 定义。
 
 ## 备选方案
 
@@ -42,11 +42,11 @@ JSONL provider 公开 `writeBatchMaxDelayMs`，其值必须是一个不超过 No
 
 **按最新事件重置防抖窗口。** 不采纳：持续不断的流式响应可能无限期推迟首次写入。由第一个待处理事件启动的固定窗口，为主动合并等待提供了真正的上界。
 
-**在 JSONL 内实现计时器。** 不采纳：调度、失败保留、flush 竞态和 teardown 都是 provider 无关的生命周期问题，属于 `PersistenceCoordinator`；仓库外 provider 可以复用同一行为。
+**共享的 provider 无关控制器组件。** 曾在一次迭代中交付，随后不采纳：句柄的修改链本就串行化写入，独立控制器重复了这套排序机制。每个 provider 在自己的句柄上实现该缓冲，共享的实时写入约定测试套件为任何 provider 钉住等价的可观察行为。
 
 ## 验证
 
-控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及对重叠发生的后台失败进行显式重试。协调器测试会在会话通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 测试套件继续覆盖存储格式、恢复和共享持久化约定。
+共享的实时写入约定测试套件（`runLiveWritePathContract`）使用假时钟证明固定且不会重置的 200 ms 窗口、`session/flush` 屏障及其失败的响亮暴露、有序保留失败批次并恰好恢复一次、带逐会话失败聚合的服务级 `flush()` 清扫，以及 disposed/close/teardown 的排空。JSONL 测试套件继续覆盖存储格式、恢复和共享持久化约定。
 
 ## 后果
 
@@ -54,6 +54,6 @@ JSONL provider 公开 `writeBatchMaxDelayMs`，其值必须是一个不超过 No
 
 本决策不会限制因 provider 缓慢而积压的待处理事件数量或字节数，也不会减少解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放约定，而不是再引入一条隐式计时器规则。
 
-接纳后的事件在配置窗口内可能只存在于内存中，此后在等待调度或后端工作完成期间也可能如此。部署可以选择较小的值以缩短普通丢失窗口，也可以选择较大的值以加强批处理。显式持久性边界保持不变，并会绕过等待。
+接纳后的事件在固定窗口内可能只存在于内存中，此后在等待调度或后端工作完成期间也可能如此。显式持久性边界保持不变，并会绕过等待。
 
-deep 模块统一负责计时器、活跃写入、待处理前缀、重试暂停和屏障。`PersistenceCoordinator` 继续负责初始化和按标识串行化；provider 仍只负责持久存储原语。`SESSION_FORMAT_VERSION` 保持不变。
+句柄统一负责计时器、活跃排空、待处理前缀、重试暂停和屏障；后端的监听器负责路由和生命周期驱动的排空。`SESSION_FORMAT_VERSION` 保持不变。
diff --git a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.i18n.yaml
index 884aa27385..44c31bc1cd 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.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 .agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md
-2026-08-10-message-feedback-sidecar.md: eb1f8786f9ec0363b3c98d5b80a796b9c0fc0b4c
-2026-08-10-message-feedback-sidecar.zh.md: 573d3b30e3bd14b492925f4a00424db588736943
+2026-08-10-message-feedback-sidecar.md: d047bebf47f844a6d88932c7e19a3952f43d94cc
+2026-08-10-message-feedback-sidecar.zh.md: 4ee1b861a8013dacfd5eba40d9e30b23237be2e5
diff --git a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md
index eb1f8786f9..d047bebf47 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md
@@ -16,9 +16,9 @@ A sidecar keyed only by `SessionId` can outlive the log lifecycle it describes w
 
 Every usable row is bound to the inspected Session header identity `{createdAt, cwd}`, not merely its `SessionId`. A lifecycle mismatch is treated as absence: `list` returns no items, and `put` may replace the stale row with one bound to the current identity. An id reused with a different header identity therefore cannot inherit stale feedback. A fork receives its own Session identity and no sidecar copy: even when the fork seed contains the same assistant messages, feedback remains attached to the Session in which the human recorded it.
 
-`put` accepts a target only when `SessionPersistence.inspect()` observes a non-empty, append-origin `assistant/message` with that `MessageId`. Replacement-origin messages, empty usage-only assistant records, and non-assistant targets are rejected. Inspection is the cold-safe authority: it neither publishes or resumes an Agent nor commits cold-log repair merely to validate feedback. A cold `listSnapshots()` preflight classifies definite absence; inspection failure for a catalogued Session remains an infrastructure failure. A request in the narrow live-detach-to-header-materialization interval can therefore return `session-not-found`, and the caller retries after retirement materialization.
+`put` accepts a target only when the observed log — a live owner's in-memory events, else the durable log through a persistence read handle — contains a non-empty, append-origin `assistant/message` with that `MessageId`. Replacement-origin messages, empty usage-only assistant records, and non-assistant targets are rejected. Observation is cold-safe: it neither publishes or resumes an Agent nor commits cold-log repair merely to validate feedback. A cold `stat()` preflight classifies definite absence; a read failure for a catalogued Session remains an infrastructure failure. A request in the narrow live-detach-to-header-materialization interval can therefore return `session-not-found`, and the caller retries after retirement materialization.
 
-Before `put` commits a sidecar row, it puts the target log behind a durability barrier. A matching live Session passes through the canonical `ctx.sessions.flush` checkpoint, then both live and cold paths are physically read from sequence zero through `SessionPersistence.readFrom`. The resulting observation's header identity and target are checked again. A missing flush participant, changed identity, vanished target, or physical-read failure prevents the sidecar write, so a committed feedback item never precedes the durable assistant message it references.
+Before `put` commits a sidecar row, it puts the target log behind a durability barrier. A matching live Session passes through the canonical `ctx.sessions.flush` checkpoint, then both live and cold paths are physically re-read from sequence zero through a fresh persistence read handle. The resulting observation's header identity and target are checked again. A missing flush participant, changed identity, vanished target, or physical-read failure prevents the sidecar write, so a committed feedback item never precedes the durable assistant message it references.
 
 Each message item carries its own opaque version plus Host-assigned `createdAt` and `updatedAt` timestamps. `put` compares the caller's `ifVersion` only with the addressed item, so editing one message does not invalidate another. The comparison is strict even when the desired value already matches, preventing a stale request from crossing an ABA value cycle; a conflict returns the authoritative current item so callers can reconcile without a second read. A matching-version no-op preserves the version and timestamps, while a material update preserves `createdAt`, replaces the version, and keeps `updatedAt` from moving backward. An already-absent delete is likewise successful. Versions are tokens for equality, not counters callers may order or synthesize.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md
index 573d3b30e3..4ee1b861a8 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md
@@ -16,9 +16,9 @@ Status: implemented
 
 每条可用记录都绑定到经检查的 Session header 身份 `{createdAt, cwd}`，而不只是其 `SessionId`。生命周期不匹配按不存在处理：`list` 返回空条目，`put` 可以用绑定当前身份的新记录替换陈旧行。因此，以不同 header 身份复用的 id 不会继承陈旧反馈。fork 拥有自己的 Session 身份，且不复制伴随记录：即使 fork 种子包含相同的 assistant 消息，反馈仍只属于人类记录它的那个 Session。
 
-`put` 只接受由 `SessionPersistence.inspect()` 观测到的非空、append-origin `assistant/message`，且其 `MessageId` 必须与目标相同。replacement-origin 消息、仅承载 usage 的空 assistant 记录以及非 assistant 目标都会被拒绝。检查使用 cold-safe 权威路径：它不会仅为验证反馈而发布或恢复 Agent，也不会提交 cold 日志修复。cold 路径由 `listSnapshots()` 预检明确不存在；已进入目录的 Session 若检查失败，仍按基础设施故障处理。因此，请求若恰落在 live detach 到 header materialization 的极短窗口，可能返回 `session-not-found`，调用方在 retirement materialization 后重试。
+`put` 只在被观测的日志——live 持有者的内存事件，否则是经由持久化读句柄读取的持久日志——包含非空、append-origin 且 `MessageId` 与目标相同的 `assistant/message` 时才接受该目标。replacement-origin 消息、仅承载 usage 的空 assistant 记录以及非 assistant 目标都会被拒绝。观测是 cold-safe 的：它不会仅为验证反馈而发布或恢复 Agent，也不会提交 cold 日志修复。cold 路径由 `stat()` 预检明确不存在；已进入目录的 Session 若读取失败，仍按基础设施故障处理。因此，请求若恰落在 live detach 到 header materialization 的极短窗口，可能返回 `session-not-found`，调用方在 retirement materialization 后重试。
 
-`put` 提交伴随记录前，会先让目标日志通过 durability barrier。身份匹配的 live Session 经过权威 `ctx.sessions.flush` checkpoint，随后 live 与 cold 路径都会通过 `SessionPersistence.readFrom` 从序列零做物理复读。之后再次校验所得观测的 header 身份与目标。缺少 flush 参与方、身份变化、目标消失或物理读取失败都会阻止伴随记录写入，因此已提交反馈绝不会先于它引用的持久 assistant 消息。
+`put` 提交伴随记录前，会先让目标日志通过 durability barrier。身份匹配的 live Session 经过权威 `ctx.sessions.flush` checkpoint，随后 live 与 cold 路径都会通过新开的持久化读句柄从序列零做物理复读。之后再次校验所得观测的 header 身份与目标。缺少 flush 参与方、身份变化、目标消失或物理读取失败都会阻止伴随记录写入，因此已提交反馈绝不会先于它引用的持久 assistant 消息。
 
 每个消息条目都携带自己的 opaque version，以及 Host 分配的 `createdAt` 和 `updatedAt` 时间戳。`put` 只把调用方的 `ifVersion` 与目标条目比较，因此编辑一条消息不会使另一条消息失效。即使目标值已经相同，比较仍然严格执行，从而防止陈旧请求穿过 ABA 值循环；冲突会返回权威当前条目，调用方无需二次读取即可协调。携带匹配 version 的无变化请求会保留 version 与时间戳；实质更新保留 `createdAt`、替换 version，并保证 `updatedAt` 不倒退。删除已经不存在的条目也同样成功。version 是只能做相等比较的 token，不是调用方可以排序或自行合成的计数器。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml
index f717ba76e2..620239bf08 100644
--- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.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 .agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md
-2026-08-18-session-history-and-event-transport.md: d35ed79dedd5592d15a27b0e1b952e66d80b268f
-2026-08-18-session-history-and-event-transport.zh.md: 6e6ccf53e28c9a7ce76bb4aa5d80d94f39e11f10
+2026-08-18-session-history-and-event-transport.md: 10fdd9b256c27aadada97195c8dc5516b4485a43
+2026-08-18-session-history-and-event-transport.zh.md: bf110b5f1a2bea99f9aa086c66a616eddaa0a50e
diff --git a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md
index d35ed79ded..10fdd9b256 100644
--- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md
+++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md
@@ -163,7 +163,7 @@ Each method explicitly selects a cold inspection, live-only lookup, or resume-ca
 
 Reading titles, lists, and projections does not require an Agent. An observation operation cannot inherit resume authority merely because another Remote endpoint uses Agent lookup.
 
-`SessionQuery.observeSession()` chooses an attached Session or borrows one prepared source from `SessionPersistence.borrowSession()`. The persistence preparation cache shares concurrent cold reads and pins the exact unpublished Session until every observation lease is released. An observation computes either all registered projections or none; callers may expose a subset, but no caller creates a partial projection state.
+`SessionQuery.observeSession()` chooses an attached Session or serves a cold one from the reader's own prepared cache, filled through a persistence read handle. The cache shares concurrent cold reads and pins an entry until every observation lease is released. An observation computes either all registered projections or none; callers may expose a subset, but no caller creates a partial projection state.
 
 `session.list` never performs an unbounded cold-log scan. It uses cached projection hints when available and may fully observe only an individually stored artifact within the configured small-log byte limit to distinguish an abandoned blank Session. Missing or unreadable hints keep the row visible with unknown metadata.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md
index 6e6ccf53e2..bf110b5f1a 100644
--- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md
@@ -163,7 +163,7 @@ Session Remote 方法传递 `SessionId` 或 `SessionAddress`，不靠参数类
 
 读取 title、列表和投影不要求 Agent。观察操作不能因为另一个 Remote endpoint 使用了 Agent lookup 而继承其恢复权限。
 
-`SessionQuery.observeSession()` 选择 attached Session，或从 `SessionPersistence.borrowSession()` 借用 prepared source。Persistence preparation cache 共享并发冷读取，并在所有 observation lease 释放前固定同一个未发布 Session。一次 observation 要么计算所有已注册 projection，要么完全不计算；调用方可以只公开其中一部分，但不会建立只计算部分 projection 的中间状态。
+`SessionQuery.observeSession()` 选择 attached Session，或从读取方自己的 prepared cache——经由持久化读句柄填充——提供冷 Session。该 cache 共享并发冷读取，并在所有 observation lease 释放前固定同一条目。一次 observation 要么计算所有已注册 projection，要么完全不计算；调用方可以只公开其中一部分，但不会建立只计算部分 projection 的中间状态。
 
 `session.list` 不会无界扫描冷日志。它优先使用缓存的 projection hint，仅在独立存储 artifact 不超过配置的小日志字节上限时，才可能完整观察日志以判断不确定的 blank 状态。hint 缺失或不可读时，列表仍保留该行，并把 metadata 视为未知。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml
index d8e1977615..df7268de5c 100644
--- a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.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 .agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md
-2026-08-25-session-observations-and-projection-owned-client-state.md: 492640385215b059761b17a057328cc5c6d24bff
-2026-08-25-session-observations-and-projection-owned-client-state.zh.md: 0b892a9cae2c999b4472dd46f19068e2b4139e60
+2026-08-25-session-observations-and-projection-owned-client-state.md: 554d003da1e1767b8955be7a067cbea716f130ef
+2026-08-25-session-observations-and-projection-owned-client-state.zh.md: a63b0414f8b0250e4cea95ac39a39aa2c62cd958
diff --git a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md
index 4926403852..554d003da1 100644
--- a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md
+++ b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md
@@ -32,8 +32,8 @@ flowchart LR
   Cache -->|"small miss"| Observe
   Observe --> Source{"live or cold"}
   Source --> Live["attached Session cut"]
-  Source --> Borrow["borrowSession"]
-  Borrow --> Prepared["SessionPreparations.borrow"]
+  Source --> Borrow["persistence read handle"]
+  Borrow --> Prepared["reader's prepared cache"]
   Live --> Mode{"all or none"}
   Prepared --> Mode
   Mode --> Snapshot["SessionObservation"]
@@ -45,7 +45,7 @@ flowchart LR
 
 ### Observation is the point-read unit
 
-`SessionQueryEngine.observeSession(sessionId, options)` returns a disposable `SessionObservation` containing one source kind, header, contiguous event prefix, cursor, optional projection snapshot, and the durable revision for a prepared source. An attached Session wins. Otherwise `SessionPersistence.borrowSession()` and `SessionPreparations.borrow()` share and pin one prepared Session, including an in-flight cold load.
+`SessionQueryEngine.observeSession(sessionId, options)` returns a disposable `SessionObservation` containing one source kind, header, contiguous event prefix, cursor, optional projection snapshot, and the durable revision for a prepared source. An attached Session wins. Otherwise the reader's own prepared cache — keyed by `stat().revision` and pinned by observation leases — serves the cold Session, sharing one persistence read (`open(id, 'read')` + `read`) across concurrent observations, including an in-flight cold load.
 
 Every owner disposes its observation. `retain()` creates another lease over the same cut, which lets `session.follow` publish a snapshot and then transfer that exact prepared source to background Agent promotion without rereading the log. A live Session that appears during cold resolution wins before publication; a disappeared live source is retried as cold.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md
index 0b892a9cae..a63b0414f8 100644
--- a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md
@@ -32,8 +32,8 @@ flowchart LR
   Cache -->|"small miss"| Observe
   Observe --> Source{"live or cold"}
   Source --> Live["attached Session cut"]
-  Source --> Borrow["borrowSession"]
-  Borrow --> Prepared["SessionPreparations.borrow"]
+  Source --> Borrow["persistence read handle"]
+  Borrow --> Prepared["reader's prepared cache"]
   Live --> Mode{"all or none"}
   Prepared --> Mode
   Mode --> Snapshot["SessionObservation"]
@@ -45,7 +45,7 @@ flowchart LR
 
 ### Observation 是 point read 单元
 
-`SessionQueryEngine.observeSession(sessionId, options)` 返回可 dispose（资源释放）的 `SessionObservation`，其中包含同一份 source kind、header、连续事件前缀、cursor、可选 projection snapshot，以及 prepared source 的持久化 revision。已挂载 Session 优先；否则 `SessionPersistence.borrowSession()` 与 `SessionPreparations.borrow()` 共享并固定一份 prepared Session，包括尚未完成的冷加载。
+`SessionQueryEngine.observeSession(sessionId, options)` 返回可 dispose（资源释放）的 `SessionObservation`，其中包含同一份 source kind、header、连续事件前缀、cursor、可选 projection snapshot，以及 prepared source 的持久化 revision。已挂载 Session 优先；否则由读取方自己的 prepared cache——以 `stat().revision` 为键、由 observation lease 固定——提供冷 Session，让并发 observation 共享同一次持久化读取（`open(id, 'read')` + `read`），包括尚未完成的冷加载。
 
 每个 owner 都会 dispose 自己的 observation。`retain()` 为同一切面创建另一份 lease，使 `session.follow` 能够先发布 snapshot，再把完全相同的 prepared source 转交给后台 Agent promotion，而无需重读日志。冷解析期间出现的 live Session 会在发布前胜出；已经消失的 live source 会按 cold source 重试。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.i18n.yaml
similarity index 55%
rename from .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
rename to .agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.i18n.yaml
index 0a513e049f..2c0b6abd41 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
-2026-08-04-load-pre-react-loop-sessions.md: e95817ee60647ca002060a4f90c2263d4fe7ce42
-2026-08-04-load-pre-react-loop-sessions.zh.md: 98fb1f530f5168fc02b312775d1bb8e6d305b8f8
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md
+2026-08-27-handle-based-session-persistence.md: ced7a78178d3036fd5fa9a09ca49f8c751c3a169
+2026-08-27-handle-based-session-persistence.zh.md: e13b5b0e9e7286411b6d38f3b9dc0e86fa742a3d
diff --git a/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md b/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md
new file mode 100644
index 0000000000..ced7a78178
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md
@@ -0,0 +1,42 @@
+# Agent Note: Handle-based session persistence
+
+Status: implemented
+
+English | [中文](2026-08-27-handle-based-session-persistence.zh.md)
+
+## Problem
+
+The previous persistence seam owned far more than storage. A shared coordinator subscribed to `session/created`/`session/event`/`session/flush`/`session/disposed` and adopted any published session (ownerless claims, HMR re-seeding, stored-prefix adoption); a bounded prepared-Session LRU with exclusive reservations served resume and read-only observation from one cache; committing crash repair lived inside `load`/`prepare`; and optimistic revision read/check/read loops stood in for ownership, so a continuous external writer could livelock a read and nothing excluded a second writer. The service surface (twelve methods) mixed storage with Session construction and lifecycle. Cross-process write ownership — the next step — has no honest home in that shape: ownership belongs to an explicit per-session channel with an owner, not to a global listener.
+
+## Decision
+
+**The seam is five service methods returning or serving per-session handles.** `create(header)` stores a new session and returns its owned write handle; `open(id, 'read' | 'write')` opens an existing one; `stat(id)`/`list()` observe snapshots (`header`, opaque `revision`, optional `eventCount`/`sizeBytes` hints — the JSONL backend supplies `sizeBytes`) without reading logs; service-level `flush()` is one backend-wide durability barrier that drains and flushes every active write handle, aggregating per-session failures without abandoning the sweep. The seam carries no raw-artifact export: the WebUI ZIP download serializes the logical log (header line + events) from a read handle in `dsh-session-log-export`, so every backend exports identically and the JSONL-only 501 path is gone. A `SessionHandle` carries `read(offset?, length?)` (validated contiguous prefix slices, never a torn tail, monotonic per handle), `append` (contiguous; persistence is best-effort on resolution, and the shipped JSONL backend happens to persist each batch immediately), `flush` (the durability barrier, which also materializes an empty session), and idempotent uncancellable `close`. One handle type serves both accesses — a mutation on a read handle is a runtime `SessionReadOnlyError`, the deliberate convention of this codebase's other seams rather than a typed split. Single-writer ownership is enforced in-process by a registry (`SessionAlreadyOwnedError`); the durable cross-process lease is the planned next layer on the same shape.
+
+**The agent lifecycle owns handle acquisition; the backend owns the event-driven flow.** agent-loop — the sole production publication point for sessions — acquires the handle before publication (`create` for fresh sessions, appending any constructor seed through it; `open(id, 'write')` for resume) and closes it in the same memoized teardown that drains the loop. Because persistence already enforces one active write handle per session id, the backend installs the session listeners once and routes by id: `session/event` into the owning handle's bounded write-behind window (an internal scheduling policy, not configuration), `session/flush` as the durability and error-observation barrier, `session/disposed` as final drain and close. Nothing about the write path crosses the package boundary — no writer component, no batching configuration, no drain registry. Root-fiber disposal runs every fiber's disposers concurrently, so `close()` itself drains the routed buffer through the still-open storage; backend teardown's close sweep keeps application shutdown lossless regardless of which fiber unwinds first. The drain guarantees only buffered already-emitted events; a root dispose mid-turn still loses the turn's unemitted remainder by design — the next resume's `interruptedTurnClosers` repairs that tail durably. Sessions published outside the lifecycle no longer persist implicitly; nothing in production does that.
+
+**Semantic crash repair moved out of persistence.** Resume reads the physically valid log through its write handle, computes `interruptedTurnClosers`, and appends them (plus the constructor's `session/end-seed` marker) through the same handle as ordinary batches — repair is not a special storage entry point. Read-only observers (session-query) balance an interrupted cold log in memory only, and own their cold-Session cache keyed by `stat().revision`; the persistence-side prepared cache and revision convergence loops are deleted.
+
+**Visibility and freshness are explicit.** A created session is observable in-process from `create`; physical materialization may be deferred (a pure optimization) until the first append or flush, other processes see only materialized sessions, and a crash before materialization means the session never existed. Once an append or flush resolves, reads started afterwards on the same backend instance observe at least that prefix — the guarantee `message-feedback`'s durable-target check rides on.
+
+**Revision simplifies to a per-instance change token.** Equal tokens may be treated as an unchanged log; ownership churn never changes one. JSONL derives a best-effort token and `sizeBytes` from one `fs.stat`; a backend whose medium can count events cheaply may supply the `eventCount` hint instead. The session-list cold blank probe returns on this metadata (`coldBlankProbeMaxEvents`/`coldBlankProbeMaxBytes`), restoring the capability removed with the path query.
+
+## Alternatives considered
+
+**Typed read/write handle classes (or overloads).** Rejected as the seam style: this codebase's seams prefer one access-tagged type with runtime refusal, and the split would double every consumer-facing type for one compile-time check.
+
+**Keeping the coordinator's adoption/HMR write path beside handles.** Rejected: adoption exists to guess ownership after the fact; with the lifecycle handing the handle over explicitly, a reloaded backend that cannot serve old handles fails the writer loudly instead of silently re-claiming logs, and a session with no handle is a composition bug surfaced by absent persistence rather than masked by adoption.
+
+**A service-level `append(id, events)` beside handles.** Rejected: an id-addressed write path bypasses ownership; every write flows through the owning handle so the future lease check has exactly one door.
+
+**Persistence-owned batching configuration.** Rejected: the batching window is internal write-path scheduling, not a deployment-varying choice, so it is a provider constant and no configuration knob exists anywhere.
+
+## Consequences
+
+Resume, fork, subagent, ACP, webhook, and SDK sessions all persist through one explicit acquisition point, and dispose provably releases write ownership (reopening for write succeeds after teardown). The costs: a backend plugin reload under live sessions invalidates their handles — writes fail loudly until the sessions restart, where adoption previously re-attached silently; `ctx.sessions.create` + `flush` in a test persists nothing without a handle (tests seed through `create`/`append`/`close`); resume re-reads a cold log only when no immediately preceding observation parsed the same artifact — a bounded provider-local memo (session id + stat revision, invalidated by every local mutation) serves the observe-then-promote and authorize-then-resume handoffs without restoring the deleted borrow/reservation lifecycle, and the session-query reader's own prepared cache remains the pin-capable layer above it (a later consolidation may fold one into the other); and an empty created session is invisible to other processes until an explicit flush (ACP forces one for its resumable-empty-session promise). `SESSION_FORMAT_VERSION` stays 0.
+
+## Related
+
+- [Session persistence as an abstract service](2026-06-14-session-persistence.md) — the seam this reshapes; its interface list reflects the handle API.
+- [Persistence export() and pre-release trims](../simplification/2026-08-27-persistence-export-and-pre-release-trims.md) — the preparatory removals, including the blank probe this note's metadata restores.
+- [Retain ignorable external session events](2026-08-30-retain-ignorable-external-session-events.md) — the read-side refusal contract, now shared through `storage-contract` helpers.
+- [Bounded session-persistence write batching](2026-08-08-bounded-session-persistence-write-batching.md) — the batching semantics the routed write path preserves as internal scheduling policy.
diff --git a/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md
new file mode 100644
index 0000000000..e13b5b0e9e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: 基于句柄的会话持久化
+
+Status: implemented
+
+[English](2026-08-27-handle-based-session-persistence.md) | 中文
+
+## 问题
+
+先前的持久化 seam 承担的远不止存储。一个共享协调器订阅 `session/created`/`session/event`/`session/flush`/`session/disposed`，并接管任何已发布的会话（无主认领、HMR 重新播种、已存储前缀接管）；一个带独占预留的有界已准备 Session LRU 用同一个缓存服务恢复与只读观察；提交式崩溃修复内嵌在 `load`/`prepare` 中；乐观的 revision 读取/复核/再读取循环充当所有权的替身，因此持续的外部写入方可能使读取活锁，而且没有任何机制排除第二个写入方。服务表面（十二个方法）把存储与 Session 构造和生命周期混在一起。跨进程写所有权——下一步——在那种形态里没有诚实的归宿：所有权属于一条有明确持有者的逐会话通道，而不属于一个全局监听器。
+
+## 决策
+
+**该 seam 是五个返回或供给逐会话句柄的服务方法。**`create(header)` 存储一个新会话并返回其持有的写句柄；`open(id, 'read' | 'write')` 打开一个已有会话；`stat(id)`/`list()` 观察快照（`header`、不透明 `revision`、可选的 `eventCount`/`sizeBytes` 提示——JSONL 后端提供 `sizeBytes`），而不读取日志；服务级 `flush()` 是一道后端范围的持久性屏障，排空并 flush 每一个活跃写句柄，逐会话聚合失败而不中途放弃清扫。该 seam 不承载原始工件导出：WebUI 的 ZIP 下载在 dsh-session-log-export 中从读句柄序列化逻辑日志（header 行 + 事件），因此每个后端的导出完全一致，仅 JSONL 可用的 501 路径也随之消失。`SessionHandle` 承载 `read(offset?, length?)`（经过验证的连续前缀切片，绝不返回撕裂尾部，逐句柄单调）、`append`（连续；完成时的持久化是尽力而为的，交付的 JSONL 后端恰好会立即持久化每个批次）、`flush`（持久性屏障，同时把空会话实体化）以及幂等且不可取消的 `close`。一种句柄类型同时服务两种访问——在读句柄上执行修改是运行时的 `SessionReadOnlyError`，这是本代码库其他 seam 的既定惯例，而非类型层面的拆分。单写者所有权由注册表在进程内强制（`SessionAlreadyOwnedError`）；持久的跨进程租约是计划在同一形态上叠加的下一层。
+
+**agent 生命周期负责获取句柄；后端负责事件驱动的流程。**agent-loop——会话在生产环境中唯一的发布点——在发布之前获取句柄（新建会话用 `create`，并通过它追加构造 seed；恢复用 `open(id, 'write')`），并在与排空循环相同的记忆化 teardown 中关闭它。由于持久化已保证每个会话 id 只有一个活跃写句柄，后端一次性安装会话监听器并按 id 路由：`session/event` 进入持有句柄的有界 write-behind 窗口（内部调度策略，而非配置），`session/flush` 作为持久性与错误观察屏障，`session/disposed` 作为最终排空并关闭。写路径没有任何部分跨越包边界——没有写入器组件，没有批处理配置，没有排空注册表。根 fiber 的 dispose 会并发运行每个 fiber 的 disposer，因此 `close()` 本身会经由仍然打开的存储排空已路由的缓冲；后端 teardown 的关闭清扫使应用关闭无论哪个 fiber 先解退都不丢数据。该排空只保证已发出并缓冲的事件；turn 中途的根 dispose 仍会按设计丢失该 turn 尚未发出的剩余部分——下一次恢复的 `interruptedTurnClosers` 会持久地修复这段尾部。在生命周期之外发布的会话不再隐式持久化；生产环境中没有任何地方那样做。
+
+**语义崩溃修复移出了持久化。**恢复通过其写句柄读取物理上有效的日志，计算 `interruptedTurnClosers`，并把它们（连同构造器的 `session/end-seed` 标记）作为普通批次通过同一句柄追加——修复不是特殊的存储入口。只读观察方（session-query）仅在内存中配平被中断的冷日志，并拥有以 `stat().revision` 为键的冷 Session 缓存；持久化侧的已准备缓存与 revision 收敛循环被删除。
+
+**可见性与新鲜度是显式的。**已创建的会话自 `create` 起即可在进程内被观察到；物理实体化（纯粹的优化）可以推迟到第一次 append 或 flush，其他进程只能看到已实体化的会话，实体化之前崩溃意味着该会话从未存在。一旦某次 append 或 flush 完成，其后在同一后端实例上开始的读取至少能观察到该前缀——这正是 `message-feedback` 持久目标检查所依赖的保证。
+
+**revision 简化为逐实例变更令牌。**令牌相等可视为日志未变；所有权变动绝不会改变令牌。JSONL 通过一次 `fs.stat` 派生尽力而为的令牌与 `sizeBytes`；存储介质能够廉价统计事件数的后端可以改为提供 `eventCount` 提示。会话列表的冷空白探测回归到这些元数据之上（`coldBlankProbeMaxEvents`/`coldBlankProbeMaxBytes`），恢复了随路径查询一起移除的能力。
+
+## 考虑过的替代方案
+
+**类型化的读/写句柄类（或重载）。**不作为该 seam 的风格采纳：本代码库的 seam 偏好带访问标记的单一类型加运行时拒绝，而拆分会为一个编译期检查让每个面向消费方的类型翻倍。
+
+**在句柄旁保留协调器的接管/HMR 写路径。**不采纳：接管的存在是为了事后猜测所有权；当生命周期显式移交句柄后，无法服务旧句柄的重载后端会向写入器响亮地失败，而不是静默地重新认领日志，而没有句柄的会话是一个由持久化缺席暴露、而非被接管掩盖的组合缺陷。
+
+**在句柄旁提供服务级 `append(id, events)`。**不采纳：按 id 寻址的写路径绕过所有权；每次写入都流经持有句柄，使未来的租约检查恰好只有一扇门。
+
+**由持久化持有批处理配置。**不采纳：批处理窗口是写路径内部的调度策略，而非随部署变化的选择，因此它是 provider 常量，任何地方都不存在配置旋钮。
+
+## 后果
+
+恢复、fork、subagent、ACP、webhook 与 SDK 会话全部经由一个显式获取点持久化，且 dispose 可证明地释放写所有权（teardown 之后重新以写模式打开可以成功）。代价：在有活跃会话时重载后端插件会使它们的句柄失效——写入会响亮地失败，直到会话重启，而以前接管会静默重连；测试中 `ctx.sessions.create` + `flush` 在没有句柄时什么也不持久化（测试通过 `create`/`append`/`close` 播种）；只有当紧邻其前没有观察读解析过同一产物时，恢复才重新读取冷日志——一个有界的 provider 内部 memo（按会话 id + stat 修订号，任何本地修改都使其失效）服务观察后提升与授权后恢复这两类交接，而不恢复已删除的 borrow/reservation 生命周期；session-query reader 自己的已准备缓存仍是其上方具备 pin 能力的一层（后续可考虑二者收敛）；空的已创建会话在显式 flush 之前对其他进程不可见（ACP 为其可恢复空会话承诺强制执行一次 flush）。`SESSION_FORMAT_VERSION` 保持为 0。
+
+## 相关
+
+- [作为抽象服务的会话持久化](2026-06-14-session-persistence.zh.md)——本 Note 重塑的 seam；其接口列表已反映句柄 API。
+- [持久化 export() 与预发布读取路径精简](../simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md)——预备性的移除，包括本 Note 的元数据所恢复的空白探测。
+- [保留可忽略的外部会话事件](2026-08-30-retain-ignorable-external-session-events.zh.md)——读取侧的拒绝约定，现经由 `storage-contract` 辅助函数共享。
+- [为会话持久化写入批处理设定上界](2026-08-08-bounded-session-persistence-write-batching.zh.md)——被路由写路径作为内部调度策略保留的批处理语义。
diff --git a/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.i18n.yaml
index 8c92e95dac..a1a3a0b8ec 100644
--- a/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.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 .agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md
-2026-08-30-retain-ignorable-external-session-events.md: c796a8dab1a9d127473a341fc98bc9934429fbdf
-2026-08-30-retain-ignorable-external-session-events.zh.md: 0c635b1082a31a0a35d01669ff9f933a1f218bee
+2026-08-30-retain-ignorable-external-session-events.md: e79713cf16c627706939f33f6748eaa4821de870
+2026-08-30-retain-ignorable-external-session-events.zh.md: 8fddbfdd7e60716b0a78ef6b33de09935e9bd4d7
diff --git a/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md b/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md
index c796a8dab1..e79713cf16 100644
--- a/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md
+++ b/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md
@@ -12,7 +12,7 @@ That producer inventory did not cover a third-party plugin that currently depend
 
 ## Decision
 
-The canonical `SessionEvent` envelope retains `ignorable?: true`, and every representation preserves it: seed validation, JSONL, API transport, generated catalogs, and test fixtures. `PersistenceCoordinator` continues to refuse an unknown event unless its stored envelope explicitly carries `ignorable: true`; absent remains required-on-read.
+The canonical `SessionEvent` envelope retains `ignorable?: true`, and every representation preserves it: seed validation, JSONL, API transport, generated catalogs, and test fixtures. The persistence seam's stored-event validation (`validateStoredEvents`) continues to refuse an unknown event unless its stored envelope explicitly carries `ignorable: true`; absent remains required-on-read.
 
 The field is removable only after a replacement supports the current third-party plugin across event production, persistence, reload, and transport, with an explicit cutover for sessions already containing the marker. The [session log versioning decision](2026-08-10-session-log-version-mechanism.md) continues to own the default-required safety rule and format-version policy.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.zh.md b/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.zh.md
index 0c635b1082..8fddbfdd7e 100644
--- a/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决定
 
-标准 `SessionEvent` 信封保留 `ignorable?: true`，每种表示都保留它：seed 校验、JSONL、API 传输、生成目录与测试 fixture。`PersistenceCoordinator` 继续拒绝未知事件，除非已存信封显式带有 `ignorable: true`；字段不存在时仍表示读取必需。
+标准 `SessionEvent` 信封保留 `ignorable?: true`，每种表示都保留它：seed 校验、JSONL、API 传输、生成目录与测试 fixture。持久化 seam 的已存事件校验（`validateStoredEvents`）继续拒绝未知事件，除非已存信封显式带有 `ignorable: true`；字段不存在时仍表示读取必需。
 
 只有替代机制在事件生产、持久化、重新加载与传输中都支持当前第三方插件，并为已包含该标记的会话提供显式切换方案后，才能删除此字段。[Session log 版本决策](2026-08-10-session-log-version-mechanism.zh.md)继续定义默认读取必需的安全规则与格式版本策略。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
deleted file mode 100644
index 6d022cb4b3..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Agent Note: Load sessions persisted before message identity
-
-Status: implemented
-
-English | [中文](2026-07-28-load-pre-identity-session-messages.zh.md)
-
-## Problem
-
-The identified immutable message change replaced four durable event payloads with complete message values. Existing v0 JSONL Sessions still held the immediately preceding forms: direct `content`/`source` on user and steering events, `content`/`provenance` on assistant events, and `callId`/`content`/`isError` on tool results. Their headers still matched `SESSION_FORMAT_VERSION`, but current-form validation rejected them before resume could construct a live `Session`.
-
-Changing the message representation without a version bump made those logs indistinguishable at the header level from current v0 logs. The runtime needs a narrow import rule that restores data created by the supported first-party provider without weakening validation for unrelated obsolete or malformed events.
-
-## Decision
-
-`PersistenceCoordinator` normalizes the four exact pre-identity message payloads after backend decoding and before current message validation. It wraps their existing semantic fields in the current role-specific message shape and assigns `legacy-message:<session-id>:<event-seq>` as the deterministic imported `MessageId`. A legacy `tool/result` content replacement inherits the imported id of its replacement target, preserving the current content-only rewrite invariant.
-
-The same normalization runs for `load`, `inspect`, an ownerless loaded state claiming its live session, and HMR prefix adoption. Prefix comparisons therefore compare the live current-shape seed with the same normalized stored view. Current-looking wrappers with missing or invalid fields are not repaired, and unsupported event vocabulary, request headers, versions, and surface relations retain their existing rejection paths.
-
-The upgrade is read-only. Stored legacy records remain unchanged; a resumed session appends only current-shape events after them. Deterministic identities make repeated loads and a mixed legacy/current log reproduce the same message ids without a backend-specific rewrite transaction.
-
-## Alternatives considered
-
-**Reject the logs under the pre-release compatibility stance.** This is the default for unrelated v0 churn, but it strands real first-party sessions even though every old field maps unambiguously to the current message representation.
-
-**Rewrite the complete stored log in place.** This would canonicalize the artifact but violate the append-only storage contract, require an atomic replacement mechanism, and expand a read compatibility fix into a migration system.
-
-**Mint random ids on each load.** The messages would satisfy the type shape but lose stable identity across inspect, resume, restart, and mixed legacy/current appends.
-
-## Consequences
-
-Pre-identity JSONL Sessions resume with their original message content, sources, assistant provider/model fields, tool correlation, errors, metadata, and surface replacements. The returned events are otherwise indistinguishable from current imported message snapshots and remain deeply frozen.
-
-This is one explicit same-version import exception, not a general v0 compatibility layer. Adding another exception requires another complete, unambiguous mapping at the persistence boundary; malformed current data continues to fail rather than being guessed into validity. The shared coordinator contract exercises the upgrade against the in-memory reference and JSONL provider, including deterministic reload and tool-result replacement identity.
-
-## Related
-
-- [Create every message as an identified immutable value](../architecture/2026-07-28-identified-immutable-message-values.md) — owns the current message identity and immutability contract.
-- [Session persistence as an abstract service](../architecture/2026-06-14-session-persistence.md) — owns the append-only backend and resume boundary.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
deleted file mode 100644
index 86439337b3..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Agent Note: 加载消息标识机制引入前持久化的会话
-
-Status: implemented
-
-[English](2026-07-28-load-pre-identity-session-messages.md) | 中文
-
-## 问题
-
-带标识的不可变消息变更将四种持久化事件载荷替换为完整消息值。现有 v0 JSONL Session 仍保留紧邻该变更之前的表示：用户事件和 steering（中途引导）事件直接携带 `content`/`source`，assistant 事件携带 `content`/`provenance`，工具结果则携带 `callId`/`content`/`isError`。这些 Session 的 header 仍与 `SESSION_FORMAT_VERSION` 匹配，但当前表示验证会拒绝它们，导致恢复流程无法构造 live `Session`。
-
-消息表示改变时没有提升版本，导致这些日志无法仅凭 header 与当前 v0 日志区分。运行时需要一条范围受限的导入规则，既能恢复受支持的 first-party provider 所创建的数据，又不削弱对无关过时事件或格式错误事件的验证。
-
-## 决策
-
-`PersistenceCoordinator` 会在后端解码之后、当前消息验证之前，规范化消息标识机制引入前的四种特定消息载荷。它将载荷现有的语义字段包装进当前按角色区分的消息形状，并为其分配确定性的导入用 `MessageId`：`legacy-message:<session-id>:<event-seq>`。旧版 `tool/result` 的内容替换会继承替换目标导入后的 id，从而保持当前仅改写内容的不变量。
-
-同一项规范化也用于 `load`、`inspect`、无 owner 的已加载状态认领其活跃会话，以及 HMR（热模块替换）前缀接管。因此，前缀比较会将活跃会话的当前形状 seed 与同一份规范化存储视图进行比较。看似当前形状、但字段缺失或无效的包装层不会被修复；不受支持的事件词汇、请求 header、版本和 surface 关系仍沿用现有拒绝路径。
-
-这项升级只发生在读取时。存储中的旧版记录保持不变；会话恢复后，只会在其后追加当前形状的事件。确定性标识使重复加载以及新旧形状混合的日志无需执行后端专用的重写事务，也能复现相同的消息 id。
-
-## 考虑过的替代方案
-
-**按照预发布兼容性立场拒绝这些日志。** 这是处理其他 v0 形状变动的默认方式，但即使每个旧字段都能明确映射到当前消息表示，它仍会导致真实的第一方会话无法恢复。
-
-**就地重写完整的存储日志。** 这会使产物规范化，但违反仅追加存储约定，还需要原子替换机制，并将一次读取兼容性修复扩大为迁移系统。
-
-**每次加载时随机生成 id。** 这些消息会满足类型形状，却无法在检查、恢复、重启以及新旧形状混合追加之间保持稳定标识。
-
-## 后果
-
-消息标识机制引入前的 JSONL Session 可以恢复，并保留原始消息内容、来源、assistant 的 provider／model 字段、工具调用关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
-
-这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享协调器约定会通过内存参考实现与 JSONL provider 验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
-
-## 相关
-
-- [将每条消息创建为带标识的不可变值](../architecture/2026-07-28-identified-immutable-message-values.zh.md)：该记录负责当前的消息标识与不可变性约定。
-- [会话持久化作为抽象服务](../architecture/2026-06-14-session-persistence.zh.md)：该记录负责仅追加后端与恢复边界。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
index a1a69bb1af..a5e97e8e8e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.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 .agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
-2026-07-31-resume-selector-batch-projection.md: e4809575e03bbd74522b26a8a170ac558d6eee41
-2026-07-31-resume-selector-batch-projection.zh.md: 04646d266c87b96b7c28692663540ffe808d0082
+2026-07-31-resume-selector-batch-projection.md: aa99ecf323b44432e360402f072d89436b2778bd
+2026-07-31-resume-selector-batch-projection.zh.md: ebc9d43677edc23004c32736db989d39e59ef152
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
index e4809575e0..aa99ecf323 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
@@ -26,7 +26,7 @@ No session-query or session-persistence surface changed. The shipped TUI composi
 
 **Fix only the O(N²) listing inside `SessionCorpus.load()`.** Rejected as the primary fix: the per-candidate full decompress, replay validation, and triple clone dominated on large logs. The redundant pre-listing in `load()` remains a candidate cleanup with error-semantics implications.
 
-**Surface a last-modified time through `listSnapshots`/`SessionRecord`.** Cleanest seam-wise, but touches the persistence contract, provider, and query record type for what the TUI can already derive from `locate()` plus one stat. Reintroduce if a second consumer needs metadata activity times.
+**Surface a last-modified time through `list()`/`SessionRecord`.** Cleanest seam-wise, but touches the persistence contract, provider, and query record type for what the TUI can already derive from the stored log's file metadata. Reintroduce if a second consumer needs metadata activity times.
 
 **A bespoke persisted title index or TUI-local title cache.** Rejected: the session-projection cache already is the owned durable checkpoint system with an invalidation contract (`stateVersion`, identity binding, shrunk-log anchoring); mounting it beats adding a parallel cache.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
index 04646d266c..ebc9d43677 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
@@ -26,7 +26,7 @@ session-query 与 session-persistence 的任何接口都未改变。随附的 TU
 
 **只修复 `SessionCorpus.load()` 内部的 O(N²) 列表查询。** 作为主要修复被否决：在大日志上，按候选行执行的完整解压、回放验证和三重克隆才是主要开销。`load()` 中的冗余预列表查询仍是一个候选清理项，但涉及错误语义。
 
-**通过 `listSnapshots`/`SessionRecord` 暴露最后修改时间。** 从 seam 角度最干净，但要触碰持久化约定、provider 和查询记录类型，而 TUI 已能用 `locate()` 加一次 stat 得到同样的信息。若出现第二个需要元数据活动时间的消费方再引入。
+**通过 `list()`/`SessionRecord` 暴露最后修改时间。** 从 seam 角度最干净，但要触碰持久化约定、provider 和查询记录类型，而 TUI 已能从已存日志的文件元数据得到同样的信息。若出现第二个需要元数据活动时间的消费方再引入。
 
 **专门的持久化标题索引或 TUI 本地标题缓存。** 否决：session-projection 缓存本身就是自有的持久 checkpoint 系统，并已带失效约定（`stateVersion`、身份绑定、日志收缩锚定）；挂载它优于再造一套并行缓存。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
deleted file mode 100644
index e95817ee60..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Agent Note: Load sessions from the pre-react-loop format
-
-Status: implemented
-
-English | [中文](2026-08-04-load-pre-react-loop-sessions.zh.md)
-
-## Problem
-
-The react-loop simplification changed durable events while retaining `SESSION_FORMAT_VERSION` 0. Stored sessions from the change's base contain `steering/message` and `turn/start.trigger`; their terminal reasons also use coarse `aborted`, separate `disposed`, and two older error payloads. Current surface and turn invariants cannot replay those records directly.
-
-The new durable inbox is not part of this compatibility problem. The base emitted process-local inbox notifications but no `agent/inbox/*` session events, so replaying old history as pending work would resurrect already claimed or discarded prompts.
-
-## Decision
-
-`PersistenceCoordinator` recognizes the exact pre-react-loop shapes after backend decoding and projects them into the current read view. It removes the obsolete `turn/start.trigger`, converts `steering/message` to the same identified `user/message`, maps old failure facts into the current structured error, folds `disposed` into an aborted turn with the `disposed` cause, and represents coarse aborted records with the persistence-only `{ kind: 'legacy' }` cause because their caller is unavailable.
-
-The coordinator applies the projection to `load`, `inspect`, adoption, HMR prefix comparison, and `readFrom`. A seek-capable `readFrom` normally reads only its suffix; when that suffix contains a legacy event needing an earlier replacement identity, the coordinator loads and normalizes the complete prefix before returning the requested seq range.
-
-The importer does not synthesize inbox splices. A resumed pre-react-loop agent begins with empty pending lists, matching the base runtime's inability to persist pending inbox work. The stored artifact remains append-only and later events use the current format.
-
-## Alternatives considered
-
-**Treat the same-version records as unsupported.** This follows the pre-release default but strands sessions produced by the PR base even though the removed steering content and terminal facts have complete mappings.
-
-**Replay old inbox notifications into durable splices.** Those notifications were not session events and do not provide a trustworthy pending-state snapshot. Inferring insertions without every claim and discard would re-run consumed work.
-
-**Assign coarse aborted records to an existing caller.** Mapping them to `user`, `parent`, or `hook` would invent a caller that the old record did not name. A dedicated `legacy` cause keeps the stop classification without making a false audit claim.
-
-**Rewrite stored JSONL records.** A rewrite would violate the append-only contract and require atomic migration machinery for a read compatibility boundary.
-
-## Consequences
-
-Sessions written in the refactor's base format resume through the current AgentLoop with their steering content, turn boundaries, error facts, and stop classification intact. The shared coordinator contract covers in-memory and JSONL `load`/`inspect`/`readFrom`; an assembled JSONL Agent resume verifies that the historical transcript is visible while both new inbox lists start empty.
-
-This exception supports the base format, not intermediate formats produced during development of the refactor. In particular, it defines no migration for earlier experimental `agent/inbox/spliced` payloads. Exact-shape recognition keeps malformed current-looking records on their rejection path instead of guessing them into validity.
-
-## Related
-
-- [Load sessions persisted before message identity](2026-07-28-load-pre-identity-session-messages.md) — owns deterministic identities and the general read-only import boundary for another same-version format change.
-- [Session persistence as an abstract service](../architecture/2026-06-14-session-persistence.md) — owns append-only backend storage and resume.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
deleted file mode 100644
index 98fb1f530f..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Agent Note: 加载 react-loop 重构前格式的会话
-
-Status: implemented
-
-[English](2026-08-04-load-pre-react-loop-sessions.md) | 中文
-
-## 问题
-
-react-loop 简化在保持 `SESSION_FORMAT_VERSION` 为 0 的同时更改了持久事件。该变更基线所存储的会话包含 steering（中途引导）事件 `steering/message`，以及 `turn/start.trigger` 字段；其终止原因还使用粗粒度 `aborted`、独立的 `disposed` 和两种旧版错误载荷。当前表层和轮次不变量无法直接回放这些记录。
-
-新的持久 inbox 不属于此兼容性问题。该基线会发出进程本地 inbox 通知，但不会产生 `agent/inbox/*` 会话事件，因此将旧历史回放为待处理工作会让已经领取或丢弃的提示词再次执行。
-
-## 决策
-
-`PersistenceCoordinator` 会在后端解码后识别 react-loop 重构前的确切形状，并将其投影为当前读取视图。它移除已废弃的 `turn/start.trigger`，把 `steering/message` 转换为同一条带标识的 `user/message`，将旧版失败事实映射为当前结构化错误，把 `disposed` 折叠为带 `disposed` 原因的已中止轮次，并用仅供持久化导入使用的 `{ kind: 'legacy' }` 原因表示粗粒度中止记录，因为无法获得其调用方。
-
-协调器会把该投影应用于 `load`、`inspect`、接管、HMR（热模块替换）前缀比较和 `readFrom`。可寻址的 `readFrom` 通常只读取后缀；如果后缀包含需要更早替换标识的旧版事件，协调器会先加载并规范化完整前缀，再返回所请求的 seq 范围。
-
-导入器不会合成 inbox splice。恢复后的 react-loop 重构前 agent（智能体）从空的待处理列表开始，这与基线运行时无法持久化待处理 inbox 工作的行为一致。已存储产物仍然仅追加，后续事件使用当前格式。
-
-## 考虑过的替代方案
-
-**将同版本记录视为不受支持。** 这符合预发布阶段的默认立场，但会使 PR（Pull Request）基线产生的会话无法恢复，尽管已移除的 steering 内容和终止事实都有完整映射。
-
-**将旧 inbox 通知回放为持久 splice。** 这些通知不是会话事件，也无法提供可信的待处理状态快照。如果无法获知每一次领取和丢弃，就推断插入操作，会让已消费的工作再次执行。
-
-**将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会凭空指定旧记录未注明的调用方。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
-
-**重写已存储的 JSONL 记录。** 重写会违反仅追加约定，并要求为读取兼容边界建立原子迁移机制。
-
-## 后果
-
-以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器约定覆盖内存与 JSONL 的 `load`／`inspect`／`readFrom`；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
-
-此例外支持基线格式，不支持重构开发期间产生的中间格式。具体而言，它没有为更早的实验性 `agent/inbox/spliced` 载荷定义迁移。通过确切形状识别，当前格式外观相似但结构错误的记录仍会走拒绝路径，不会被猜测性地转换为有效记录。
-
-## 相关资料
-
-- [加载消息标识机制引入前持久化的会话](2026-07-28-load-pre-identity-session-messages.zh.md)：负责另一项同版本格式变更的确定性标识和通用只读导入边界。
-- [以抽象服务实现会话持久化](../architecture/2026-06-14-session-persistence.zh.md)：负责仅追加后端存储和恢复。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.i18n.yaml
index 94a7268a28..51a7388005 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.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 .agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.md
-2026-08-13-bounded-cold-blank-verification.md: ab2f3b5a0534a98e02a3e2494ca2fff1223efe81
-2026-08-13-bounded-cold-blank-verification.zh.md: 5dc4b62f7ac43ebd3c4a8cef58f5da9af367520a
+2026-08-13-bounded-cold-blank-verification.md: 8244b93641cfe576cd2f5b0c618ae69fbb215dd5
+2026-08-13-bounded-cold-blank-verification.zh.md: 2c7f392fa8fbd3fed0641fe2b95e717f76cd78fb
diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.md b/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.md
index ab2f3b5a05..8244b93641 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.md
@@ -14,15 +14,15 @@ The same cold list used the JSONL artifact mtime for `updatedAt`. Opening a Sess
 
 `dsh-api-session-controller` registers `sessionListMetadata`, a projection containing `blank` and `lastPromptAt`. The attached summary folds the same functions directly over the live log. `blank` changes only from true to false on `turn/start`; `lastPromptAt` changes only on a `user/message` whose source kind is `user`.
 
-A cold summary trusts cached `blank: false`, because a checkpoint prefix containing `turn/start` remains non-blank. Cached `blank: true` and a cache miss do not prove the current log is blank. When persistence exposes a physical artifact through `locate()` and its observed size is at most the `coldBlankProbeMaxBytes` eligibility threshold (default 1 KiB per Session), the gateway calls `readFrom(id, 0)` and folds exact list metadata from the stored prefix. Files above the threshold, backends without a location, vanished artifacts, and failed reads all produce `blank: false`, keeping the Session visible.
+A cold summary trusts cached `blank: false`, because a checkpoint prefix containing `turn/start` remains non-blank. Cached `blank: true` and a cache miss do not prove the current log is blank and are served `blank: false`, keeping the Session visible. The earlier physical-size probe — a `locate()` path plus a `coldBlankProbeMaxBytes` eligibility threshold gating an exact `readFrom(id, 0)` fold — is removed with the seam's path query ([export and pre-release trims](../simplification/2026-08-27-persistence-export-and-pre-release-trims.md)); persistence snapshot metadata (`eventCount`/`sizeBytes` on `stat()`/`list()`) is the reintroduction path for exact cold verification.
 
-`updatedAt` is the later of `createdAt` and `lastPromptAt`. An eligible artifact read supplies exact `lastPromptAt` at no additional I/O cost; other cache misses or stale checkpoints order the Session too old rather than promoting it from an unrelated file write. After each asynchronous cold read, the gateway checks the live store again and replaces the cold result with an attached summary when another request resumed that Session meanwhile.
+`updatedAt` is the later of `createdAt` and `lastPromptAt`. A cache miss or stale checkpoint orders the Session too old rather than promoting it from an unrelated file write.
 
 ## Alternatives considered
 
 **Trust cached `blank: true`.** Rejected because the projection cache deliberately permits a persisted log to advance beyond its checkpoint. A crash or fail-soft write failure after the first `turn/start` would hide a real conversation and could make the client reuse it as New Session.
 
-**Read every cold log.** Rejected because list latency and I/O would scale with total stored conversation bytes. The physical-size eligibility check targets small historical artifacts that can be checked cheaply and degrades larger unknowns toward visibility. It intentionally does not add a persistence operation solely to make the threshold atomic with the read: concurrent growth may increase one probe's read cost, but the additional events can only preserve visibility or change a blank result to non-blank.
+**Read every cold log.** Rejected because list latency and I/O would scale with total stored conversation bytes; unverified cold entries degrade toward visibility instead.
 
 **Store blankness and recency in an authoritative persistence index.** Deferred because the shipped JSONL provider has an immutable first line and would require a second durable artifact with ordered updates. An out-of-tree provider may use its own index only with defined update atomicity, versioning, and recovery. The broader exact-index design remains in the [last-activity proposal](../../proposed/architecture/2026-07-29-durable-last-activity-index.md).
 
@@ -30,8 +30,6 @@ A cold summary trusts cached `blank: false`, because a checkpoint prefix contain
 
 ## Consequences
 
-Existing small blank JSONL artifacts are hidden without depending on projection-cache availability, and a stale cache cannot hide a stored `turn/start`. A cold list may read each artifact whose observed physical size is within the configured threshold when its cache does not already prove non-blank. The default threshold compares compressed bytes for the shipped Zstandard JSONL backend.
+A stale cache cannot hide a stored `turn/start`, and a cold list performs no artifact I/O: cold rows are served from cached projections only. Blank cold Sessions without a cached non-blank projection remain visible, and missing or delayed recency cache entries fall back to `createdAt`. These are conservative degradations: the UI may show an extra empty row or order a Session too low, but it does not hide a conversation or promote one because it was merely opened.
 
-Blank artifacts above the threshold and blank Sessions on location-less backends remain visible. Missing or delayed recency cache entries for artifacts that are not read fall back to `createdAt`. These are conservative degradations: the UI may show an extra empty row or order a Session too low, but it does not hide a conversation or promote one because it was merely opened.
-
-The gateway-owned projection is an effect of the gateway fiber; unloading the gateway removes the key. Unit coverage pins exact-threshold eligibility, stale-true rejection, monotonic false reuse, exact small-log recency, live-attachment races, fallback direction, human-prompt recency, and fiber disposal. A keyless Web snapshot boots the shipped compressed JSONL composition, seeds a small cold blank artifact without a cache row, and verifies that the sidebar omits it.
+The gateway-owned projection is an effect of the gateway fiber; unloading the gateway removes the key. Unit coverage pins stale-true rejection, monotonic false reuse, cache-miss visibility, human-prompt recency, and fiber disposal.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.zh.md b/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.zh.md
index 5dc4b62f7a..2c7f392fa8 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.zh.md
@@ -14,15 +14,15 @@ Web 会话树会隐藏空白 Session，并把当前选中的空白项复用为 N
 
 `dsh-api-session-controller` 注册 `sessionListMetadata` 投影，其中包含 `blank` 与 `lastPromptAt`。已附加摘要直接用同一组函数折叠实时日志。`blank` 只在 `turn/start` 时从 true 单调变为 false；`lastPromptAt` 只在来源 kind 为 `user` 的 `user/message` 上更新。
 
-冷摘要信任缓存的 `blank: false`，因为已包含 `turn/start` 的 checkpoint 前缀会始终保持非空。缓存的 `blank: true` 和 cache miss 都无法证明当前日志为空。当 persistence 通过 `locate()` 暴露物理工件，且其观测大小不超过 `coldBlankProbeMaxBytes` 资格阈值（默认每个 Session 1 KiB）时，网关调用 `readFrom(id, 0)`，从已存前缀折叠精确列表元数据。超过阈值的文件、不提供位置的后端、已消失的工件和读取失败都产生 `blank: false`，让 Session 保持可见。
+冷摘要信任缓存的 `blank: false`，因为已包含 `turn/start` 的 checkpoint 前缀会始终保持非空。缓存的 `blank: true` 和 cache miss 都无法证明当前日志为空，因而按 `blank: false` 提供，让 Session 保持可见。早先的物理大小探测——`locate()` 路径加上门控一次精确 `readFrom(id, 0)` 折叠的 `coldBlankProbeMaxBytes` 资格阈值——随该 seam 的路径查询一并移除（[导出与预发布裁剪](../simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md)）；persistence 快照元数据（`stat()`/`list()` 上的 `eventCount`/`sizeBytes`）是重新引入精确冷验证的路径。
 
-`updatedAt` 取 `createdAt` 与 `lastPromptAt` 中较晚者。符合资格的工件读取无需额外 I/O 即可提供精确 `lastPromptAt`；其他 cache miss 或陈旧 checkpoint 只会让 Session 排得偏旧，而不会因无关的文件写入被提升。每次异步冷读取后，网关都会再次检查实时 store；若另一请求期间已恢复该 Session，则用已附加摘要替换冷结果。
+`updatedAt` 取 `createdAt` 与 `lastPromptAt` 中较晚者。cache miss 或陈旧 checkpoint 只会让 Session 排得偏旧，而不会因无关的文件写入被提升。
 
 ## Alternatives considered
 
 **信任缓存的 `blank: true`。** 拒绝，因为 projection cache 有意允许持久日志前进到 checkpoint 之后。首个 `turn/start` 之后若发生崩溃或 fail-soft 写入失败，真实对话就会被隐藏，客户端还可能把它复用为 New Session。
 
-**读取每一份冷日志。** 拒绝，因为列表延迟与 I/O 会随所有已存对话的总字节数增长。物理大小资格检查只针对能够低成本核验的小型历史工件，更大的未知项则向保持可见降级。该检查有意不为“让阈值与读取原子化”单独新增 persistence 操作：并发增长可能增加一次探测的读取成本，但新增事件只会保持可见，或把空白结果改为非空。
+**读取每一份冷日志。** 拒绝，因为列表延迟与 I/O 会随所有已存对话的总字节数增长；未经核验的冷条目转而向保持可见降级。
 
 **把空白状态与最近时间存入权威 persistence index。** 暂缓，因为交付的 JSONL provider 首行不可变，需要增加带有顺序写入要求的第二份持久工件。仓库外 provider 只有定义更新原子性、版本与恢复语义后才可使用自己的索引。更广泛的精确索引设计仍由[最后活动提案](../../proposed/architecture/2026-07-29-durable-last-activity-index.zh.md)负责。
 
@@ -30,8 +30,6 @@ Web 会话树会隐藏空白 Session，并把当前选中的空白项复用为 N
 
 ## Consequences
 
-既有的小型空白 JSONL 工件无需依赖 projection cache 是否存在即可被隐藏，陈旧 cache 也无法隐藏已存的 `turn/start`。对于 cache 尚不能证明非空，且观测物理大小在配置阈值内的每个 Session，冷列表可能读取其工件。对默认交付的 Zstandard JSONL 后端，该阈值比较压缩后的字节数。
+陈旧 cache 无法隐藏已存的 `turn/start`，且冷列表不做任何工件 I/O：冷行只从缓存投影提供。没有缓存非空投影的空白冷 Session 保持可见，缺失或延迟的最近时间 cache 条目回退到 `createdAt`。这些都是保守降级：UI 可能多显示一条空记录，或把 Session 排得偏低，但不会隐藏真实对话，也不会因为单纯打开而把会话提升到前面。
 
-超过阈值的空白工件，以及来自不提供位置的后端的空白 Session 会保持可见。对于未被读取的工件，缺失或延迟的最近时间 cache 会回退到 `createdAt`。这些都是保守降级：UI 可能多显示一条空记录，或把 Session 排得偏低，但不会隐藏真实对话，也不会因为单纯打开而把会话提升到前面。
-
-网关自有投影是网关 fiber 的 effect；卸载网关会移除该 key。单元覆盖固定了临界大小资格、拒绝陈旧 true、复用单调 false、小日志精确最近时间、实时附加竞态、回退方向、真人 prompt 最近时间和 fiber 销毁。无密钥 Web snapshot 会启动发行版的压缩 JSONL 组合，在没有 cache row 的情况下播种一份小型冷空白工件，并验证侧栏不展示它。
+网关自有投影是网关 fiber 的 effect；卸载网关会移除该 key。单元覆盖固定了拒绝陈旧 true、复用单调 false、cache miss 保持可见、真人 prompt 最近时间和 fiber 销毁。
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
index 50b5c20bf4..9f4c455c9c 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.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 .agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
-2026-07-10-agent-session-identity-and-log-location.md: 1bd16fa4123aa8a44719aa0e8c40c4e662f7cb3b
-2026-07-10-agent-session-identity-and-log-location.zh.md: 1b54949fb34a0593eaa255e8ff548c203c8023c8
+2026-07-10-agent-session-identity-and-log-location.md: c849ffb882a3334c380b6736a8c8fd8d07a9da40
+2026-07-10-agent-session-identity-and-log-location.zh.md: 07826993839257dd893ef2a56059170ef9d0db31
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
index 1bd16fa412..c849ffb882 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
@@ -1,4 +1,4 @@
-# Agent Note: Expose agent session identity and JSONL location to tools and hooks
+# Agent Note: Expose agent session identity to tools and hooks
 
 Status: implemented
 
@@ -6,29 +6,12 @@ English | [中文](2026-07-10-agent-session-identity-and-log-location.zh.md)
 
 ## Problem
 
-An agent can identify its workspace through `session.header.cwd`, but a model using bash cannot reliably identify the session that owns the call or the durable transcript that records it. Searching `./.sessions` guesses deployment config and JSONL layout; custom roots, alternate persistence backends, resume, forks, and concurrent parent/child agents make that guess unreliable. Hooks have the same need for transcript location, while future plugins may need to expose other harness-owned environment facts to shell commands.
+An agent can identify its workspace through `session.header.cwd`, but a model using bash cannot reliably identify the session that owns the call. Resume, forks, and concurrent parent/child agents make any ambient guess unreliable, while future plugins may need to expose other harness-owned environment facts to shell commands.
 
 The boundary must preserve two properties: the owner of a fact decides how to resolve it, and every child receives a per-execution snapshot rather than process-global mutable state. In particular, a nested harness must not leak its ambient `DSH_*` values into a child whose current agent, persistence backend, or configuration differs.
 
 ## Decision
 
-Extend the [`SessionPersistence`](../architecture/2026-06-14-session-persistence.md) seam with a synchronous, side-effect-free location query:
-
-```ts
-import type { SessionHeader } from '@deepseek-ai/dsh-session'
-
-interface SessionLocation {
-  readonly kind: string
-  readonly path: string
-}
-
-interface SessionPersistence {
-  locate(meta: SessionHeader): SessionLocation | undefined
-}
-```
-
-`path` is an absolute local path to the provider's dedicated log for `meta`; `kind` identifies the representation. JSONL returns `{ kind: 'jsonl', path }` using its resolved root and path helpers. An out-of-tree provider without an honest local per-Session artifact returns `undefined`. The query creates and flushes nothing, so it can report a lazy target path before that file exists.
-
 The model-facing bash package owns a `ctx.shellEnv` registry. A contributor declares its stable name, every `DSH_*` key it may return, a description for each key, and `resolve(execution: ToolExecution)`. Duplicate contributor names, duplicate key ownership, reserved keys, malformed declarations, undeclared runtime output, and non-string output fail loudly. Registration is a Cordis effect and is removed with the contributing plugin fiber. `list()` exposes declarations without running resolvers, keeping the environment API enumerable for diagnostics and future prompt/UI consumers.
 
 The registry rebuilds a trusted overlay for every foreground and background bash `ToolExecution`:
@@ -36,15 +19,16 @@ The registry rebuilds a trusted overlay for every foreground and background bash
 - `DSH_HOME` is always the absolute configured Harness home. The standalone [`@deepseek-ai/dsh-home-paths`](../../../../packages/util/home-paths/README.md) utility owns its precedence: explicit `dshHome`, then ambient `$DSH_HOME`, then `~/.dsh`.
 - `DSH_SHELL=1` is always present and identifies a model bash child managed by DeepSeek Harness.
 - `DSH_SESSION_ID` is present when the execution has an agent and equals `agent.session.header.id`.
-- The built-in persistence translator contributes `DSH_SESSION_JSONL` only when `ctx.sessionPersistence.locate(header)` returns `kind: 'jsonl'`.
 
-Session persistence remains the fact owner: JSONL does not depend on tool-bash or register shell variables itself, and hooks continue to consume `locate()` directly. Tool-bash is the translation layer from the persistence fact into a shell convention. Other plugins that need shell-visible facts depend on the registry and register their own keys; they do not modify `process.env`.
+A transcript-location fact is deliberately absent. An earlier form of this decision also extended the persistence seam with a `locate()` path query feeding a `DSH_SESSION_JSONL` variable and the hook bridges' `transcript_path`; the [persistence export and pre-release trims](../simplification/2026-08-27-persistence-export-and-pre-release-trims.md) note owns removing that half — the paths were only readable with compression disabled, and the seam no longer exposes artifact locations.
+
+Plugins that need shell-visible facts depend on the registry and register their own keys; they do not modify `process.env`.
 
 The bash seam exports `DSH_ENV_PREFIX` as the single namespace source and derives `DshEnvironmentKey` from its `typeof`. Tool-bash derives built-in names and model guidance from that constant, while executors use it for ambient filtering. The seam carries the managed overlay separately as `ShellExecRequest.dshEnv` / `ShellExecSpec.dshEnv`: ordinary `env` remains the general in-process plugin surface used by hooks, while `dshEnv` is typed to managed keys. The local executor removes every inherited ambient managed key, applies its ordinary scrub/terminal environment/explicit `env`, and finally merges the trusted `dshEnv` snapshot, so an `env` entry can never displace a managed value. This guarantees that a missing value means absent now rather than inherited from an outer or previous harness. The model-facing tool still ignores model-supplied `env`/`stdin` arguments.
 
 The bash tool description teaches only the durable convention: current harness environment facts are available through managed `$DSH_*` variables and may be inspected when needed. It does not enumerate persistence-specific keys or add a permanent system-prompt section. Tool schemas are already logged in request headers and tool output is logged as `tool/result`, so no new session event is required.
 
-The [Claude Code and Codex hook bridges](2026-06-30-hook-bridges.md) resolve transcript location from the same persistence seam when constructing payloads. Codex uses `transcript_path: string | null`; Claude Code preserves its string field and falls back to `''`. Hook lookup neither materializes nor flushes a session.
+The [Claude Code and Codex hook bridges](2026-06-30-hook-bridges.md) keep `transcript_path` in their wire payloads for protocol shape but always send `''` (Claude Code) / `null` (Codex); the [persistence export and pre-release trims](../simplification/2026-08-27-persistence-export-and-pre-release-trims.md) note owns that degradation.
 
 ## Peer product findings
 
@@ -52,36 +36,30 @@ Peer products separate stable identity from physical storage. Codex injects stab
 
 ## Lifecycle and persistence semantics
 
-A fresh session receives its id before the first turn, so its first bash call can read `DSH_SESSION_ID` and a JSONL target. The JSONL file may still be absent until the first successful turn-end checkpoint, and during an open turn it contains only the last flushed prefix. `DSH_SESSION_JSONL` is a location hint, not an authorization credential or freshness guarantee.
-
-Resume reuses the loaded header and therefore the same id and location. Fork and spawn create new session ids and locations. Parent and child calls resolve from their own `ToolExecution.agent`; each command receives an immutable snapshot even when calls overlap. A persistence service replacement affects later collections because the translator queries `ctx.get('sessionPersistence')` at execution time; the registry itself is effect-scoped and HMR-safe.
+A fresh session receives its id before the first turn, so its first bash call can read `DSH_SESSION_ID`. Resume reuses the loaded header and therefore the same id. Fork and spawn create new session ids. Parent and child calls resolve from their own `ToolExecution.agent`; each command receives an immutable snapshot even when calls overlap. The registry is effect-scoped and HMR-safe.
 
 `dshHome` is session-independent deployment context. Agent-core resolves one value through `@deepseek-ai/dsh-home-paths` and routes it to both tool-bash and local skill discovery; standalone consumers call the same resolver. If top-level `dshHome` and `skills.local.dshHome` are both supplied and resolve differently, composition fails instead of exposing contradictory homes. Persistence may change independently without freezing its facts into the session prefix.
 
 ## Testing
 
-Unit coverage pins registry declaration validation, effect disposal, per-execution collection, the `dshHome` precedence, and the local executor's `DSH_*` scrub/rebuild order. Request-recording tests cover foreground/background snapshots, no-agent calls, absent/JSONL persistence, ignored model `env`, and parent/child isolation. JSONL and no-artifact locator contract tests plus both hook bridge suites pin available and unavailable transcript dialects.
+Unit coverage pins registry declaration validation, effect disposal, per-execution collection, the `dshHome` precedence, and the local executor's `DSH_*` scrub/rebuild order. Request-recording tests cover foreground/background snapshots, no-agent calls, ignored model `env`, and parent/child isolation. Both hook bridge suites pin the constant degraded transcript dialects.
 
-A keyless full-loop integration drives the real agent loop, JSONL persistence, tool-bash, and bash-local on the first turn. The child prints `DSH_HOME`, `DSH_SHELL`, session id, JSONL target, and an inherited stale sentinel; the test verifies current values, absence of the stale variable, pre-flush file absence, and the eventual persisted header. Snapshot coverage pins the generic bash description in the recorded request header. No with-key test is required because the contract is deterministic local execution rather than model choice.
+A keyless full-loop integration drives the real agent loop, JSONL persistence, tool-bash, and bash-local on the first turn. The child prints `DSH_HOME`, `DSH_SHELL`, session id, and an inherited stale sentinel; the test verifies current values, absence of the stale variable, and the eventual persisted header. Snapshot coverage pins the generic bash description in the recorded request header. No with-key test is required because the contract is deterministic local execution rather than model choice.
 
 ## Alternatives considered
 
 **Only an id plus `find`.** Search cannot know a custom root or backend layout and races under multiple sessions.
 
-**Only an absolute path.** A path can be unavailable, lazy, or representation-specific and is not stable session identity.
-
 **Global `process.env`.** Concurrent agents would overwrite one another and nested harnesses would inherit stale current-session values.
 
-**Put persistence instructions in the session prefix.** A session prefix is frozen while the active service can change across HMR or future backend switching; persistence-specific guidance would become stale.
-
 **A typed waterfall event.** Listeners cannot declare ownership without running, and later listeners can silently overwrite keys. A registry detects key conflicts at registration and remains enumerable.
 
-**Have each persistence backend register bash env directly.** That reverses the dependency from storage into one consumer and forces bash into deployments that do not use it. `locate()` is also still required by hooks.
+**Have each persistence backend register bash env directly.** That reverses the dependency from storage into one consumer and forces bash into deployments that do not use it.
 
 **A model-facing `session_info` tool.** It adds schema and another call while bash already supplies the query API; the registry generalizes to future environment facts without one tool per fact.
 
 ## Consequences
 
-Every model bash child receives current Harness home and shell identity, and agent calls additionally receive stable session identity. JSONL-backed calls get an optional target path; non-file persistence omits it honestly. The managed `DSH_*` facts inside these children come from the harness: ambient values are removed, current trusted values are re-added last, and an ordinary caller's `env` entry cannot displace them.
+Every model bash child receives current Harness home and shell identity, and agent calls additionally receive stable session identity. The managed `DSH_*` facts inside these children come from the harness: ambient values are removed, current trusted values are re-added last, and an ordinary caller's `env` entry cannot displace them.
 
-The namespace is discoverable but not secret. Paths can reveal configured roots, lazy targets can be absent or stale, and a command can override variables inside its own shell syntax. Consumers treat them as correlation and environment facts, verify transcript metadata when attribution matters, and rely on sandbox/filesystem policy rather than variable secrecy for authorization.
+The namespace is discoverable but not secret. `DSH_HOME` can reveal a configured root, and a command can override variables inside its own shell syntax. Consumers treat them as correlation and environment facts and rely on sandbox/filesystem policy rather than variable secrecy for authorization.
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
index 1b54949fb3..0782699383 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 向工具与钩子公开 agent 会话标识和 JSONL 位置
+# Agent Note: 向工具与钩子公开 agent 会话标识
 
 Status: implemented
 
@@ -6,29 +6,12 @@ Status: implemented
 
 ## 问题
 
-agent（智能体）可以通过 `session.header.cwd` 识别其工作区，但使用 bash 的模型无法可靠识别当前调用所属的会话，也无法找到记录该调用的持久 transcript（文本记录）。搜索 `./.sessions` 等同于猜测部署配置和 JSONL 布局；自定义根目录、替代持久化后端、恢复、fork，以及并发运行的父子 agent，都会让这种猜测失效。钩子同样需要 transcript 位置，而未来的插件也可能需要向 shell 命令公开其他由 harness 所有的环境事实。
+agent（智能体）可以通过 `session.header.cwd` 识别其工作区，但使用 bash 的模型无法可靠识别当前调用所属的会话。恢复、fork 以及并发运行的父子 agent 会让任何来自环境的猜测都不可靠，而未来的插件也可能需要向 shell 命令公开其他由 harness 所有的环境事实。
 
 这项边界必须维持两个属性：事实的所有者决定如何解析该事实；每个子进程接收每次执行的快照，而不是进程级可变全局状态。尤其是嵌套 harness 不能把环境中的 `DSH_*` 值泄漏给当前 agent、持久化后端或配置均可能不同的子进程。
 
 ## 决策
 
-在 [`SessionPersistence`](../architecture/2026-06-14-session-persistence.zh.md) seam 上增加同步、无副作用的位置查询：
-
-```ts
-import type { SessionHeader } from '@deepseek-ai/dsh-session'
-
-interface SessionLocation {
-  readonly kind: string
-  readonly path: string
-}
-
-interface SessionPersistence {
-  locate(meta: SessionHeader): SessionLocation | undefined
-}
-```
-
-`path` 是 provider 为 `meta` 保留的专用日志本地绝对路径；`kind` 标识其表示。JSONL 使用解析后的 root 与路径 helper 返回 `{ kind: 'jsonl', path }`。无法诚实提供逐 Session 本地产物的仓库外 provider 返回 `undefined`。该查询不会创建或刷写任何内容，因此即使文件尚不存在，也可以报告按需创建的目标路径。
-
 面向模型的 bash 包拥有一个 `ctx.shellEnv` 注册表。贡献方声明稳定名称、它可能返回的每个 `DSH_*` 键、每个键的说明，以及 `resolve(execution: ToolExecution)`。贡献方名称重复、键所有权重复、使用保留键、声明格式错误、运行时输出未声明或输出不是字符串时，系统都会明确失败。注册属于 Cordis effect，并随贡献插件的 fiber 一同移除。`list()` 无需运行解析器即可公开声明，从而让环境 API 可供诊断工具和未来的提示词／UI 消费方枚举。
 
 注册表会为每次前台和后台 bash `ToolExecution` 重新构建受信任的覆盖层：
@@ -36,15 +19,16 @@ interface SessionPersistence {
 - `DSH_HOME` 始终是配置的 Harness home 绝对路径。独立的 [`@deepseek-ai/dsh-home-paths`](../../../../packages/util/home-paths/README.zh.md) 工具库规定其优先级：显式 `dshHome`，其次是环境中的 `$DSH_HOME`，最后是 `~/.dsh`。
 - `DSH_SHELL=1` 始终存在，用于标识由 DeepSeek Harness 管理、面向模型的 bash 子进程。
 - 执行具有关联 agent 时，`DSH_SESSION_ID` 存在并等于 `agent.session.header.id`。
-- 内置的持久化转换层提供 `DSH_SESSION_JSONL` 的条件是 `ctx.sessionPersistence.locate(header)` 返回 `kind: 'jsonl'`。
 
-会话持久化仍然是事实所有者：JSONL 不依赖 tool-bash，也不会自行注册 shell 变量；钩子继续直接使用 `locate()`。tool-bash 是把持久化事实转换为 shell 约定的转换层。其他需要向 shell 公开事实的插件依赖该注册表，并注册各自的键；它们不修改 `process.env`。
+transcript（文本记录）位置事实被有意省略。本决策的早期形式还在持久化 seam 上增加了 `locate()` 路径查询，为 `DSH_SESSION_JSONL` 变量和钩子桥接层的 `transcript_path` 提供来源；[持久化导出与预发布精简](../simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md) Note 负责移除这一半——这些路径只有在禁用压缩时才可读，该 seam 也不再公开产物位置。
+
+需要向 shell 公开事实的插件依赖该注册表，并注册各自的键；它们不修改 `process.env`。
 
 bash seam 导出 `DSH_ENV_PREFIX` 作为唯一的命名空间来源，并派生 `DshEnvironmentKey`，其来源是该常量的 `typeof`。tool-bash 从该常量派生内置名称与模型指引，执行器则使用该常量过滤环境中已有的值。seam 通过 `ShellExecRequest.dshEnv`／`ShellExecSpec.dshEnv` 单独传递受管理的覆盖层：普通 `env` 仍是钩子所用的通用进程内插件接口，`dshEnv` 则以类型约束为受管理键。本地执行器移除环境中继承的全部受管理键，依次应用普通清理、终端环境和显式 `env`，最后合并受信任的 `dshEnv` 快照，因此 `env` 条目永远无法顶掉受管理的值。这保证了值缺失表示它当前确实不存在，而不是从外层或先前的 harness 继承而来。面向模型的工具仍忽略模型提供的 `env`／`stdin` 参数。
 
 bash 工具说明只讲解持久约定：当前 harness 环境事实通过受管理的 `$DSH_*` 变量提供，可以在需要时查看。它不会枚举持久化专用键，也不会添加永久的系统提示词章节。工具 schema 已记录在请求 header 中，工具输出则记录为 `tool/result`，因此无需新增会话事件。
 
-[Claude Code 和 Codex 钩子桥接层](2026-06-30-hook-bridges.zh.md)在构造 payload 时，从同一持久化 seam 解析 transcript 位置。Codex 使用 `transcript_path: string | null`；Claude Code 保留其字符串字段，并回退为 `''`。钩子查询不会物化或刷写会话。
+[Claude Code 和 Codex 钩子桥接层](2026-06-30-hook-bridges.zh.md)为保持协议格式，仍在线上 payload 中保留 `transcript_path` 字段，但始终发送 `''`（Claude Code）／`null`（Codex）；这项降级由[持久化导出与预发布精简](../simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md) Note 负责。
 
 ## 同类产品调研
 
@@ -52,36 +36,30 @@ bash 工具说明只讲解持久约定：当前 harness 环境事实通过受管
 
 ## 生命周期与持久化语义
 
-新会话在第一个轮次之前获得 id，因此它的首次 bash 调用即可读取 `DSH_SESSION_ID` 和 JSONL 目标。JSONL 文件可能要等到第一次成功的轮次结束检查点后才存在，而且在一个轮次仍未结束时，它只包含上次刷写的前缀。`DSH_SESSION_JSONL` 是位置提示，不是授权凭据或新鲜度保证。
-
-恢复操作复用已加载的 header，因此 id 和位置不变。fork 和 spawn 会创建新的会话 id 与位置。父子调用分别从自己的 `ToolExecution.agent` 解析事实；即使调用重叠，每条命令也会收到不可变快照。替换持久化服务会影响后续收集，因为转换层在执行时查询 `ctx.get('sessionPersistence')`；注册表本身受 effect 作用域约束，并且可安全用于 HMR（热模块替换）。
+新会话在第一个轮次之前获得 id，因此它的首次 bash 调用即可读取 `DSH_SESSION_ID`。恢复操作复用已加载的 header，因此 id 不变。fork 和 spawn 会创建新的会话 id。父子调用分别从自己的 `ToolExecution.agent` 解析事实；即使调用重叠，每条命令也会收到不可变快照。注册表受 effect 作用域约束，并且可安全用于 HMR（热模块替换）。
 
 `dshHome` 是与会话无关的部署上下文。agent-core 通过 `@deepseek-ai/dsh-home-paths` 解析出一个值，并将其同时传给 tool-bash 和本地 skill（技能）发现；独立消费方调用同一解析器。如果顶层 `dshHome` 与 `skills.local.dshHome` 均已提供但解析结果不同，组合会失败，而不会公开互相矛盾的 home。持久化可以独立变更，无需把其事实冻结到会话前缀中。
 
 ## 测试
 
-单元测试覆盖注册表声明校验、effect 释放、逐次执行收集、`dshHome` 优先级，以及本地执行器清理并重建 `DSH_*` 的顺序。请求录制测试覆盖前台／后台快照、无 agent 调用、持久化不存在或为 JSONL、忽略模型 `env`，以及父子隔离。JSONL 与无产物定位器约定测试、两套钩子桥接测试均固定 transcript 可用和不可用两种方言。
+单元测试覆盖注册表声明校验、effect 释放、逐次执行收集、`dshHome` 优先级，以及本地执行器清理并重建 `DSH_*` 的顺序。请求录制测试覆盖前台／后台快照、无 agent 调用、忽略模型 `env`，以及父子隔离。两套钩子桥接测试均锁定恒定的降级 transcript 方言。
 
-一项无密钥的完整循环集成测试会在第一个轮次驱动真实的 agent loop、JSONL 持久化、tool-bash 与 bash-local。子进程打印 `DSH_HOME`、`DSH_SHELL`、会话 id、JSONL 目标和继承的陈旧哨兵值；测试校验当前值、陈旧变量不存在、刷写前文件不存在，并最终检查持久化 header。快照测试会固定录制请求 header 中的通用 bash 说明。该约定属于确定性的本地执行，不涉及模型选择，因此无需带密钥测试。
+一项无密钥的完整循环集成测试会在第一个轮次驱动真实的 agent loop、JSONL 持久化、tool-bash 与 bash-local。子进程打印 `DSH_HOME`、`DSH_SHELL`、会话 id 和继承的陈旧哨兵值；测试校验当前值、陈旧变量不存在，并最终检查持久化 header。快照测试会固定录制请求 header 中的通用 bash 说明。该约定属于确定性的本地执行，不涉及模型选择，因此无需带密钥测试。
 
 ## 考虑过的替代方案
 
 **只提供 id，再用 `find`。** 搜索无法得知自定义根目录或后端布局，并且在多会话环境下存在竞态。
 
-**只提供绝对路径。** 路径可能不可用、延迟创建或取决于表示形式，不能作为稳定的会话标识。
-
 **使用全局 `process.env`。** 并发 agent 会互相覆盖，嵌套 harness 也会继承陈旧的当前会话值。
 
-**把持久化说明放入会话前缀。** 活动服务可以在 HMR 或未来的后端切换中改变，而会话前缀保持冻结；持久化专用指引会因此变得陈旧。
-
 **使用类型化 waterfall 事件。** 监听器不运行就无法声明所有权，而后续监听器可以无提示地覆盖键。注册表能在注册时检测键冲突，并且保持可枚举。
 
-**让每个持久化后端直接注册 bash 环境。** 这会反转依赖方向，让存储层依赖某一个消费方，并迫使未使用 bash 的部署也引入它。钩子仍然需要 `locate()`。
+**让每个持久化后端直接注册 bash 环境。** 这会反转依赖方向，让存储层依赖某一个消费方，并迫使未使用 bash 的部署也引入它。
 
 **增加面向模型的 `session_info` 工具。** bash 已经提供查询 API，新增工具只会多出 schema 和一次调用；注册表可以扩展至未来的环境事实，无需为每项事实增加一个工具。
 
 ## 影响
 
-每个面向模型的 bash 子进程都会收到当前 Harness home 和 shell 标识，关联 agent 的调用还会收到稳定的会话标识。使用 JSONL 后端的调用可以获得可选的目标路径；非文件持久化会如实省略该值。这些子进程中受管理的 `DSH_*` 事实来自 harness：系统移除环境中已有的受管理值、在最后重新加入当前受信任的值，普通调用方的 `env` 条目无法顶掉它们。
+每个面向模型的 bash 子进程都会收到当前 Harness home 和 shell 标识，关联 agent 的调用还会收到稳定的会话标识。这些子进程中受管理的 `DSH_*` 事实来自 harness：系统移除环境中已有的受管理值、在最后重新加入当前受信任的值，普通调用方的 `env` 条目无法顶掉它们。
 
-该命名空间可被发现，但并非秘密。路径可能泄露配置的根目录，延迟创建的目标也可能不存在或处于陈旧状态，而且命令可以在自己的 shell 语法中覆盖变量。消费方应把这些值视为关联信息和环境事实，在归属关系重要时校验 transcript 元数据，并依靠沙箱／文件系统策略而不是变量保密性来完成授权。
+该命名空间可被发现，但并非秘密。`DSH_HOME` 可能泄露配置的根目录，而且命令可以在自己的 shell 语法中覆盖变量。消费方应把这些值视为关联信息和环境事实，并依靠沙箱／文件系统策略而不是变量保密性来完成授权。
diff --git a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml
index 9fbc91279b..860f113f10 100644
--- a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.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 .agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md
-2026-08-06-manager-owned-subagent-settlement-delivery.md: 7dfa05c247ee0efb71963e057731c7ff6a5a1989
-2026-08-06-manager-owned-subagent-settlement-delivery.zh.md: 6bd8836d966c85ee0ef08ec19bbf96a4f72b0dd4
+2026-08-06-manager-owned-subagent-settlement-delivery.md: d06245eacd3b7453a031716b1921015a5e38a25c
+2026-08-06-manager-owned-subagent-settlement-delivery.zh.md: e5259e97f185203ed77ae9427e5523ac29d4162f
diff --git a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md
index 7dfa05c247..d06245eacd 100644
--- a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md
+++ b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md
@@ -32,6 +32,10 @@ An external `ctx.on('subagent/end')` listener looks more decoupled and is wrong.
 
 Both rules are pinned by tests that fail when the ordering is reversed or the accounting removed.
 
+### Establishment holds ownership open
+
+The owned-child accounting also guards the creation side: `holdOwnership()` pre-registers the child id in a continuation-managed parent's owned set before the establishment or resume awaits (persistence stat, provider preparation, materialization), so an idle parent cannot be judged settled while a caller is still creating or resuming that child — an admitted delivery after settlement would find a stale parent identity. The returned releaser serves only the failure path: it removes just the hold this call added, and once a live Activation for the child exists the ownership edge belongs to that Activation and `finishDisposal`'s `releaseOwnership`. A parent with no Activation needs no hold (only this manager settles parents), and a parent whose own disposal transaction is already open rejects with `ACTIVATION_CLOSING` instead of establishing a child that could never be delivered to.
+
 ### Scheduling
 
 An idle parent gets one ordinary later turn. A busy parent is steered into its nearest step boundary, because `Inbox.claim()` takes the whole next-step batch at one boundary: four children settling together then cost one step rather than four turns. Steering rather than injecting is deliberate — the wake is a no-op while the driver is running, and it closes the window where a driver retires between the status read and the send, which would strand the notice unclaimed until something unrelated woke the parent. This is a correctness rule, not a deployment preference, so it is not a `Config` field.
diff --git a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.zh.md b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.zh.md
index 6bd8836d96..e5259e97f1 100644
--- a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.zh.md
@@ -32,6 +32,10 @@ Status: implemented
 
 两条规则都有测试固定：把顺序反转或去掉记账，测试就会失败。
 
+### 建立期间保持所有权敞开
+
+被持有子代的记账同样守护创建侧：`holdOwnership()` 会在建立或恢复的各个 await（持久化 stat、提供方准备、实体化）之前，把子代 id 预先登记进由续接管理的父代持有集合，因此当调用方仍在创建或恢复某个子代时，空闲的父代不会被判定为已结算——若在结算之后才接纳投递，将会遇到过期的父代身份。返回的释放器只服务失败路径：它只移除本次调用添加的持有；一旦该子代存在活跃 Activation，所有权边就归属于该 Activation 与 `finishDisposal` 的 `releaseOwnership`。没有 Activation 的父代不需要持有（只有本管理器会结算父代），而自身 dispose 事务已经打开的父代会以 `ACTIVATION_CLOSING` 拒绝，而不是建立一个永远无法收到投递的子代。
+
 ### 调度
 
 空闲父级得到一个普通的后续轮次。繁忙父级则被 steer 到其最近的 step 边界，因为 `Inbox.claim()` 会在一个边界上整批取走 next-step：四个 child 同时结算时因此只消耗一个 step，而不是四个轮次。采用 steer 而非 inject 是刻意的——驱动运行期间该唤醒是空操作，同时它关闭了「驱动在状态读取与发送之间退出」的那个窗口；否则通知会滞留无人认领，直到别的事件唤醒父级。这是正确性规则而非部署偏好，因此不做成 `Config` 字段。
diff --git a/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.i18n.yaml b/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.i18n.yaml
index 3f5971500e..5dfaad4c18 100644
--- a/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.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 .agents/notes/implemented/feature/2026-08-10-web-session-log-export.md
-2026-08-10-web-session-log-export.md: df80ad4d264d835b2c11973ca61cf143576f11f3
-2026-08-10-web-session-log-export.zh.md: 2af86f371f9e7ed5255bb4e57a8a43427c745fe0
+2026-08-10-web-session-log-export.md: 47686e70c2f961c2d7e5d9ebd54b71b25c3c80b7
+2026-08-10-web-session-log-export.zh.md: 2c12c5271a52e37a6ded95bb65d4eb343072ba41
diff --git a/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.md b/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.md
index df80ad4d26..47686e70c2 100644
--- a/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.md
+++ b/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.md
@@ -10,7 +10,7 @@ The Trajectory view had no way to hand a debugging artifact to a human: the raw
 
 ## Decision
 
-- **The export is a host-only download, not an RPC**: `GET /api/session.export?sessionId=…&includeDescendants=true` streams one ZIP attachment. Every file is a session's **stored artifact text verbatim**: `readRaw` on the persistence service reads the backend's own durable bytes (the JSONL backend decodes its physical zstd frames, or returns plaintext) — never a reconstruction from parsed events, so packed-chunk rows, key order, and line breaks survive byte-for-byte — under its original base name (`session.jsonl` at the root, `subagents/<id>/session.jsonl` for descendants). Compression runs on the host with fflate's streaming `Zip`/`ZipDeflate` API at validated `sessionExportCompressionLevel` 0–9 (default 6), letting deployments trade CPU and latency against archive size; each entry is deflated in bounded chunks as it is produced, so the response is chunked as it is generated and the host never holds the whole archive in one buffer (at most one descendant's artifact text beyond the preloaded root). At the 64 KiB response byte high-water mark, production waits for consumer pull to restore capacity; fflate's synchronous callback can add at most one bounded input push beyond that queue bound. No manifest is written — every file is byte-identical to the durable artifact and self-describing through its own header line.
+- **The export is a host-only download, not an RPC**: `GET /api/session.export?sessionId=…&includeDescendants=true` streams one ZIP attachment. Every file is a session's **stored artifact text verbatim**: `export(id)` on the persistence service reads the backend's own durable bytes (the JSONL backend decodes its physical zstd frames, or returns plaintext) — never a reconstruction from parsed events, so packed-chunk rows, key order, and line breaks survive byte-for-byte — under its original base name (`session.jsonl` at the root, `subagents/<id>/session.jsonl` for descendants). Compression runs on the host with fflate's streaming `Zip`/`ZipDeflate` API at validated `sessionExportCompressionLevel` 0–9 (default 6), letting deployments trade CPU and latency against archive size; each entry is deflated in bounded chunks as it is produced, so the response is chunked as it is generated and the host never holds the whole archive in one buffer (at most one descendant's artifact text beyond the preloaded root). At the 64 KiB response byte high-water mark, production waits for consumer pull to restore capacity; fflate's synchronous callback can add at most one bounded input push beyond that queue bound. No manifest is written — every file is byte-identical to the durable artifact and self-describing through its own header line.
 - **Error vocabulary is HTTP-native**: missing services → 500, a backend without per-session raw artifacts → 501, missing root session → 404 (all decided before any byte streams), and a descendant without a stored artifact → the stream errors (fail-loud, never silent under-export). Request abort remains cancellation instead of being rewritten as 500; request and response-consumer cancellation converge on the producer signal, which reaches lineage, persistence, and attachment reads and terminates the active compressor. Connection applies the `/api` trust fence before dispatching the exact `GET`/`HEAD /api/session.export` route registered by `session-log-export`.
 - **The UI just downloads**: browser consumers may issue a bodyless `HEAD` preflight for preparation errors, then hand the GET endpoint to the browser's native download manager, so JavaScript never buffers the ZIP. The `session.log` RPC that an earlier iteration shipped was removed — the download endpoint is its only consumer, and the repo rule is no public interface without a current owner. The client bundle carries no archive implementation.
 - The current Header and `/export` consumers are defined by the [session-log export package contract](../../../../packages/session-query/session-log-export/README.md).
@@ -25,6 +25,6 @@ The Trajectory view had no way to hand a debugging artifact to a human: the raw
 ## Consequences
 
 - Export fidelity: immediately before reading each live root or descendant, the exporter crosses the authoritative `SessionStore.flush` durability barrier; every exported file is byte-identical to that resulting durable artifact. A live session may append again after its read, so the archive is a per-session read-boundary snapshot rather than one atomic tree snapshot. The archive name is `dsh-session-<sanitized-id>.zip` and archive paths sanitize ids before they can shape entries.
-- `supportsRawArtifacts` explicitly separates backend capability from session absence: a backend without one raw artifact per Session reports `false` and the concrete `readRaw` default rejects, while the shipped JSONL override reports `true`, owns physical decoding, and reserves `undefined` for an absent artifact. `session-log-export` registers one exact Host-only Fetch route with Connection; no Remote descriptor or JSON envelope represents the streamed response.
+- The export needs no seam capability: each log is read through a persistence read handle and serialized here as canonical JSONL, so any mounted backend exports identically ([export and pre-release trims](../simplification/2026-08-27-persistence-export-and-pre-release-trims.md) records the removal of the earlier verbatim-artifact surface). Absence is decided by a `stat` preflight (absent session → 404). `session-log-export` registers one exact Host-only Fetch route with Connection; no Remote descriptor or JSON envelope represents the streamed response.
 - Fixture mode (no host) answers 404 for the export, which the browser reports as a failed download; the navigation-panes golden snapshot includes the 导出 button.
 - Deferred: transcript.md and a report/feedback bundle remain future work; the byte-faithful, manifest-free shape keeps the v2 bundle extension cheap.
diff --git a/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.zh.md b/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.zh.md
index 2af86f371f..2c12c5271a 100644
--- a/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-10-web-session-log-export.zh.md
@@ -10,8 +10,8 @@ Trajectory 视图没有任何方式把调试工件交到人手里：原始会话
 
 ## 决策
 
-- **导出是宿主侧的下载面，不是 RPC**：`GET /api/session.export?sessionId=…&includeDescendants=true` 流式返回一个 ZIP 附件。每个文件都是会话**存储工件的逐字原文**：持久化服务新增的 `readRaw` 读取后端自己的持久化字节（jsonl 后端解码其物理 zstd 帧，或直接返回明文）——绝非从解析后事件重建，因此 chunk 打包、键序、换行全部逐字节保留——放在其原始基础文件名下（根为 `session.jsonl`，子代理为 `subagents/<id>/session.jsonl`）。压缩在宿主侧使用 fflate 流式 `Zip`/`ZipDeflate` API 和已验证的 `sessionExportCompressionLevel` 0–9（默认 6），使部署可以在 CPU／延迟与归档大小之间取舍；每个条目按有界分块边产出边压缩，响应随生成分块写出，宿主从不把整个归档放进单个缓冲区（除预载的根外，最多同时持有一条后代的工件文本）。到达 64 KiB 响应字节高水位后，生产会等待 Consumer pull 恢复容量；fflate 的同步回调最多只会在该队列界限外再增加一次有界输入 push。不写清单——每个文件都与持久化工件逐字节一致，并通过自身 header 行自描述。
-- **错误词汇是 HTTP 原生的**：服务缺失 → 500，后端不提供每会话原始工件 → 501，根会话缺失 → 404（三者都在任何字节流出前判定），后代缺少存储工件 → 流失败（fail-loud，绝不静默少导出）。请求中止会保持取消语义而不会改写成 500；请求取消与响应 consumer 取消汇合到生产者 signal，该 signal 会传到血缘、持久化与附件读取，并终止活跃压缩器。Connection 在分发 `session-log-export` 注册的精确 `GET`/`HEAD /api/session.export` 路由前应用 `/api` 信任围栏。
+- **导出是宿主侧的下载面，不是 RPC**：`GET /api/session.export?sessionId=…&includeDescendants=true` 流式返回一个 ZIP 附件。每个文件都是会话**存储工件的逐字原文**：持久化服务上的 `export(id)` 读取后端自己的持久化字节（jsonl 后端解码其物理 zstd 帧，或直接返回明文）——绝非从解析后事件重建，因此 chunk 打包、键序、换行全部逐字节保留——放在其原始基础文件名下（根为 `session.jsonl`，子代理为 `subagents/<id>/session.jsonl`）。压缩在宿主侧使用 fflate 流式 `Zip`/`ZipDeflate` API 和已验证的 `sessionExportCompressionLevel` 0–9（默认 6），使部署可以在 CPU／延迟与归档大小之间取舍；每个条目按有界分块边产出边压缩，响应随生成分块写出，宿主从不把整个归档放进单个缓冲区（除预载的根外，最多同时持有一条后代的工件文本）。到达 64 KiB 响应字节高水位后，生产会等待 Consumer pull 恢复容量；fflate 的同步回调最多只会在该队列界限外再增加一次有界输入 push。不写清单——每个文件都与持久化工件逐字节一致，并通过自身 header 行自描述。
+- **错误词汇是 HTTP 原生的**：服务缺失 → 500，后端不提供每会话原始工件 → 501，根会话缺失 → 404（三者都在任何字节流出前判定），后代缺少存储工件 → 流失败（fail-loud，绝不静默少导出）。请求中止会保持取消语义而不会改写成 500；请求取消与响应 Consumer 取消汇合到生产者 signal，该 signal 会传到血缘、持久化与附件读取，并终止活跃压缩器。Connection 在分发 `session-log-export` 注册的精确 `GET`/`HEAD /api/session.export` 路由前应用 `/api` 信任围栏。
 - **UI 只负责下载**：浏览器 Consumer 可以先发出不读取 body 的 `HEAD` 预检以取得准备阶段错误，再把 GET 端点交给浏览器原生下载管理器，因此 JavaScript 不会缓冲 ZIP。早先迭代发布的 `session.log` RPC 已删除——下载端点是它唯一的消费者，仓库规则是不留无当前所有者的公共接口。客户端 bundle 不包含任何归档实现。
 - 当前 Header 与 `/export` Consumer 由 [Session 日志导出包约定](../../../../packages/session-query/session-log-export/README.zh.md)定义。
 
@@ -25,6 +25,6 @@ Trajectory 视图没有任何方式把调试工件交到人手里：原始会话
 ## 后果
 
 - 导出保真度：读取每个实时根会话或后代前，导出器会通过权威的 `SessionStore.flush` 持久性屏障；每个导出文件都与由此得到的持久化工件逐字节一致。实时会话可能在自身读取后再次追加，因此归档是按会话读取边界形成的快照，而不是整棵树的原子快照。压缩包名为 `dsh-session-<sanitized-id>.zip`，归档路径在塑造条目前会先净化会话 id。
-- `supportsRawArtifacts` 明确区分后端能力与会话缺失：没有每 Session 一份原始工件的后端报告 `false`，具体 `readRaw` 默认会拒绝；交付的 JSONL 覆写报告 `true`、自持物理解码，并只用 `undefined` 表示工件缺失。`session-log-export` 向 Connection 注册一个精确的 Host-only Fetch 路由；流式响应不使用 Remote descriptor 或 JSON envelope 表示。
+- 导出不需要 seam 能力：每份日志经由持久化读句柄读取，并在此处序列化为规范 JSONL，因此任何挂载的后端导出完全一致（早先逐字工件表面的移除由[导出与预发布裁剪](../simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md)记录）。缺失由一次 `stat` 预检判定（会话缺失 → 404）。`session-log-export` 向 Connection 注册一个精确的 Host-only Fetch 路由；流式响应不使用 Remote descriptor 或 JSON envelope 表示。
 - fixture 模式（无宿主）对导出应答 404，浏览器会将其报告为下载失败；navigation-panes golden 快照包含「导出」按钮。
 - 暂缓：transcript.md 以及 report/feedback 打包留待后续；逐字节忠实、无清单的形态让 v2 的打包扩展保持廉价。
diff --git a/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.i18n.yaml b/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.i18n.yaml
index 444893c272..d2f85360d8 100644
--- a/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.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 .agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.md
-2026-08-22-standard-acp-automation-controls.md: 5523fd547dd850e2e52eb818ef418df5a325106e
-2026-08-22-standard-acp-automation-controls.zh.md: 23140eb3e76b26716239d0f53fe3206efd87baa9
+2026-08-22-standard-acp-automation-controls.md: dd1e39b84f942417640f741f17a211276b67872c
+2026-08-22-standard-acp-automation-controls.zh.md: be54850a933e4e728c672d76595fbf900bdda833
diff --git a/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.md b/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.md
index 5523fd547d..dd1e39b84f 100644
--- a/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.md
+++ b/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.md
@@ -32,7 +32,7 @@ Complete ACP lifecycle support requires session persistence. `session/list` read
 
 Persistence deliberately treats `create(meta)` as a live registration: the shipped JSONL provider creates no artifact until the first event append. That default removes abandoned empty sessions, but ACP cannot inherit it because `session/new` publishes a session identity before any prompt and the process may stop after the success response without receiving `session/close`. The bridge materializes only after Agent and MCP composition succeeds and before returning `session/new`; failed composition remains residue-free, while every returned id survives restart.
 
-`ensureMaterialized(session)` accepts the exact live Session so the coordinator first flushes it, then serializes header-only materialization on the existing per-session write chain using the immutable registered header. JSONL writes one header frame; an out-of-tree provider must materialize equivalent header state atomically or reject the operation. Repeat calls are idempotent. Making `create` eager would change every frontend's abandoned-session behavior, appending a synthetic event would invent a sequence and replay fact solely to trigger storage, and waiting until close would make durability race process loss.
+The bridge materializes through the ordinary durability barrier: `ctx.sessions.flush(session)` reaches the session's write handle, whose `flush` writes header-only materialization when nothing has been appended. JSONL writes one header frame; an out-of-tree provider must materialize equivalent header state atomically or reject the operation. Repeat calls are idempotent. Making `create` eager would change every frontend's abandoned-session behavior, appending a synthetic event would invent a sequence and replay fact solely to trigger storage, and waiting until close would make durability race process loss.
 
 ## Standard configuration options
 
diff --git a/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.zh.md b/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.zh.md
index 23140eb3e7..be54850a93 100644
--- a/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-22-standard-acp-automation-controls.zh.md
@@ -32,7 +32,7 @@
 
 持久化有意把 `create(meta)` 视为 live registration：交付的 JSONL provider 在首次追加事件前不创建 artifact。该默认行为会移除被放弃的空会话，但 ACP 不能继承它，因为 `session/new` 会在任何提示词出现前公布会话身份，而进程可能在返回成功响应后、收到 `session/close` 前停止。桥接层只在 Agent 和 MCP 组合成功后、返回 `session/new` 前执行实体化；组合失败仍不留下残留物，每个已返回 id 则都能在重启后继续存在。
 
-`ensureMaterialized(session)` 接收确切 live Session，使 coordinator 先 flush 该会话，再通过现有 per-session 写入链，使用已注册的不可变 header 串行执行仅 header 实体化。JSONL 写入一个 header frame；仓库外 provider 必须原子实体化等价 header 状态，否则拒绝该操作。重复调用幂等。让 `create` 全面 eager 会改变所有前端放弃会话的行为；追加 synthetic event 会仅为触发存储而虚构 sequence 与 replay 事实；等到关闭时再写入则会让持久性与进程丢失竞争。
+bridge 经由普通的持久性屏障实体化：`ctx.sessions.flush(session)` 抵达该会话的写句柄，其 `flush` 在尚无任何追加时写入仅 header 实体化。JSONL 写入一个 header frame；仓库外 provider 必须原子实体化等价 header 状态，否则拒绝该操作。重复调用幂等。让 `create` 全面 eager 会改变所有前端放弃会话的行为；追加 synthetic event 会仅为触发存储而虚构 sequence 与 replay 事实；等到关闭时再写入则会让持久性与进程丢失竞争。
 
 ## 标准配置选项
 
diff --git a/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.i18n.yaml b/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.i18n.yaml
index 81fd019718..9ffbc53991 100644
--- a/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.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 .agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.md
-2026-08-27-web-at-mention-discovery-and-row-content.md: ae27f98b07d7a837e095f95129b355770fc8ac02
-2026-08-27-web-at-mention-discovery-and-row-content.zh.md: 8569473d1dec28f371ae8cc12ed50081d2642ab4
+2026-08-27-web-at-mention-discovery-and-row-content.md: defe3eaffbfe111b383467354fb21f088c9475c0
+2026-08-27-web-at-mention-discovery-and-row-content.zh.md: 236cefc55f96f7d918e754622ebc7ae3b7759792
diff --git a/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.md b/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.md
index ae27f98b07..defe3eaffb 100644
--- a/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.md
+++ b/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.md
@@ -34,7 +34,7 @@ The zh composer placeholder says `文件或对话`, matching the `对话` sectio
 
 **Fold the missing titles from their logs, memoized per cold log.** Implemented first, then removed in review. It made the first filtered query over a corpus the cache had not covered read those logs — on a 342-session store, roughly 190 of them — to rescue sessions that predate the cache. Correlating that store against the cache's arrival showed why the trade is bad: every session the product writes today gets a checkpoint at creation, `turn/end`, and disposal, and an old session acquires one the first time it is opened. The gap is legacy data that heals on contact, not a shape discovery has to pay for on every keystroke.
 
-**Read a cold session's title through `sessionQuery.observeSession` or `persistence.readFrom`.** Rejected: neither removes the read on the shipped backend. `observeSession` borrows the whole `inspection.events`, and `readFrom` documents that sequential media — JSONL, both encodings — "still parse the whole artifact and skip forward"; the primitive bounds what is returned and refolded, not the physical read.
+**Read a cold session's title through `sessionQuery.observeSession` or a persistence read handle.** Rejected: neither removes the read on the shipped backend. `observeSession` borrows the whole `inspection.events`, and `readFrom` documents that sequential media — JSONL, both encodings — "still parse the whole artifact and skip forward"; the primitive bounds what is returned and refolded, not the physical read.
 
 **Debounce the candidate fetch.** Rejected. The reducer already resets every group to pending on each hit, so a trailing debounce extends the skeleton state and reads as *slower* while typing. With the fold removed, the round trip no longer justifies the timer; keeping the previous rows visible under a new generation is a separate decision with pick-safety consequences, and is not taken here.
 
diff --git a/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.zh.md b/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.zh.md
index 8569473d1d..236cefc55f 100644
--- a/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-27-web-at-mention-discovery-and-row-content.zh.md
@@ -34,7 +34,7 @@ Web e2e 看不到这一切：它的 scaffold 固定使用只含两个会话的
 
 **从日志折叠缺失的标题，并按冷日志记忆化。** 先实现了，评审时移除。它会让缓存尚未覆盖的语料在首次过滤查询时读那些日志——在 342 会话的存储上约 190 份——只为救回早于缓存存在的会话。把该存储与缓存的上线时间对照后可以看出这笔买卖不划算：今天产品写出的每个会话都会在创建、`turn/end` 与销毁三处建立 checkpoint，而旧会话只要被打开一次就会补上。缺口是「一碰即愈」的存量数据，不是发现路径每次击键都该付的形状。
 
-**通过 `sessionQuery.observeSession` 或 `persistence.readFrom` 读冷会话标题。** 否决：在随附后端上两者都消不掉这次读。`observeSession` 借的是完整的 `inspection.events`；而 `readFrom` 的文档写明顺序介质（JSONL 的两种编码）「仍会解析整个产物再向前跳过」——该原语约束的是返回与重折叠的范围，不是物理读。
+**通过 `sessionQuery.observeSession` 或持久化读句柄读冷会话标题。** 否决：在随附后端上两者都消不掉这次读。`observeSession` 借的是完整的 `inspection.events`；而 `readFrom` 的文档写明顺序介质（JSONL 的两种编码）「仍会解析整个产物再向前跳过」——该原语约束的是返回与重折叠的范围，不是物理读。
 
 **给候选拉取加防抖。** 否决。归约器在每次命中时已经把所有分组重置为 pending，因此尾部防抖会延长骨架状态，输入时读起来更慢。折叠成本移除后，往返时间不再值得一个定时器；在新 generation 下保留上一批行是另一个决定，带有误选后果，此处不做。
 
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
index 9d7829716d..fbde7aa853 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.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 .agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
-2026-06-19-drop-mutable-session-summary.md: 73fc99b4d948da90b78d66e801915a2fb38e4749
-2026-06-19-drop-mutable-session-summary.zh.md: 97b1b098489cccfbbfdbd48439d640b554a26c37
+2026-06-19-drop-mutable-session-summary.md: b93566914a490b5054b865e51a8fda21925be1b5
+2026-06-19-drop-mutable-session-summary.zh.md: 9a36ba6f20e38a571099372c47588024cfea4853
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
index 73fc99b4d9..b93566914a 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
@@ -22,7 +22,7 @@ Delete the mutable session summary entirely. `SessionSummary` and the `SessionMe
 
 Anything the summary was meant to provide is **derivable from the append-only log** when a consumer actually needs it (`firstPrompt` = first `user/message`; recency = the last event's `time` or the file mtime) or already lives in the immutable header (`createdAt`, `cwd`). The one thing *not* derivable — a user-*edited* title — had no implementation and is pure YAGNI; it can return as its own log event or header field if a real feature ever needs it.
 
-The removal narrows the public service contract and JSONL on-disk format; the summary was a deliberate forward-looking design, not an accident; and `SessionHeader` stands where the original Agent Note described `SessionMeta`, which is why the summary vanished. It also simplifies the [shared persistence write coordinator](../architecture/2026-06-18-shared-persistence-write-coordinator.md): with no mutable summary, the coordinator needs no `updateSummary` hook, and an out-of-tree provider can reuse the same summary-free orchestration.
+The removal narrows the public service contract and JSONL on-disk format; the summary was a deliberate forward-looking design, not an accident; and `SessionHeader` stands where the original Agent Note described `SessionMeta`, which is why the summary vanished. It also simplified the then-current [shared persistence write coordinator](../../archived/architecture/2026-06-18-shared-persistence-write-coordinator.md): with no mutable summary, that orchestration needed no `updateSummary` hook.
 
 ## No migration
 
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
index 97b1b09848..9a36ba6f20 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 摘要原本要提供的一切，在消费方真正需要时都**可从仅追加日志中派生**（`firstPrompt` = 第一条 `user/message`；近期度 = 最后一个事件的 `time` 或文件 mtime），或者已经存在于不可变 header 中（`createdAt`、`cwd`）。唯一*不可*派生的是用户*手动编辑*的标题，但它从未实现，纯属 YAGNI；如果未来真有功能需要，它可以作为独立的日志事件或 header 字段回归。
 
-这次移除收窄公开服务约定与 JSONL 磁盘格式；摘要是有意为未来设计的结果，而非意外；原 Agent Note 描述 `SessionMeta` 之处由 `SessionHeader` 承担，这就是摘要消失的原因。它还简化了[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.zh.md)：没有可变摘要后，协调器不需要 `updateSummary` 钩子，仓库外 provider 可复用相同的无摘要编排。
+这次移除收窄公开服务约定与 JSONL 磁盘格式；摘要是有意为未来设计的结果，而非意外；原 Agent Note 描述 `SessionMeta` 之处由 `SessionHeader` 承担，这就是摘要消失的原因。它也简化了当时的[共享持久化写入协调器](../../archived/architecture/2026-06-18-shared-persistence-write-coordinator.md)：没有可变摘要后，那套编排不需要 `updateSummary` 钩子。
 
 ## 无需迁移
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.i18n.yaml
similarity index 52%
rename from .agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
rename to .agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.i18n.yaml
index a353fc98ef..f78c98f5a7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
-2026-07-28-load-pre-identity-session-messages.md: 6d022cb4b37345cd61cc9a89c6fc55c19ad402a5
-2026-07-28-load-pre-identity-session-messages.zh.md: 86439337b3c646a72b7584fbf4640799226fc9ca
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.md
+2026-08-27-persistence-export-and-pre-release-trims.md: ed01023023e9d7817b08e275492b7ec244b893a5
+2026-08-27-persistence-export-and-pre-release-trims.zh.md: 1e31a5836c2761c3d6fb5dbb68b30e8691c1fc69
diff --git a/.agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.md b/.agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.md
new file mode 100644
index 0000000000..ed01023023
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.md
@@ -0,0 +1,46 @@
+# Agent Note: Persistence export() and pre-release read-path trims
+
+Status: implemented
+
+English | [中文](2026-08-27-persistence-export-and-pre-release-trims.zh.md)
+
+## Problem
+
+The session-persistence seam is moving to a handle-based API with cross-process ownership (open/read/append/flush/close per session). Before that swap, the old seam carried surfaces the new design drops or replaces, each with its own consumers and tests: a consumer-facing path query (`locate`), a capability-flagged verbatim read (`supportsRawArtifacts` + `readRaw`), ~300 lines of same-version legacy event-shape migration in the coordinator, and a `locate`-based size gate for the session list's cold blank probe. Removing them inside the seam swap would bloat an already large change; removing them first shrinks the core swap to the seam itself.
+
+## Decision
+
+**One verbatim export method.** `SessionPersistence.export(id, signal?)` returns the session's raw artifact (`SessionRawArtifact`: parsed header, logical filename, decoded verbatim text) or `undefined`. The base default resolves `undefined`; JSONL overrides it with the former `readRaw` behavior. `supportsRawArtifacts` and `readRaw` do not exist. The apiproxy ZIP download distinguishes an unsupported backend (session present in `list()` but `export()` undefined → 501) from an absent session (404) by list membership instead of a capability flag. Superseded by the [handle seam](../architecture/2026-08-27-handle-based-session-persistence.md): the WebUI download needs only the logical log, so `export()` was removed entirely and the ZIP route serializes JSONL from a read handle, ending the 501 path.
+
+**No consumer-facing path query.** `locate` is not a service method. `SessionLocation` survives only as refusal diagnostics: the JSONL backend derives the artifact path internally so `SessionFormatUnsupportedError` can point at the raw log a build refused. The three consumer features built on `locate` are removed or degraded, not ported:
+
+- `DSH_SESSION_JSONL` no longer exists; shell-env registers no persistence contributor. The variable was only honest with `compression: 'none'` — the default `.jsonl.zstd` artifact is unreadable from bash.
+- The Claude Code / Codex hook bridges keep `transcript_path` in the wire payload for protocol shape but always send `''` / `null`. Hook scripts could not parse the compressed artifact either.
+- The `locate`-based size gate for the session-controller cold blank probe is deleted. The probe itself runs on stat metadata: the [handle-based seam](../architecture/2026-08-27-handle-based-session-persistence.md)'s `stat()`/`list()` snapshots carry optional `eventCount`/`sizeBytes`, and session-controller bounds the probe with `coldBlankProbeMaxEvents`/`coldBlankProbeMaxBytes`; a cold session past both thresholds, or on a backend offering neither hint, reports `blank: false` (unknown).
+
+**Legacy event-shape migration is deleted.** Reads validate current v0 records only. Retired event types (`steering/message`, `mode/set`, `request/header-delta`) refuse through the read-side vocabulary gate as `SessionFormatUnsupportedError`. Pre-identity message payloads and the `request/header` `fallback` reason refuse through session validation — surfaced as `SessionPersistenceCorruptionError` on the load/inspect path and as the plain validation error on `readFrom`. Pre-react-loop turn envelopes have no validator: a stale `turn/start.trigger` field and the coarse `aborted`/`disposed` turn-end reasons load unprojected as extension-shaped data, the documented merge-extensible fall-through that the contract test "preserves extension turn/end reasons outside the closed reason set" pins. This consolidates and supersedes the pre-identity-message and pre-react-loop import notes; their record is preserved below.
+
+## Consolidated record of the deleted same-version imports
+
+Two shipped read-side imports existed because message identity (2026-07) and the react-loop refactor (2026-08) changed durable payloads without bumping `SESSION_FORMAT_VERSION`: the coordinator normalized four exact pre-identity message payloads (minting deterministic `legacy-message:<id>:<seq>` identities, with tool-result replacements inheriting their target's id) and projected pre-react-loop shapes (`steering/message` → identified `user/message`, `turn/start.trigger` removal, terminal-reason mapping including a persistence-only `{ kind: 'legacy' }` aborted cause). Both were read-only, exact-shape, and deliberately not a general v0 compatibility layer; their rejected alternatives were stranding first-party sessions, rewriting stored logs in place (violates append-only), and minting unstable identities.
+
+They no longer justify their surface: no tagged release exists, the covered logs are months-old development artifacts, and the mechanism cost ~300 coordinator lines, per-event normalization on every read, a `readFrom` whole-prefix fallback for suffix reads, and fixture suites in three backends. The capability given up: pre-identity logs refuse to load (loudly, with the raw-log path in the refusal) instead of resuming, and pre-react-loop logs either refuse (when they carry the retired `steering/message` type) or load with their stale turn-envelope fields passed through instead of projected to current shapes. Reintroduction condition: after the first tagged release, a durable format change bumps `SESSION_FORMAT_VERSION` and ships an explicit migration under the version gate — never another same-version exact-shape exception. Absence is verified by the vocabulary-refusal tests in the coordinator contract and backend specs.
+
+## Alternatives considered
+
+**Keep `locate` as (or move it to) a separate export-location service.** Rejected: all three path consumers are only functional with compression disabled, so the seam would preserve a half-broken feature; verbatim access needs are served by `export()`.
+
+**Keep the `supportsRawArtifacts` capability flag beside `export()`.** Rejected: `undefined` plus a list-membership check carries the same information with one seam member instead of three.
+
+**Keep the migrations until the first tagged release.** Rejected: the pre-release stance ("remove at the first tagged release") already refuses old on-disk formats everywhere else; the migrations' only beneficiaries are development-era logs.
+
+## Consequences
+
+The seam ahead of the handle refactor is smaller: one export method, no path query, no capability flag, and a coordinator without migration tables. The costs are recorded degradations: hook payload `transcript_path` is never populated (a durable consumer gap in both hook bridge READMEs), the session list marks never-opened cold sessions blank only within the snapshot-metadata probe thresholds, and development-era logs written before the react-loop refactor refuse to load. The 501/404 split for ZIP export costs one `list()` call on the undefined-export path only.
+
+## Related
+
+- [Retain ignorable external session events](../architecture/2026-08-30-retain-ignorable-external-session-events.md) — owns the read-side-only unknown-type gate this change leans on.
+- [Session persistence as an abstract service](../architecture/2026-06-14-session-persistence.md) — owns the seam these trims shrink.
+- [Zstandard JSONL session logs](../architecture/2026-07-19-zstandard-jsonl-session-logs.md) — owns the frame container these reads and appends flow through.
+- [Session identity and log location](../feature/2026-07-10-agent-session-identity-and-log-location.md) — partially superseded: its `DSH_SESSION_ID` and shell-env registry decisions stand; its `locate`/`DSH_SESSION_JSONL`/`transcript_path` decisions are removed here.
diff --git a/.agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md b/.agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md
new file mode 100644
index 0000000000..1e31a5836c
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-27-persistence-export-and-pre-release-trims.zh.md
@@ -0,0 +1,46 @@
+# Agent Note: 持久化 export() 与预发布读取路径精简
+
+Status: implemented
+
+[English](2026-08-27-persistence-export-and-pre-release-trims.md) | 中文
+
+## 问题
+
+会话持久化 seam 正在迁移到基于句柄、具备跨进程所有权的 API（每个会话的 open/read/append/flush/close）。在这次替换之前，旧 seam 携带着新设计将放弃或替换的多个表面，每个都有自己的消费方与测试：面向消费方的路径查询（`locate`）、由能力标志控制的逐字读取（`supportsRawArtifacts` + `readRaw`）、协调器中约 300 行的同版本 legacy 事件形态迁移，以及会话列表冷空白探测使用的基于 `locate` 的大小门槛。若在 seam 替换中一并移除它们，会让本已庞大的变更进一步膨胀；先移除它们能把核心替换缩小到 seam 本身。
+
+## 决策
+
+**单一逐字导出方法。**`SessionPersistence.export(id, signal?)` 返回该会话的原始产物（`SessionRawArtifact`：解析后的 header、逻辑文件名、解码后的逐字文本）或 `undefined`。基类默认解析为 `undefined`；JSONL 用原先的 `readRaw` 行为覆盖它。`supportsRawArtifacts` 与 `readRaw` 不复存在。apiproxy 的 ZIP 下载通过 list 成员关系而非能力标志区分不受支持的后端（会话存在于 `list()` 中但 `export()` 为 undefined → 501）与不存在的会话（404）。已被[句柄 seam](../architecture/2026-08-27-handle-based-session-persistence.zh.md)取代：WebUI 下载只需要逻辑日志，因此 `export()` 被整体移除，ZIP 路由改为从读句柄序列化 JSONL，501 路径随之终结。
+
+**不提供面向消费方的路径查询。**`locate` 不是服务方法。`SessionLocation` 仅作为拒绝诊断保留：JSONL 后端在内部推导工件路径，使 `SessionFormatUnsupportedError` 能指向构建所拒绝的原始日志。基于 `locate` 构建的三项消费方功能被移除或降级，而非移植：
+
+- `DSH_SESSION_JSONL` 不复存在；shell-env 不再注册持久化贡献方。该变量只有在 `compression: 'none'` 时才是诚实的——默认的 `.jsonl.zstd` 产物无法从 bash 读取。
+- Claude Code／Codex 钩子桥接层为保持协议格式，仍在线上 payload 中保留 `transcript_path`，但始终发送 `''`／`null`。钩子脚本同样无法解析压缩产物。
+- session-controller 冷空白探测中基于 `locate` 的大小门槛被删除。探测本身运行在 stat 元数据之上：[基于句柄的 seam](../architecture/2026-08-27-handle-based-session-persistence.zh.md) 的 `stat()`/`list()` 快照携带可选的 `eventCount`/`sizeBytes`，session-controller 以 `coldBlankProbeMaxEvents`/`coldBlankProbeMaxBytes` 限定探测；超过两个阈值的冷会话，或位于两种提示都不提供的后端上的冷会话，报告 `blank: false`（未知）。
+
+**删除 legacy 事件形态迁移。**读取只校验当前 v0 记录。已废弃的事件类型（`steering/message`、`mode/set`、`request/header-delta`）经由读取侧词汇门禁以 `SessionFormatUnsupportedError` 拒绝。消息标识机制之前的消息 payload 与 `request/header` 的 `fallback` 原因经由会话校验拒绝——在 load/inspect 路径上表现为 `SessionPersistenceCorruptionError`，在 `readFrom` 上表现为普通校验错误。react-loop 重构之前的轮次 envelope 没有校验器：过时的 `turn/start.trigger` 字段与粗粒度的 `aborted`/`disposed` 轮次结束原因会作为扩展形态数据不经投影地加载，这正是约定测试 "preserves extension turn/end reasons outside the closed reason set" 所钉住的、有文档记载的可合并扩展 fall-through。此举合并并取代了 pre-identity-message 与 pre-react-loop 两份导入 Note；其记录保存在下文。
+
+## 已删除的同版本导入的合并记录
+
+曾存在两个已上线的读取侧导入，因为消息标识机制（2026-07）与 react-loop 重构（2026-08）在未升级 `SESSION_FORMAT_VERSION` 的情况下改变了持久 payload：协调器会归一化四种精确的 pre-identity 消息 payload（铸造确定性的 `legacy-message:<id>:<seq>` 标识，工具结果替换项继承其目标的 id），并投影 pre-react-loop 形态（`steering/message` → 带标识的 `user/message`、移除 `turn/start.trigger`、终止原因映射——包括仅存在于持久化中的 `{ kind: 'legacy' }` aborted 原因）。二者都是只读、精确形态匹配，并且有意不构成通用的 v0 兼容层；当时被否决的替代方案是弃置第一方会话、就地改写已存储日志（违反仅追加）以及铸造不稳定的标识。
+
+它们已不足以支撑自身的表面：尚无任何已打标签的发布，所覆盖的日志是数月前的开发期产物，而该机制的代价是协调器约 300 行代码、每次读取的逐事件归一化、后缀读取时 `readFrom` 回退到整个前缀，以及三个后端中的 fixture（测试前置数据）套件。放弃的能力是：pre-identity 日志会拒绝加载（明确报错，并在拒绝信息中给出原始日志路径），而不是继续恢复；pre-react-loop 日志则要么被拒绝（当其携带已废弃的 `steering/message` 类型时），要么在加载时把过时的轮次 envelope 字段原样透传，而不是投影为当前形态。重新引入条件：在第一个已打标签的发布之后，持久格式变更升级 `SESSION_FORMAT_VERSION` 并在版本门禁之下提供显式迁移——绝不再开一个同版本精确形态的例外。协调器约定与后端 spec 中的词汇拒绝测试验证该机制确实不存在。
+
+## 考虑过的替代方案
+
+**保留 `locate`（或将其移入独立的导出位置服务）。**不予采用：三个路径消费方都只有在禁用压缩时才可用，seam 会因此保留一个半失效的功能；逐字访问需求已由 `export()` 满足。
+
+**在 `export()` 之外保留 `supportsRawArtifacts` 能力标志。**不予采用：`undefined` 加上 list 成员检查携带相同的信息，却只需一个 seam 成员而非三个。
+
+**把迁移保留到第一个已打标签的发布。**不予采用：预发布立场（「在第一个已打标签的发布时移除」）已在其他所有地方拒绝旧的磁盘格式；这些迁移的唯一受益者是开发期日志。
+
+## 后果
+
+句柄重构之前的 seam 更小：一个导出方法、没有路径查询、没有能力标志，以及不含迁移表的协调器。代价是已记录在案的降级：钩子 payload 的 `transcript_path` 永远不会被填充（两个钩子桥接层 README 中记录的持久消费方缺口）；会话列表只在快照元数据探测阈值之内才把从未打开过的冷会话标记为空白；react-loop 重构之前写入的开发期日志会拒绝加载。ZIP 导出的 501/404 区分只在 `export()` 为 undefined 的路径上多一次 `list()` 调用。
+
+## 相关资料
+
+- [保留可忽略的外部会话事件](../architecture/2026-08-30-retain-ignorable-external-session-events.zh.md)——拥有本变更所依赖的仅读取侧未知类型门禁。
+- [会话持久化作为抽象服务](../architecture/2026-06-14-session-persistence.zh.md)——拥有本次精简所缩小的 seam。
+- [Zstandard JSONL 会话日志](../architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md)——拥有这些读取与追加流经的帧容器。
+- [会话标识与日志位置](../feature/2026-07-10-agent-session-identity-and-log-location.zh.md)——部分被取代：其 `DSH_SESSION_ID` 与 shell-env 注册表决策仍然有效；其 `locate`/`DSH_SESSION_JSONL`/`transcript_path` 决策在此移除。
diff --git a/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.i18n.yaml
index e697040ad9..d66d1e346d 100644
--- a/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.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 .agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.md
-2026-08-30-jsonl-only-session-persistence.md: f21fb89e3747dffd043d42ace2c05bbe521f3069
-2026-08-30-jsonl-only-session-persistence.zh.md: 4100e576ccdcd46443e12a22cfec6dd3d3495317
+2026-08-30-jsonl-only-session-persistence.md: 6282544a6132ed66eab3b1a174edbf9b67e1c8ad
+2026-08-30-jsonl-only-session-persistence.zh.md: 4785ff72d599404fa6d6b897fda520c761150b11
diff --git a/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.md b/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.md
index f21fb89e37..6282544a61 100644
--- a/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.md
+++ b/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.md
@@ -12,7 +12,7 @@ The SQLite full-text Session-query provider is not an alternative authoritative
 
 ## Decision
 
-`@deepseek-ai/dsh-session-persistence-jsonl` is the sole first-party implementation of `ctx.sessionPersistence`. The abstract Service Definition and `PersistenceCoordinator` remain backend-neutral so an out-of-tree provider can implement the same service, but the repository owns and tests one authoritative physical Session format.
+`@deepseek-ai/dsh-session-persistence-jsonl` is the sole first-party implementation of `ctx.sessionPersistence`. The abstract Service Definition remains backend-neutral so an out-of-tree provider can implement the same service, but the repository owns and tests one authoritative physical Session format.
 
 The `@deepseek-ai/dsh-session-persistence-sqlite` package, its schema resources, backend-specific tests, configuration surface, and Windows differential lane are absent. Cross-package persistence tests use the real JSONL provider or an owner-local fake. `@deepseek-ai/dsh-session-query-sqlite` remains the optional FTS5 query provider over a separate rebuildable database, and `@deepseek-ai/dsh-storage-sqlite` remains the generic domain-KV provider.
 
diff --git a/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.zh.md b/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.zh.md
index 4100e576cc..4785ff72d5 100644
--- a/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.zh.md
@@ -12,7 +12,7 @@ SQLite 全文 Session-query provider 不是另一种权威 store。它通过 `ct
 
 ## Decision
 
-`@deepseek-ai/dsh-session-persistence-jsonl` 是 `ctx.sessionPersistence` 唯一的 first-party 实现。抽象 Service Definition 与 `PersistenceCoordinator` 保持后端无关，使仓库外 provider 仍可实现同一服务，但仓库只拥有并测试一种权威 Session 物理格式。
+`@deepseek-ai/dsh-session-persistence-jsonl` 是 `ctx.sessionPersistence` 唯一的 first-party 实现。抽象 Service Definition 保持后端无关，使仓库外 provider 仍可实现同一服务，但仓库只拥有并测试一种权威 Session 物理格式。
 
 仓库不再包含 `@deepseek-ai/dsh-session-persistence-sqlite` package、其 schema resource、后端专用测试、配置接口与 Windows differential lane。跨 package 持久化测试使用真实 JSONL provider 或 owner-local fake。`@deepseek-ai/dsh-session-query-sqlite` 继续作为可选 FTS5 query provider 使用独立、可重建的数据库，`@deepseek-ai/dsh-storage-sqlite` 继续作为通用 domain-KV provider。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
index 1862475aae..e16b25b55b 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.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 .agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md
-2026-07-29-durable-last-activity-index.md: e391b5cd0281c66221d9ca96920a294c98c7e16f
-2026-07-29-durable-last-activity-index.zh.md: 453e8a772d2ad8fe4ab2affcfd7049d86da258c5
+2026-07-29-durable-last-activity-index.md: 8022bb50530dc565813ba4f4c07342b348125eed
+2026-07-29-durable-last-activity-index.zh.md: be84ad73ba9f685bdff7cd80a4ed6fdb46006588
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md
index e391b5cd02..8022bb5053 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md
@@ -10,7 +10,7 @@ A cold (persisted, unattached) session has no authoritative stored answer to "wh
 
 The gateway previously used JSONL artifact mtime when available. mtime answers a different question: when the artifact was last written. Every durable write refreshes it, including a truncate-repair of a torn tail, synthetic closers that balance an interrupted turn, and the [`session/end-seed` boundary](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md) appended during pickup. That approximation promoted a Session merely because it was opened. The [bounded cold blank verification](../../implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.md) removed mtime ordering and accepted the cache's conservative "too old" failure direction as an interim tradeoff.
 
-An attached summary can fold the live event log and select the latest human-authored `user/message`, but the cold path deliberately does not read large logs. Reading every log to compute `updatedAt` would make `list()` scale with total conversation bytes rather than Session count. The 1 KiB cold read used for metadata verification makes eligible small-artifact recency exact, but it does not make large-log ordering exact.
+An attached summary can fold the live event log and select the latest human-authored `user/message`, but the cold path deliberately reads no logs: cold summaries come from the projection cache alone, so cold recency is only as fresh as the cache.
 
 Making cold ordering exact remains a durable-format decision, which is why it is scoped here rather than in the gateway workaround.
 
@@ -58,7 +58,7 @@ Three questions must be answered before implementation, and none of them is sett
 
 ## Related
 
-- [Bounded cold blank verification](../../implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.md) — removes mtime ordering, defines the interim projection-cache fallback, and limits direct cold reads to small-artifact metadata verification.
+- [Bounded cold blank verification](../../implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.md) — removes mtime ordering and defines the interim cache-only cold summary this proposal would make exact.
 - [The end-seed log boundary](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md) — one of the non-prompt writes that made mtime unsuitable.
 - [Session persistence](../../implemented/architecture/2026-06-14-session-persistence.md) — the append-only and never-rewrite invariants that rule out a mutable JSONL header field.
-- [Shared persistence write coordinator](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md) — the append path a stored field would hook into.
+- [Handle-based session persistence](../../implemented/architecture/2026-08-27-handle-based-session-persistence.md) — the write-handle append path a stored field would hook into.
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
index 453e8a772d..be84ad73ba 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
@@ -10,7 +10,7 @@ Status: proposed
 
 网关以前会在可用时采用 JSONL 产物的 mtime。mtime 回答的是另一件事：这份产物上次是什么时候被写入。每一次持久写入都会刷新它，包括对撕裂尾部的截断修复、平衡中断轮次的合成 closer，以及拾起时追加的 [`session/end-seed` 边界](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md)。这套近似会让 Session 仅仅因为被打开就提升排序。[有界冷空白验证](../../implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.zh.md)移除了 mtime 排序，并把 cache 保守的「过旧」错误方向作为现阶段取舍。
 
-已附加摘要可以折叠实时事件日志并选择最新的真人 `user/message`，但冷路径有意不读取大日志。为计算 `updatedAt` 而读取每一份日志，会让 `list()` 的开销随对话总字节数而非 Session 数量增长。用于 metadata 验证的 1 KiB 冷读取可以让符合条件的小产物得到精确的最近时间，但不能让大日志的排序精确。
+已附加摘要可以折叠实时事件日志并选择最新的真人 `user/message`，但冷路径有意不读取任何日志：冷摘要只来自 projection cache，因此冷最近时间的新旧只取决于 cache。
 
 让冷排序变得精确仍是一项持久格式决策，因此其范围留在本文，而不是网关 workaround 中。
 
@@ -58,7 +58,7 @@ Status: proposed
 
 ## 相关
 
-- [有界冷空白验证](../../implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.zh.md)——移除 mtime 排序，定义 projection cache 的过渡回退，并把直接冷读取限制为小产物 metadata 验证。
+- [有界冷空白验证](../../implemented/bug-fix/2026-08-13-bounded-cold-blank-verification.zh.md)——移除 mtime 排序，并定义了本提案将使之精确的、仅依赖 cache 的过渡冷摘要。
 - [种子结束日志边界](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md)——让 mtime 不适用的非 prompt 写入之一。
 - [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.zh.md)——仅追加与绝不重写这两条不变式，正是它们排除了可变的 JSONL header 字段。
-- [共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md)——一个已存储字段将挂入的那条追加路径。
+- [基于句柄的会话持久化](../../implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md)——一个已存储字段将挂入的那条写句柄追加路径。
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.i18n.yaml
index 2b387384b3..eb78f7fe94 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.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 .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.md
-2026-07-04-prune-dead-core-spine-api.md: 554244a67cdbe26d90aca1b4bd7a61e1ca0dc7ec
-2026-07-04-prune-dead-core-spine-api.zh.md: a0a2520ecf31a4626b629779ca07b7debf8d062d
+2026-07-04-prune-dead-core-spine-api.md: b26a39ef8d18306b9d42894eaab4925c69c37c8b
+2026-07-04-prune-dead-core-spine-api.zh.md: b72e902504f66fc48947ea71c75a257ad724e643
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.md
index 554244a67c..b26a39ef8d 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.md
@@ -20,7 +20,6 @@ The production corpus is `packages/*/*/src`, example sources/config, and runtime
 | ACP `agentOptions` root export | The helper has only same-file and ACP-test consumers; the sole outside-package production consumer mounts the plugin namespace. | Keep `name`, `inject`, `Config`, `AcpConfig`, and `apply`; make `agentOptions` source-private and test it through bridge behavior. |
 | `providerWording` and `completedTurnPrefix` root exports | Each has one same-package production caller; only the balanced-prefix helper has a same-package white-box test. | Make them source-private and test provider behavior. |
 | `depthOf`, `SubagentDepthError`, `waitForExit`, and `exitsWithin` root exports | Production subagent backends consume the in-process runner and subprocess construction/disposal helpers, not these enforcement/test internals. `SENSITIVE_ENV_PATTERN` is excluded because the SDK helper applies it to caller-supplied environments. | Keep depth and exit behavior but make the remaining helpers and error source-private; test through spawn and disposal. Keep the shared credential pattern public. |
-| `PersistenceCoordinator.inits`, provider `inits` accessors, `seedCoversPrefix`, and `assertSerializable` | The accessors exist for white-box tests; `seedCoversPrefix` has no outside production importer; `assertSerializable` has no production caller and duplicates the coordinator append boundary's lossless snapshot. | Observe initialization through `session/flush`, make `seedCoversPrefix` source-private, and delete `assertSerializable`. Keep the JSONL provider and `SessionHeader`. |
 | `LlmError.status` and replay status | Adapters/replay populate it, but production branches on stable error code/message and never reads raw status. | Remove the unread field and replay plumbing while preserving error classification. |
 | `BlockAssembler.push()` return value | Both production callers ignore the returned completed block. | Return `void`; keep the deliberately public `blocks()`/`message()` contract. |
 | `compactRegion`'s separate `session` argument | The fixed caller passes the same object already present as `agent.session`; the model-visible mount API can also call the method, but accepting two identities permits a mounted plugin to provide an incoherent pair. | Keep the manual-region API while deliberately narrowing it to `agent.session` as the one source of truth. |
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.zh.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.zh.md
index a0a2520ecf..b72e902504 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.zh.md
@@ -20,7 +20,6 @@ Status: proposed
 | ACP 的 `agentOptions` 根导出 | 该辅助函数只有同文件和 ACP 测试消费方；唯一的包外生产消费方挂载的是插件命名空间。 | 保留 `name`、`inject`、`Config`、`AcpConfig` 和 `apply`；将 `agentOptions` 改为源码私有，通过桥接层行为测试。 |
 | `providerWording` 与 `completedTurnPrefix` 根导出 | 各有一个同包生产调用者；只有 balanced-prefix 辅助函数有一个同包白盒测试。 | 改为源码私有，测试提供方行为。 |
 | `depthOf`、`SubagentDepthError`、`waitForExit` 与 `exitsWithin` 根导出 | 生产 subagent 后端消费的是进程内 runner 和子进程构造/dispose（资源释放）辅助函数，而非这些强制机制和测试内部实现。`SENSITIVE_ENV_PATTERN` 不在其中，因为 SDK helper 会将它应用于调用方传入的环境。 | 保留深度与退出行为，但将剩余辅助函数和 error 改为源码私有；通过 spawn 和 dispose 测试。保持共享凭据正则公开。 |
-| `PersistenceCoordinator.inits`、provider `inits` 访问器、`seedCoversPrefix` 与 `assertSerializable` | 访问器为白盒测试而存在；`seedCoversPrefix` 没有包外生产导入者；`assertSerializable` 没有生产调用者，且与 coordinator append 边界的无损快照重复。 | 通过 `session/flush` 观察初始化，将 `seedCoversPrefix` 改为源码私有，删除 `assertSerializable`。保留 JSONL provider 与 `SessionHeader`。 |
 | `LlmError.status` 与回放 status | 适配器/回放填充它，但生产分支基于稳定的错误码/消息判断，从不读取原始 status。 | 移除未读字段和回放管道，保留错误分类。 |
 | `BlockAssembler.push()` 返回值 | 两个生产调用者都忽略返回的已完成块。 | 返回 `void`；保留有意公开的 `blocks()`/`message()` 约定。 |
 | `compactRegion` 的独立 `session` 参数 | 固定调用方传入的对象就是 `agent.session` 中已有的对象；模型可见的 mount API 也可以调用该方法，但同时接受两个独立对象，会让挂载的插件传入不一致的组合。 | 保留手动 region API，同时有意将其收窄为以 `agent.session` 为唯一真源。 |
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
index 8c9988f86a..47d6125e0d 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.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 .agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
-2026-06-20-fold-session-persistence-interface.md: 3079e9495cdbf4dd698fccc65d3c2fdada29cfc1
-2026-06-20-fold-session-persistence-interface.zh.md: 3eff594a0d2377c52bbee54a1d7e3b26a015078e
+2026-06-20-fold-session-persistence-interface.md: 58c6aa8f5b3b77f146e18d285ebf3fe1e36b0778
+2026-06-20-fold-session-persistence-interface.zh.md: 9fb53d16fced3d17ee0a76a05df04628ac9d8c95
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
index 3079e9495c..58c6aa8f5b 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
@@ -22,7 +22,7 @@ The implementing PR should update the [capability seams](../../implemented/archi
 - `dsh-session` exports the persistence service type, coordinator, and contract helpers.
 - JSONL and SQLite backend packages depend on `dsh-session` directly.
 - `agent-loop` resume uses the session-owned service key.
-- [Session persistence](../../implemented/architecture/2026-06-14-session-persistence.md), [shared persistence write coordinator](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md), and [package docs](../../../../packages/session/session-persistence/README.md) explain why backend implementations remain separate.
+- [Session persistence](../../implemented/architecture/2026-06-14-session-persistence.md), [handle-based session persistence](../../implemented/architecture/2026-08-27-handle-based-session-persistence.md), and [package docs](../../../../packages/session/session-persistence/README.md) explain why backend implementations remain separate.
 
 ## What we give up
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
index 3eff594a0d..9fb53d16fc 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
@@ -22,7 +22,7 @@ Status: rejected — 独立的持久化 Service Definition 包是持久化能力
 - `dsh-session` 导出持久化服务类型、协调器和约定辅助工具。
 - JSONL 和 SQLite 后端包直接依赖 `dsh-session`。
 - `agent-loop` 的恢复功能使用会话包拥有的服务键。
-- [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.zh.md)、[共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md)与[包文档](../../../../packages/session/session-persistence/README.zh.md)说明后端实现为何仍保持独立。
+- [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.zh.md)、[基于句柄的会话持久化](../../implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md)与[包文档](../../../../packages/session/session-persistence/README.zh.md)说明后端实现为何仍保持独立。
 
 ## 放弃了什么
 
diff --git a/.agents/skills/dsh-find-simplifications/SKILL.md b/.agents/skills/dsh-find-simplifications/SKILL.md
index 9416a511a3..777a1b08f6 100644
--- a/.agents/skills/dsh-find-simplifications/SKILL.md
+++ b/.agents/skills/dsh-find-simplifications/SKILL.md
@@ -11,7 +11,7 @@ This skill helps turn a broad "find things to simplify" request into evidence-ba
 
 - Read `AGENTS.md`, especially the pre-release stance and the conventions (including the tests-are-not-golden-truth and Agent Notes-are-not-golden-truth doctrines), plus [docs/defensive-patterns.md](../../../docs/defensive-patterns.md) and [docs/testing.md](../../../docs/testing.md).
 - Skim [docs/architecture.md](../../../docs/architecture.md) before judging anything under `packages/`; simplifications that fight the service map or event taxonomy need extra evidence.
-- Use the Agent Note tree and its [rules](../../notes/README.md) to understand intentional architecture. The most relevant implemented examples are [drop mutable session summary](../../notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md), [shared persistence write coordinator](../../notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md), [JSONL-only first-party Session persistence](../../notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.md), [capability seams](../../notes/implemented/architecture/2026-06-13-capability-seams.md), and the twin-adapter Agent Notes.
+- Use the Agent Note tree and its [rules](../../notes/README.md) to understand intentional architecture. The most relevant implemented examples are [drop mutable session summary](../../notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md), [handle-based session persistence](../../notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md), [JSONL-only first-party Session persistence](../../notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.md), [capability seams](../../notes/implemented/architecture/2026-06-13-capability-seams.md), and the twin-adapter Agent Notes.
 - Treat dual LLM adapters as intentional by default. Session persistence is different: JSONL is the sole first-party provider, while the backend-neutral service remains available to out-of-tree providers. Do not propose deleting an LLM twin or the persistence seam as "low effort" unless the user explicitly overrides that constraint. Removing an unused method or hook inside a protected seam can still be valid if it does not collapse the protected design.
 
 ## What Counts As A Strong Candidate
diff --git a/apps/cli/tests/profiles/headless/tests/coding-task.e2e.ts b/apps/cli/tests/profiles/headless/tests/coding-task.e2e.ts
index f6155102e3..312d712575 100644
--- a/apps/cli/tests/profiles/headless/tests/coding-task.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/coding-task.e2e.ts
@@ -55,7 +55,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('coding task: fix a failing test
     expect(before.status).not.toBe(0)
 
     ctx = await codingHarness(workdir, { persona: SYSTEM_PROMPT })
-    const agent = ctx.agentLoop.create(SessionId('e2e-task'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    const agent = await ctx.agentLoop.create(SessionId('e2e-task'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
 
     agent.followup(createUserMessage({
       content: [{
diff --git a/apps/cli/tests/profiles/headless/tests/compaction.e2e.ts b/apps/cli/tests/profiles/headless/tests/compaction.e2e.ts
index 7b22be2958..5dfc42f97d 100644
--- a/apps/cli/tests/profiles/headless/tests/compaction.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/compaction.e2e.ts
@@ -45,7 +45,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
       },
       persistenceRoot: join(workdir, '.sessions'),
     })
-    const agent = ctx.agentLoop.create(SessionId('e2e-compaction'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    const agent = await ctx.agentLoop.create(SessionId('e2e-compaction'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
 
     agent.followup(createUserMessage({
       content: [{
diff --git a/apps/cli/tests/profiles/headless/tests/full-loop.e2e.ts b/apps/cli/tests/profiles/headless/tests/full-loop.e2e.ts
index cf55e35d28..01c8e65b99 100644
--- a/apps/cli/tests/profiles/headless/tests/full-loop.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/full-loop.e2e.ts
@@ -29,7 +29,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('full loop: real model + real bas
   it('runs a bash command on request and reports its output', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-full-loop-e2e-'))
     ctx = await codingHarness(workdir, { persona: SYSTEM_PROMPT })
-    const agent = ctx.agentLoop.create(SessionId('e2e-loop'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    const agent = await ctx.agentLoop.create(SessionId('e2e-loop'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'Run `echo e2e-ok` with the bash tool and tell me its exact output.' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
diff --git a/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts b/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts
index fba29b93b3..8ee3affb8a 100644
--- a/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts
@@ -356,7 +356,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('PTC mode: real model writes a pr
   it('collapses the wire tool list to [run_code], bridges sub-calls, and returns curated output', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-ptc-e2e-'))
     ctx = await ptcModeHarness(workdir)
-    const agent = ctx.agentLoop.create(SessionId('e2e-ptc'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    const agent = await ctx.agentLoop.create(SessionId('e2e-ptc'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
 
     agent.followup(createUserMessage({
       content: [{
diff --git a/apps/cli/tests/profiles/headless/tests/semantic-checkpoint.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/semantic-checkpoint.expected.e2e.ts
index 498a4e9499..587c4fda82 100644
--- a/apps/cli/tests/profiles/headless/tests/semantic-checkpoint.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/semantic-checkpoint.expected.e2e.ts
@@ -5,8 +5,9 @@ import { Context } from '@deepseek-ai/cordis'
 import { normalizeSessionSnapshot, type NormalizeContext } from '@deepseek-ai/dsh-session-snapshot'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { createUserMessage, ToolCallId , createMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionSeq, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionSeq, SESSION_FORMAT_VERSION, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import { logPath } from '../../../../../../packages/session/session-persistence-jsonl/src/format.ts'
 import { describe, expect, it } from 'vitest'
 
 const fixtureDir = join(dirname(fileURLToPath(import.meta.url)), 'expected/semantic-checkpoint')
@@ -22,14 +23,13 @@ const task = 'Continue safely from the interrupted operation.'
 
 async function seedInterruptedSession(root: string, cwd: string): Promise<string> {
   const ctx = new Context()
-  await ctx.plugin(SessionStore)
   await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   const meta: SessionHeader = {
     version: SESSION_FORMAT_VERSION,
     id: sessionId,
     createdAt: 1,
-    cwd,
     isSeeded: false,
+    cwd,
     delegationDepth: 0,
   }
   const events: SessionEvent[] = [
@@ -70,11 +70,10 @@ async function seedInterruptedSession(root: string, cwd: string): Promise<string
     },
   ]
   try {
-    await ctx.sessionPersistence.create(meta)
-    await ctx.sessionPersistence.append(sessionId, events)
-    const location = ctx.sessionPersistence.locate(meta)
-    if (location === undefined) throw new Error('JSONL backend did not locate the seeded session')
-    return location.path
+    const handle = await ctx.sessionPersistence.create(meta)
+    await handle.append(events)
+    await handle.close()
+    return logPath(root, meta.cwd, meta.id, 'none')
   } finally {
     await ctx.fiber.dispose()
   }
diff --git a/apps/cli/tests/profiles/headless/tests/session-format-guard.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/session-format-guard.expected.e2e.ts
index a1f5d0ff9e..2f26d0c8e6 100644
--- a/apps/cli/tests/profiles/headless/tests/session-format-guard.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/session-format-guard.expected.e2e.ts
@@ -10,7 +10,7 @@ import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context } from '@deepseek-ai/cordis'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import SessionStore, {
+import {
   SESSION_FORMAT_VERSION,
   SessionId,
   SessionSeq,
@@ -18,6 +18,7 @@ import SessionStore, {
   type SessionHeader,
 } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import { logPath } from '../../../../../../packages/session/session-persistence-jsonl/src/format.ts'
 import { describe, expect, it } from 'vitest'
 
 const fixtureDir = join(dirname(fileURLToPath(import.meta.url)), 'expected/workspace-context-resume/offline-edit')
@@ -31,15 +32,13 @@ const sessionId = SessionId('workspace-context-resume')
 /** Persist one session with the given header version and events, returning its log path. */
 async function seedSession(root: string, cwd: string, version: number, events: SessionEvent[]): Promise<string> {
   const ctx = new Context()
-  await ctx.plugin(SessionStore)
   await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   const meta: SessionHeader = { version, id: sessionId, createdAt: 1, cwd, isSeeded: false }
   try {
-    await ctx.sessionPersistence.create(meta)
-    await ctx.sessionPersistence.append(sessionId, events)
-    const location = ctx.sessionPersistence.locate(meta)
-    if (location === undefined) throw new Error('JSONL backend did not locate the seeded session')
-    return location.path
+    const handle = await ctx.sessionPersistence.create(meta)
+    await handle.append(events)
+    await handle.close()
+    return logPath(root, meta.cwd, meta.id, 'none')
   } finally {
     await ctx.fiber.dispose()
   }
diff --git a/apps/cli/tests/profiles/headless/tests/subagent-diagnostic.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/subagent-diagnostic.expected.e2e.ts
index e3c80f9219..13e1e75810 100644
--- a/apps/cli/tests/profiles/headless/tests/subagent-diagnostic.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/subagent-diagnostic.expected.e2e.ts
@@ -11,7 +11,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { normalizeSessionSnapshot, type NormalizeContext } from '@deepseek-ai/dsh-session-snapshot'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionSeq, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionSeq, SESSION_FORMAT_VERSION, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { describe, expect, it } from 'vitest'
 
@@ -33,14 +33,13 @@ const task = 'Call list_agents once and report what it shows.'
  */
 async function seedDescriptorlessChild(root: string, cwd: string): Promise<void> {
   const ctx = new Context()
-  await ctx.plugin(SessionStore)
   await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   const parentMeta: SessionHeader = {
     version: SESSION_FORMAT_VERSION,
     id: parentId,
     createdAt: 1,
-    cwd,
     isSeeded: false,
+    cwd,
     delegationDepth: 0,
   }
   const parentEvents: SessionEvent[] = [
@@ -52,9 +51,9 @@ async function seedDescriptorlessChild(root: string, cwd: string): Promise<void>
     version: SESSION_FORMAT_VERSION,
     id: childId,
     createdAt: 2,
+    isSeeded: false,
     cwd,
     parentSession: parentId,
-    isSeeded: false,
     origin: 'subagent',
     delegationDepth: 1,
   }
@@ -63,10 +62,12 @@ async function seedDescriptorlessChild(root: string, cwd: string): Promise<void>
     { type: 'turn/end', seq: SessionSeq(1), time: 21, data: { turn: 1, reason: { kind: 'interrupted' } } },
   ]
   try {
-    await ctx.sessionPersistence.create(parentMeta)
-    await ctx.sessionPersistence.append(parentId, parentEvents)
-    await ctx.sessionPersistence.create(childMeta)
-    await ctx.sessionPersistence.append(childId, childEvents)
+    const parentHandle = await ctx.sessionPersistence.create(parentMeta)
+    await parentHandle.append(parentEvents)
+    await parentHandle.close()
+    const childHandle = await ctx.sessionPersistence.create(childMeta)
+    await childHandle.append(childEvents)
+    await childHandle.close()
   } finally {
     await ctx.fiber.dispose()
   }
diff --git a/apps/cli/tests/profiles/headless/tests/subagent-inheritance.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/subagent-inheritance.expected.e2e.ts
index 9f9da8707d..5cfe4787c8 100644
--- a/apps/cli/tests/profiles/headless/tests/subagent-inheritance.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/subagent-inheritance.expected.e2e.ts
@@ -10,7 +10,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { normalizeSessionSnapshot, type NormalizeContext } from '@deepseek-ai/dsh-session-snapshot'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionSeq, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionSeq, SESSION_FORMAT_VERSION, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { describe, expect, it } from 'vitest'
 
@@ -29,14 +29,13 @@ const task = 'Delegate the write probe to a subagent.'
 /** Seed a completed parent turn with its read-only policy and current LLM selection. */
 async function seedReadOnlyParent(root: string, cwd: string): Promise<void> {
   const ctx = new Context()
-  await ctx.plugin(SessionStore)
   await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   const meta: SessionHeader = {
     version: SESSION_FORMAT_VERSION,
     id: sessionId,
     createdAt: 1,
-    cwd,
     isSeeded: false,
+    cwd,
     delegationDepth: 0,
   }
   const events: SessionEvent[] = [
@@ -61,8 +60,9 @@ async function seedReadOnlyParent(root: string, cwd: string): Promise<void> {
     { type: 'turn/end', seq: SessionSeq(4), time: 14, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
   try {
-    await ctx.sessionPersistence.create(meta)
-    await ctx.sessionPersistence.append(sessionId, events)
+    const handle = await ctx.sessionPersistence.create(meta)
+    await handle.append(events)
+    await handle.close()
   } finally {
     await ctx.fiber.dispose()
   }
@@ -110,7 +110,7 @@ describe('parent-only override inheritance snapshot', () => {
         )
         expect(childRecords[1]).toMatchObject({
           type: 'sandbox/mode',
-          seq: 0,
+          seq: SessionSeq(0),
           data: { mode: 'read-only', source: 'delegation' },
         })
 
diff --git a/apps/cli/tests/profiles/headless/tests/todo-write.e2e.ts b/apps/cli/tests/profiles/headless/tests/todo-write.e2e.ts
index 5fa792b672..db17d267d4 100644
--- a/apps/cli/tests/profiles/headless/tests/todo-write.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/todo-write.e2e.ts
@@ -27,7 +27,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('todo_write: real model records a
   it('appends a todo/write event with the model-produced task list', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-todo-write-e2e-'))
     ctx = await codingHarness(workdir, { persona: TODO_SYSTEM_PROMPT })
-    const agent = ctx.agentLoop.create(SessionId('e2e-todo'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    const agent = await ctx.agentLoop.create(SessionId('e2e-todo'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
 
     agent.followup(createUserMessage({
       content: [{ type: 'text', text:
diff --git a/apps/cli/tests/profiles/headless/tests/workspace-context-resume.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/workspace-context-resume.expected.e2e.ts
index 2fded92b5b..07fafe4438 100644
--- a/apps/cli/tests/profiles/headless/tests/workspace-context-resume.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/workspace-context-resume.expected.e2e.ts
@@ -11,7 +11,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { normalizeSessionSnapshot, type NormalizeContext } from '@deepseek-ai/dsh-session-snapshot'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore, {
+import {
   SESSION_FORMAT_VERSION,
   SessionId,
   SessionSeq,
@@ -19,6 +19,7 @@ import SessionStore, {
   type SessionHeader,
 } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import { logPath } from '../../../../../../packages/session/session-persistence-jsonl/src/format.ts'
 import { renderWorkspaceContext } from '@deepseek-ai/dsh-agent-instructions'
 import { resolveConfig, workspaceBaselineIdentity } from '@deepseek-ai/dsh-agent-instructions/src/config.ts'
 import { describe, expect, it } from 'vitest'
@@ -47,7 +48,6 @@ async function seedVisibleBaseline(
   options: SeedBaselineOptions = {},
 ): Promise<string> {
   const ctx = new Context()
-  await ctx.plugin(SessionStore)
   await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   const meta: SessionHeader = {
     version: SESSION_FORMAT_VERSION,
@@ -103,11 +103,10 @@ async function seedVisibleBaseline(
     { type: 'turn/end', seq: SessionSeq(3), time: 13, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
   try {
-    await ctx.sessionPersistence.create(meta)
-    await ctx.sessionPersistence.append(sessionId, events)
-    const location = ctx.sessionPersistence.locate(meta)
-    if (location === undefined) throw new Error('JSONL backend did not locate the seeded session')
-    return location.path
+    const handle = await ctx.sessionPersistence.create(meta)
+    await handle.append(events)
+    await handle.close()
+    return logPath(root, meta.cwd, meta.id, 'none')
   } finally {
     await ctx.fiber.dispose()
   }
diff --git a/apps/web/tests/agent-preset-selection.e2e.ts b/apps/web/tests/agent-preset-selection.e2e.ts
index 99437f7f8c..432c34a201 100644
--- a/apps/web/tests/agent-preset-selection.e2e.ts
+++ b/apps/web/tests/agent-preset-selection.e2e.ts
@@ -15,9 +15,8 @@ import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
-import { MessageId } from '@deepseek-ai/dsh-llm'
 import {
-  SESSION_FORMAT_VERSION, SessionId as sessionId, SessionSeq, type SessionHeader, type SessionId,
+  SESSION_FORMAT_VERSION, SessionId as sessionId, type SessionEvent, type SessionHeader, type SessionId,
 } from '@deepseek-ai/dsh-session'
 import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent'
 import {
@@ -94,7 +93,12 @@ function seedLog(): string {
     at(0, { type: 'turn/start', data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user', rpcId: 'seed' } } } }),
     at(1, {
       type: 'user/message',
-      data: { content: [{ type: 'text', text: 'Seeded turn.' }], source: { kind: 'user', rpcId: 'seed' } },
+      data: {
+        id: '00000000-0000-4000-9000-000000000001',
+        role: 'user',
+        content: [{ type: 'text', text: 'Seeded turn.' }],
+        source: { kind: 'user', rpcId: 'seed' },
+      },
       surfaceOp: 'append',
     }),
     at(2, { type: 'session/title', data: { title: 'Seeded turn', messageSeqs: [1], source: { kind: 'fallback' } } }),
@@ -114,29 +118,27 @@ async function seedSubagent(scaffold: WebScaffold, parentId: SessionId): Promise
   const header: SessionHeader = {
     version: SESSION_FORMAT_VERSION,
     id: childId,
+    isSeeded: false,
     createdAt,
     cwd: scaffold.workspaceCwd,
     parentSession: parentId,
-    isSeeded: false,
     origin: 'subagent',
     delegationDepth: 1,
     agentPreset: 'minimal',
   }
-  await scaffold.ctx.sessionPersistence.create(header)
-  await scaffold.ctx.sessionPersistence.append(childId, [
+  const handle = await scaffold.ctx.sessionPersistence.create(header)
+  await handle.append([
     {
       type: 'turn/start',
-      seq: SessionSeq(0),
+      seq: 0,
       time: createdAt,
-      data: { turn: 1 },
+      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
     },
     {
       type: 'user/message',
-      seq: SessionSeq(1),
+      seq: 1,
       time: createdAt + 1,
       data: {
-        id: MessageId(`legacy-message:${childId}:1`),
-        role: 'user',
         content: [{ type: 'text', text: 'Check the session-header action order.' }],
         source: { kind: 'user' },
       },
@@ -144,7 +146,7 @@ async function seedSubagent(scaffold: WebScaffold, parentId: SessionId): Promise
     },
     {
       type: 'subagent/descriptor',
-      seq: SessionSeq(2),
+      seq: 2,
       time: createdAt + 2,
       data: snapshotSubagentDescriptor({
         mode: 'one-shot', provider: 'spawn', label: 'header order probe',
@@ -152,11 +154,12 @@ async function seedSubagent(scaffold: WebScaffold, parentId: SessionId): Promise
     },
     {
       type: 'turn/end',
-      seq: SessionSeq(3),
+      seq: 3,
       time: createdAt + 3,
       data: { turn: 1, reason: { kind: 'completed' } },
     },
-  ])
+  ] as SessionEvent[])
+  await handle.close()
 }
 
 /**
diff --git a/apps/web/tests/cold-blank-session.e2e.ts b/apps/web/tests/cold-blank-session.e2e.ts
deleted file mode 100644
index b9e64960d3..0000000000
--- a/apps/web/tests/cold-blank-session.e2e.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-/** Cold Session list visibility through the shipped compressed JSONL backend. */
-
-import { mkdir, stat } from 'node:fs/promises'
-import { fileURLToPath } from 'node:url'
-import { join } from 'node:path'
-import type { Browser, Page } from 'playwright'
-import { chromium } from 'playwright'
-import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
-import {
-  captureStableAria, compareOrRefreshGolden, launchWebScaffold, seedBlankSession,
-  watchConsole, webSnapshotMode, type WebScaffold,
-} from './scaffold.ts'
-import { newEnglishPage, saveFailureShot } from './support.ts'
-
-const SNAPSHOT_DIR = fileURLToPath(new URL('./expected/cold-blank-session', import.meta.url))
-const SIDEBAR_EXPECTED = join(SNAPSHOT_DIR, 'sidebar.expected.md')
-const MODE = webSnapshotMode()
-const SESSION_ID = 'cold-blank-session-web-e2e'
-const WORKSPACE_NAME = 'cold-blank-workspace'
-
-describe('web e2e: cold blank Session visibility', () => {
-  let scaffold: WebScaffold
-  let browser: Browser
-  let page: Page
-  let tripwire: ReturnType<typeof watchConsole>
-
-  beforeAll(async () => {
-    scaffold = await launchWebScaffold({})
-    const cwd = join(scaffold.workspaceCwd, WORKSPACE_NAME)
-    await mkdir(cwd, { recursive: true })
-    await seedBlankSession(scaffold, SESSION_ID, cwd)
-    const header = (await scaffold.ctx.sessionPersistence.list())
-      .find(candidate => candidate.id === SESSION_ID)
-    if (header === undefined) throw new Error('blank Session fixture did not materialize')
-    const location = scaffold.ctx.sessionPersistence.locate(header)
-    if (location === undefined) throw new Error('JSONL fixture has no physical artifact')
-    expect((await stat(location.path)).size).toBeLessThanOrEqual(1024)
-
-    browser = await chromium.launch()
-    page = await newEnglishPage(browser)
-    tripwire = watchConsole(page)
-    await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
-    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
-  }, 120_000)
-
-  afterAll(async () => {
-    await browser?.close()
-    await scaffold?.close()
-  })
-
-  it('keeps the verified cold blank Session out of the sidebar', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-cold-blank-session'))
-    const tree = page.getByRole('tree', { name: 'Sessions' })
-    await tree.waitFor({ timeout: 30_000 })
-    expect(await tree.getByText(WORKSPACE_NAME, { exact: true }).count()).toBe(0)
-    const sidebar = await captureStableAria(page, '[role="tree"][aria-label="Sessions"]', scaffold.workspaceCwd)
-    await compareOrRefreshGolden(SIDEBAR_EXPECTED, sidebar, MODE)
-    expect(tripwire.pageErrors).toEqual([])
-  })
-})
diff --git a/apps/web/tests/expected/cold-blank-session/sidebar.expected.md b/apps/web/tests/expected/cold-blank-session/sidebar.expected.md
deleted file mode 100644
index d4d370892e..0000000000
--- a/apps/web/tests/expected/cold-blank-session/sidebar.expected.md
+++ /dev/null
@@ -1 +0,0 @@
-- tree "Sessions": No sessions yet
diff --git a/apps/web/tests/message-actions.e2e.ts b/apps/web/tests/message-actions.e2e.ts
index de849baea3..c29d9cf977 100644
--- a/apps/web/tests/message-actions.e2e.ts
+++ b/apps/web/tests/message-actions.e2e.ts
@@ -39,12 +39,18 @@ function completedTailFixture(raw: string): string {
   const decoded = parseSeedFixture(raw)
   const kept = decoded.events.filter(event => event.seq < 101).map((event) => {
     if (event.type === 'assistant/message' && event.seq === 64) {
-      const data = event.data as unknown as { content?: unknown[] }
-      const content = data.content
-      if (!Array.isArray(content)) throw new Error('borrowed step-one assistant message has no content')
+      const data = event.data as unknown as { message?: { content?: unknown[] } }
+      const message = data.message
+      const content = message?.content
+      if (message === undefined || !Array.isArray(content)) {
+        throw new Error('borrowed step-one assistant message has no content')
+      }
       return {
         ...event,
-        data: { ...data, content: [...content.slice(0, 1), { type: 'text', text: MID_TURN_TEXT }, ...content.slice(1)] },
+        data: {
+          ...data,
+          message: { ...message, content: [...content.slice(0, 1), { type: 'text', text: MID_TURN_TEXT }, ...content.slice(1)] },
+        },
       }
     }
     return event
@@ -59,10 +65,10 @@ function completedTailFixture(raw: string): string {
   const tail = [
     at({ type: 'step/end', data: { turn: 1, step: 2 } }),
     at({ type: 'turn/end', data: { turn: 1, reason: { kind: 'aborted' } } }),
-    at({ type: 'turn/start', data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user', rpcId: '{{rpcId}}' } } } }),
-    at({ type: 'user/message', data: { content: [{ type: 'text', text: SECOND_PROMPT }], source: { kind: 'user', rpcId: '{{rpcId}}' } }, surfaceOp: 'append' }),
+    at({ type: 'turn/start', data: { turn: 2 } }),
+    at({ type: 'user/message', data: { id: '00000000-0000-4000-9000-000000000201', role: 'user', content: [{ type: 'text', text: SECOND_PROMPT }], source: { kind: 'user', rpcId: '{{rpcId}}' } }, surfaceOp: 'append' }),
     at({ type: 'step/start', data: { turn: 2, step: 1 } }),
-    at({ type: 'assistant/message', data: { turn: 2, step: 1, content: [{ type: 'text', text: 'DONE' }], provenance: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } }, sourceEventSeqs: [], surfaceOp: 'append' }),
+    at({ type: 'assistant/message', data: { turn: 2, step: 1, message: { id: '00000000-0000-4000-9000-000000000202', role: 'assistant', content: [{ type: 'text', text: 'DONE' }], source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' } } }, sourceEventSeqs: [], surfaceOp: 'append' }),
     at({ type: 'step/end', data: { turn: 2, step: 1 } }),
     at({ type: 'turn/end', data: { turn: 2, reason: { kind: 'completed' } } }),
   ]
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 95a7118560..388c52a727 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -63,11 +63,10 @@ import type {
 } from '@deepseek-ai/dsh-llm'
 import type { ReplayHandle } from '@deepseek-ai/dsh-llm-replay'
 import { installLlmReplay, parseSessionLog } from '@deepseek-ai/dsh-llm-replay'
-import SessionStore, {
+import {
   packChunkRuns,
   SESSION_FORMAT_VERSION,
   SessionId,
-  SessionSeq,
   type Session,
   type SessionEvent,
   type SessionHeader,
@@ -951,8 +950,9 @@ export function fixtureIdentity(
 
 /**
  * Seed a recorded session fixture into the scaffold's persistence root
- * through the REAL backend API (throwaway Context + SessionStore + JSONL
- * plugin — the semantic-checkpoint precedent), never raw file writes: no
+ * through the REAL backend API (throwaway Context + JSONL plugin, a
+ * create-handle/append/close write — the semantic-checkpoint precedent),
+ * never raw file writes: no
  * knowledge of bucket hashing, filename encoding, or compression, and
  * malformed session events fail loud at seed time. The fixture's tokenized identity
  * ({{sessionId}}/{{cwd}}) is realized for this world before parsing. Event
@@ -1042,8 +1042,8 @@ export async function seedSession(
     version: SESSION_FORMAT_VERSION,
     id: SessionId(id),
     createdAt: Date.now() - 60_000,
-    cwd: scaffold.workspaceCwd,
     isSeeded: false,
+    cwd: scaffold.workspaceCwd,
     delegationDepth: 0,
     ...agentPreset === undefined ? {} : { agentPreset },
   }
@@ -1057,29 +1057,6 @@ export async function seedSession(
   return meta.id
 }
 
-/** Seed one materialized cold Session whose log has no turn/start event. */
-export async function seedBlankSession(
-  scaffold: WebScaffold,
-  id: string,
-  cwd: string,
-): Promise<SessionId> {
-  const meta: SessionHeader = {
-    version: SESSION_FORMAT_VERSION,
-    id: SessionId(id),
-    createdAt: Date.now() - 60_000,
-    cwd,
-    isSeeded: false,
-    delegationDepth: 0,
-  }
-  await persistSeedSession(scaffold, meta, [{
-    type: 'session/end-seed',
-    seq: SessionSeq(0),
-    time: meta.createdAt,
-    data: {},
-  }])
-  return meta.id
-}
-
 /** Materialize one detached Session fixture through the shipped JSONL provider. */
 async function persistSeedSession(
   scaffold: WebScaffold,
@@ -1088,17 +1065,35 @@ async function persistSeedSession(
 ): Promise<void> {
   const seeder = new Context()
   try {
-    await seeder.plugin(SessionStore)
     // Same root as the booted tree with the plugin's own default compression,
     // so the host's directory-scan list() sees one consistent encoding.
     await seeder.plugin(JsonlSessionPersistence, { root: scaffold.persistenceRoot })
-    await seeder.sessionPersistence.create(meta)
-    await seeder.sessionPersistence.append(meta.id, events)
+    const handle = await seeder.sessionPersistence.create(meta)
+    await handle.append(events)
+    await handle.close()
   } finally {
     await seeder.fiber.dispose()
   }
 }
 
+/**
+ * Read one stored session's physical event log through a throwaway read
+ * handle. The physical log carries no synthetic closers: a resumed session
+ * shows the closers the loop appended durably, and a never-resumed
+ * interrupted log stays interrupted.
+ * @param scaffold - the booted scaffold whose persistence holds the session.
+ * @param id - the stored session to read.
+ * @returns the stored events.
+ */
+export async function readPersistedEvents(scaffold: WebScaffold, id: SessionId): Promise<readonly SessionEvent[]> {
+  const handle = await scaffold.ctx.sessionPersistence.open(id, 'read')
+  try {
+    return await handle.read()
+  } finally {
+    await handle.close()
+  }
+}
+
 /**
  * Normalize an aria snapshot: uuid, cwd, workspace-basename, duration,
  * decode-throughput, and path-sensitive compaction estimates collapse to
diff --git a/apps/web/tests/schedule-after.e2e.ts b/apps/web/tests/schedule-after.e2e.ts
index 28c3425941..2560b7a886 100644
--- a/apps/web/tests/schedule-after.e2e.ts
+++ b/apps/web/tests/schedule-after.e2e.ts
@@ -10,7 +10,7 @@ import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent'
 import { composeEntries, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
 import { ToolCallId, createUserMessage, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
-import { SessionId, SessionLogOffset, type SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import {
   ScheduleId,
   createEveryScheduleRecord,
@@ -615,12 +615,13 @@ describe.skipIf(MODE === 'record')('web e2e: active Schedule catalog', () => {
     await workspace.attachSession(CATALOG_SESSION_ID)
 
     // Seed the zero-I/O list view before the Session is opened.
-    const catalog = await scaffold.ctx.sessionPersistence.readFrom(CATALOG_SESSION_ID, SessionLogOffset(0))
-    scaffold.ctx.sessionProjectionCache.coldSnapshot(
-      catalog.meta,
-      catalog.inheritedEventCount,
-      catalog.events,
-    )
+    const catalogReader = await scaffold.ctx.sessionPersistence.open(CATALOG_SESSION_ID, 'read')
+    try {
+      const catalogEvents = [...await catalogReader.read()]
+      scaffold.ctx.sessionProjectionCache.coldSnapshot(catalogReader.header, catalogReader.inheritedEventCount, catalogEvents)
+    } finally {
+      await catalogReader.close()
+    }
 
     browser = await chromium.launch()
     page = await browser.newPage({
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index a55958353d..e20dde3149 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -149,6 +149,8 @@ function withCompaction(raw: string, meter: TokenMeter): string {
   at({
     type: 'user/message',
     data: {
+      id: '00000000-0000-4000-8000-00000000c0de',
+      role: 'user',
       content: [{
         type: 'text',
         text: '<context_checkpoint>Model-only compact checkpoint.</context_checkpoint>',
diff --git a/apps/web/tests/stats-paged-history.e2e.ts b/apps/web/tests/stats-paged-history.e2e.ts
index 1e6682489d..6e6174232c 100644
--- a/apps/web/tests/stats-paged-history.e2e.ts
+++ b/apps/web/tests/stats-paged-history.e2e.ts
@@ -45,7 +45,12 @@ function buildSeed(turns: number): string {
     at({ type: 'turn/start', data: { turn } })
     at({
       type: 'user/message',
-      data: { content: [{ type: 'text', text: `m${turn}` }], source: { kind: 'user' } },
+      data: {
+        id: `00000000-0000-4000-9000-${String(turn).padStart(12, '0')}`,
+        role: 'user',
+        content: [{ type: 'text', text: `m${turn}` }],
+        source: { kind: 'user' },
+      },
       surfaceOp: 'append',
     })
     at({ type: 'step/start', data: { turn, step: 1 } })
diff --git a/apps/web/tests/subagent-conversation.e2e.ts b/apps/web/tests/subagent-conversation.e2e.ts
index 56b96adc4c..508dc711bc 100644
--- a/apps/web/tests/subagent-conversation.e2e.ts
+++ b/apps/web/tests/subagent-conversation.e2e.ts
@@ -5,16 +5,15 @@ import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
-import { MessageId } from '@deepseek-ai/dsh-llm'
-import {
-  SESSION_FORMAT_VERSION, SessionId as sessionId, SessionLogOffset, SessionSeq, type SessionEvent, type SessionHeader, type SessionId,
+import { SessionLogOffset,
+  SESSION_FORMAT_VERSION, SessionId as sessionId, type SessionEvent, type SessionHeader, type SessionId,
 } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-agent'
 import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent'
 import {
   acknowledgeReloadConnectionLoss, captureExpandedTurnProcessAria, captureStableAria,
   compareOrRefreshGolden,
-  launchWebScaffold, watchConsole,
+  launchWebScaffold, readPersistedEvents, watchConsole,
   webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
@@ -67,10 +66,9 @@ async function waitForAgentToSettle(scaffold: WebScaffold, id: SessionId): Promi
 async function waitForCacheRow(
   scaffold: WebScaffold,
   header: SessionHeader,
-  inheritedEventCount: SessionLogOffset,
 ): Promise<void> {
   const deadline = Date.now() + 10_000
-  while (scaffold.ctx.sessionProjectionCache.cachedSnapshot(header, inheritedEventCount) === undefined) {
+  while (scaffold.ctx.sessionProjectionCache.cachedSnapshot(header, SessionLogOffset(0)) === undefined) {
     if (Date.now() >= deadline) throw new Error(`cache row for "${header.id}" did not land`)
     await new Promise<void>(resolve => setTimeout(resolve, 10))
   }
@@ -136,26 +134,26 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       version: SESSION_FORMAT_VERSION,
       id: oneShotId,
       createdAt: oneShotAt,
+      isSeeded: false,
       cwd: scaffold.workspaceCwd,
       parentSession: parent.id,
-      isSeeded: false,
       origin: 'subagent',
       delegationDepth: 1,
     }
-    await scaffold.ctx.sessionPersistence.create(oneShotHeader)
+    const oneShotHandle = await scaffold.ctx.sessionPersistence.create(oneShotHeader)
     const oneShotEvents = [
       {
         type: 'turn/start',
-        seq: SessionSeq(0),
+        seq: 0,
         time: oneShotAt,
         data: { turn: 1 },
       },
       {
         type: 'user/message',
-        seq: SessionSeq(1),
+        seq: 1,
         time: oneShotAt + 1,
         data: {
-          id: MessageId(`legacy-message:${oneShotId}:1`),
+          id: '00000000-0000-4000-9000-000000000101',
           role: 'user',
           content: [{ type: 'text', text: 'Review the event sourcing explanation.' }],
           source: { kind: 'user' },
@@ -164,7 +162,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       },
       {
         type: 'subagent/descriptor',
-        seq: SessionSeq(2),
+        seq: 2,
         time: oneShotAt + 2,
         data: snapshotSubagentDescriptor({
           mode: 'one-shot', provider: 'spawn', label: ONE_SHOT_LABEL,
@@ -172,40 +170,41 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       },
       {
         type: 'turn/end',
-        seq: SessionSeq(3),
+        seq: 3,
         time: oneShotAt + oneShotDurationMs,
         data: { turn: 1, reason: { kind: 'completed' } },
       },
-    ] satisfies SessionEvent[]
-    await scaffold.ctx.sessionPersistence.append(oneShotId, oneShotEvents)
+    ] as SessionEvent[]
+    await oneShotHandle.append(oneShotEvents)
+    await oneShotHandle.close()
     scaffold.ctx.sessionProjectionCache.coldSnapshot(oneShotHeader, SessionLogOffset(0), oneShotEvents)
-    await waitForCacheRow(scaffold, oneShotHeader, SessionLogOffset(0))
+    await waitForCacheRow(scaffold, oneShotHeader)
     grandchildId = sessionId('recorded-grandchild')
     const authoredAt = Date.now()
     const grandchildHeader: SessionHeader = {
       version: SESSION_FORMAT_VERSION,
       id: grandchildId,
       createdAt: authoredAt,
+      isSeeded: false,
       cwd: scaffold.workspaceCwd,
       parentSession: childId,
-      isSeeded: false,
       origin: 'subagent',
       delegationDepth: 2,
     }
-    await scaffold.ctx.sessionPersistence.create(grandchildHeader)
+    const grandchildHandle = await scaffold.ctx.sessionPersistence.create(grandchildHeader)
     const grandchildEvents = [
       {
         type: 'turn/start',
-        seq: SessionSeq(0),
+        seq: 0,
         time: authoredAt,
         data: { turn: 1 },
       },
       {
         type: 'user/message',
-        seq: SessionSeq(1),
+        seq: 1,
         time: authoredAt + 1,
         data: {
-          id: MessageId(`legacy-message:${grandchildId}:1`),
+          id: '00000000-0000-4000-9000-000000000102',
           role: 'user',
           content: [{ type: 'text', text: NESTED_PROMPT }],
           source: { kind: 'user' },
@@ -214,7 +213,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       },
       {
         type: 'subagent/descriptor',
-        seq: SessionSeq(2),
+        seq: 2,
         time: authoredAt + 2,
         data: snapshotSubagentDescriptor({
           mode: 'continuable', provider: 'spawn', label: NESTED_LABEL,
@@ -222,14 +221,15 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       },
       {
         type: 'turn/end',
-        seq: SessionSeq(3),
+        seq: 3,
         time: authoredAt + 3,
         data: { turn: 1, reason: { kind: 'completed' } },
       },
-    ] satisfies SessionEvent[]
-    await scaffold.ctx.sessionPersistence.append(grandchildId, grandchildEvents)
+    ] as SessionEvent[]
+    await grandchildHandle.append(grandchildEvents)
+    await grandchildHandle.close()
     scaffold.ctx.sessionProjectionCache.coldSnapshot(grandchildHeader, SessionLogOffset(0), grandchildEvents)
-    await waitForCacheRow(scaffold, grandchildHeader, SessionLogOffset(0))
+    await waitForCacheRow(scaffold, grandchildHeader)
     expect(scaffold.ctx.agents.get(childId)).toBeUndefined()
     expect(scaffold.ctx.agents.get(oneShotId)).toBeUndefined()
     expect(scaffold.ctx.agents.get(grandchildId)).toBeUndefined()
@@ -575,10 +575,12 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       throw new Error(`post-fork follow-up rejected: ${JSON.stringify(promptReceipt.result.error)}`)
     }
     await expect.poll(async () => {
-      const loaded = await scaffold.ctx.sessionPersistence.load(childId)
-      const messageIndex = loaded.events.findIndex(event => event.type === 'user/message'
+      // The resumed loop appends the follow-up turn's closing events durably,
+      // so the physical log alone answers whether the turn settled.
+      const events = await readPersistedEvents(scaffold, childId)
+      const messageIndex = events.findIndex(event => event.type === 'user/message'
         && event.data.content.some(block => block.type === 'text' && block.text === POST_FORK_FOLLOWUP))
-      return messageIndex >= 0 && loaded.events.slice(messageIndex + 1).some(event => event.type === 'turn/end')
+      return messageIndex >= 0 && events.slice(messageIndex + 1).some(event => event.type === 'turn/end')
     }, { timeout: 30_000 }).toBe(true)
     expect(scaffold.ctx.agents.get(forkId)).not.toBeUndefined()
     await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 10_000 }).toBeUndefined()
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
index fb7e334719..b6a06857d6 100644
--- a/apps/web/tests/subagent-interrupt-ui.e2e.ts
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -23,7 +23,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SubagentPromptRequestId } from '@deepseek-ai/dsh-subagent'
 import {
   acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
-  launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
+  launchWebScaffold, readPersistedEvents, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
 
@@ -305,15 +305,17 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     await expect.poll(() => page.getByText(WAKING_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
     await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 60_000 }).toBeUndefined()
 
-    const loaded = await scaffold.ctx.sessionPersistence.load(childId)
-    const userTexts = loaded.events.flatMap(event => event.type === 'user/message'
+    // The settled child's loop appended every turn's closing events durably,
+    // so the physical log carries the complete record asserted here.
+    const events = await readPersistedEvents(scaffold, childId)
+    const userTexts = events.flatMap(event => event.type === 'user/message'
       && event.data.source.kind === 'user'
       ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
       : [])
     expect(userTexts[0]).toBe(INITIAL)
     expect(userTexts[1]).toMatch(/^Your parent agent id is .+send_message\(\{ agent_id: /)
     expect(userTexts.slice(2)).toEqual([REARM, REARM_WAKE, FOLLOWUP, WAKING])
-    const turnEndKinds = loaded.events
+    const turnEndKinds = events
       .filter(event => event.type === 'turn/end')
       .map(event => event.data.reason.kind)
     expect(turnEndKinds).toEqual(['aborted', 'aborted', 'completed', 'completed', 'completed'])
diff --git a/apps/web/tests/subagent-interrupt.e2e.ts b/apps/web/tests/subagent-interrupt.e2e.ts
index 0243a8e170..0d674dee86 100644
--- a/apps/web/tests/subagent-interrupt.e2e.ts
+++ b/apps/web/tests/subagent-interrupt.e2e.ts
@@ -13,7 +13,7 @@ import { join } from 'node:path'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import { SessionId as sessionId, type SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-agent'
-import { launchWebScaffold, webSnapshotMode, type WebScaffold } from './scaffold.ts'
+import { launchWebScaffold, readPersistedEvents, webSnapshotMode, type WebScaffold } from './scaffold.ts'
 
 const MODE = webSnapshotMode()
 const INITIAL = 'Explain event sourcing in one sentence.'
@@ -176,17 +176,19 @@ describe.skipIf(MODE === 'record')('web e2e: subagents/interruptByParent over th
     expect(waking).toMatchObject({ ok: true })
     await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 60_000 }).toBeUndefined()
 
-    const loaded = await scaffold.ctx.sessionPersistence.load(childId)
+    // The settled child's loop appended every turn's closing events durably,
+    // so the physical log carries the complete record asserted here.
+    const events = await readPersistedEvents(scaffold, childId)
     // Human-origin messages only: the real composition also injects
     // runtime-context snapshots as non-user-source messages.
-    const userTexts = loaded.events.flatMap(event => event.type === 'user/message'
+    const userTexts = events.flatMap(event => event.type === 'user/message'
       && event.data.source.kind === 'user'
       ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
       : [])
     expect(userTexts[0]).toBe(INITIAL)
     expect(userTexts[1]).toMatch(/^Your parent agent id is .+send_message\(\{ agent_id: /)
     expect(userTexts.slice(2)).toEqual([FOLLOWUP, WAKING])
-    const turnEndKinds = loaded.events
+    const turnEndKinds = events
       .filter(event => event.type === 'turn/end')
       .map(event => (event).data.reason.kind)
     expect(turnEndKinds).toEqual(['aborted', 'completed', 'completed'])
diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts
index a8345c45d3..8c885a395a 100644
--- a/apps/web/tests/workspace-management.e2e.ts
+++ b/apps/web/tests/workspace-management.e2e.ts
@@ -18,9 +18,10 @@ import type { Browser, Locator, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import { logPath } from '../../../packages/session/session-persistence-jsonl/src/format.ts'
 import {
   acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
-  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+  launchWebScaffold, readPersistedEvents, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { newEnglishPage, saveFailureShot } from './support.ts'
 
@@ -212,12 +213,12 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     if (workspace === undefined) throw new Error('GUI did not register the existing project directory')
     await workspace.attachSession(SessionId(SEED_ID))
     const header = (await scaffold.ctx.sessionPersistence.list())
+      .map(snapshot => snapshot.header)
       .find(candidate => candidate.id === SEED_ID)
     if (header === undefined) throw new Error('seeded Session log disappeared before deletion')
-    const logLocation = scaffold.ctx.sessionPersistence.locate(header)
-    if (logLocation === undefined) throw new Error('JSONL persistence did not expose the seeded log path')
+    const seededLogPath = logPath(scaffold.persistenceRoot, header.cwd, header.id, 'zstd')
     expect(await readFile(join(scaffold.workspaceCwd, 'workspace', 'a.txt'), 'utf8')).toBe('alpha\n')
-    await stat(logLocation.path)
+    await stat(seededLogPath)
 
     // Open the seeded (first/accounted) Session so deletion must preserve the
     // current selection while it moves into Ungrouped.
@@ -261,8 +262,8 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
       { timeout: 10_000 },
     ).toBe(1)
     expect(await readFile(join(scaffold.workspaceCwd, 'workspace', 'a.txt'), 'utf8')).toBe('alpha\n')
-    await stat(logLocation.path)
-    expect((await scaffold.ctx.sessionPersistence.inspect(SessionId(SEED_ID))).events.length).toBeGreaterThan(0)
+    await stat(seededLogPath)
+    expect((await readPersistedEvents(scaffold, SessionId(SEED_ID))).length).toBeGreaterThan(0)
 
     // Re-registering the exact deleted path immediately, without a reload, is
     // a supported reversible flow. It creates a fresh Workspace id and does
@@ -285,7 +286,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     await expect.poll(() => page.getByText('Ungrouped', { exact: true }).count(), { timeout: 10_000 })
       .toBeGreaterThanOrEqual(1)
     expect(await readFile(join(scaffold.workspaceCwd, 'workspace', 'a.txt'), 'utf8')).toBe('alpha\n')
-    await stat(logLocation.path)
+    await stat(seededLogPath)
 
     // Restore the deleted-registry state so reload still verifies deletion
     // persistence independently of the successful re-registration above.
@@ -308,8 +309,8 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     ).toBe(1)
     expect(scaffold.ctx.workspaceRegistry.get(workspace.id)).toBeUndefined()
     expect(await readFile(join(scaffold.workspaceCwd, 'workspace', 'a.txt'), 'utf8')).toBe('alpha\n')
-    await stat(logLocation.path)
-    expect((await scaffold.ctx.sessionPersistence.inspect(SessionId(SEED_ID))).events.length).toBeGreaterThan(0)
+    await stat(seededLogPath)
+    expect((await readPersistedEvents(scaffold, SessionId(SEED_ID))).length).toBeGreaterThan(0)
 
     expect(transientSlotErrors).toEqual([])
     expect(slotConsoleErrors).toEqual([])
@@ -583,7 +584,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     // Durable on the host: the registry-global set carries the id while the
     // session log itself stays in persistence untouched.
     expect([...scaffold.ctx.workspaceRegistry.archivedSessionIds]).toEqual([SessionId(SEED_ID)])
-    expect((await scaffold.ctx.sessionPersistence.list()).map(header => header.id)).toContain(SessionId(SEED_ID))
+    expect((await scaffold.ctx.sessionPersistence.list()).map(snapshot => snapshot.header.id)).toContain(SessionId(SEED_ID))
     // Reload: the hidden state is rebuilt from the workspace.list baseline.
     const warningStart = tripwire.warnings.length
     await page.reload({ waitUntil: 'load' })
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 23760125d3..114c7ca082 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -54,7 +54,6 @@
     "tests/hmr-live.e2e.ts",
     "tests/preview-boot.e2e.ts",
     "tests/seeded-history.e2e.ts",
-    "tests/cold-blank-session.e2e.ts",
     "tests/stats-paged-history.e2e.ts",
     "tests/sidebar-scrollbar.e2e.ts",
     "tests/rail-search-expand.e2e.ts",
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 9516e43c8a..14c3c8ad07 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: ea1719b68e1109ca5446699a59ebb503f7f989e2
-architecture.zh.md: 3e7bbe7d51559d91858ba1062656c36bb390ec96
+architecture.md: 902fd7b53fe7493127da68f9a8f381a33b8edc18
+architecture.zh.md: 2890b32b5db1ac30f6eafef47b019a03c6acedd4
diff --git a/docs/architecture.md b/docs/architecture.md
index ea1719b68e..902fd7b53f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -139,7 +139,8 @@ New behavior attaches to a documented extension point. Changing the loop itself
 | Add durable session state | extend `SessionEventMap`; render and replay from the log |
 | Generate session titles | register the sole `ctx.sessionTitle` provider |
 | Manage a same-session objective | use `ctx.goals`; continue through `agent/*` |
-| Fork a live session | `ctx.sessions.fork(source, boundary?, childSessionId?)` |
+| Fork a session at a turn boundary | `ctx.agents.create({ sessionId, seed, meta: { parentSession, seedLength } })` — only agent-loop-published sessions persist |
+| Store sessions in a new backend | implement `SessionPersistence` (`create`/`open`/`stat`/`list`/`export`) over the shared handle scaffolding |
 | Scope a registration to one agent | use that agent's `agent.ctx` |
 
 The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities and indexes the step-by-step guides for [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [settings cards](cookbook/adding-a-settings-card.md). The [Conversation subsystem](subsystems/conversation.md) owns Chat-node assembly.
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 3e7bbe7d51..2890b32b5d 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -143,7 +143,8 @@ seam 正是替换一个提供方就能改变整个产品的原因。文件系统
 | 添加持久会话状态 | 扩展 `SessionEventMap`；从日志渲染和回放 |
 | 生成会话标题 | 注册唯一的 `ctx.sessionTitle` 提供方 |
 | 管理同会话目标 | 使用 `ctx.goals`；通过 `agent/*` 续跑 |
-| fork 活跃会话 | `ctx.sessions.fork(source, boundary?, childSessionId?)` |
+| 在轮次边界 fork 会话 | `ctx.agents.create({ sessionId, seed, meta: { parentSession, seedLength } })`——只有经 agent-loop 发布的会话才会持久化 |
+| 在新后端存储会话 | 基于共享的句柄脚手架实现 `SessionPersistence`（`create`/`open`/`stat`/`list`/`export`） |
 | 将注册项限定到单个 agent | 使用该 agent 的 `agent.ctx` |
 
 [扩展实操手册](cookbook/extension-cookbook.zh.md)将功能映射到能力，并索引[包](cookbook/adding-a-package.zh.md)、[工具](cookbook/adding-a-tool.zh.md)、[LLM（大语言模型）适配器](cookbook/adding-an-llm-adapter.zh.md)和[设置卡片](cookbook/adding-a-settings-card.zh.md)的分步指南。[Conversation 子系统](subsystems/conversation.zh.md)负责 Chat node 组装。
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 19563b4b27..6ef6574c80 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: ec62912c76ad336a7bd7e966be7921c9938a211c
-config-catalog.zh.md: e785cacb15652e4162066cbdae478870cf61bc4e
+config-catalog.md: f41dcfc49f2dae3b529bd2d492aa56057cb8d031
+config-catalog.zh.md: 948f5edd492fd5ddd1eec2003de32bffc784c2f9
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index ec62912c76..f41dcfc49f 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -111,7 +111,7 @@ export interface Config {
 
 Depends on: [`AgentOptions`](subsystems/core.md) · [`SessionId`](subsystems/core.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:311`](../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:318`](../packages/core/agent-loop/src/index.ts)
 
 <a id="deepseek-aidsh-agent-presets"></a>
 
@@ -208,14 +208,16 @@ Requires: `agentDefaultModel` · `agents` · `attachments` · `llm` · `sessions
 ```ts config-catalog
 /** Session Controller deployment policy. */
 export interface Config {
-  /** Maximum cold Session artifact size eligible for one full projection observation. */
+  /** Maximum stat-reported event count eligible for one full cold projection observation; `0` disables the event-count gate. */
+  readonly coldBlankProbeMaxEvents?: number
+  /** Maximum stat-reported artifact byte size eligible for one full cold projection observation; `0` disables the byte-size gate. */
   readonly coldBlankProbeMaxBytes?: number
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
 }
 ```
 
-Source: [`packages/api/session-controller/src/index.ts:68`](../packages/api/session-controller/src/index.ts)
+Source: [`packages/api/session-controller/src/index.ts:72`](../packages/api/session-controller/src/index.ts)
 
 <a id="deepseek-aidsh-api-settings-controller"></a>
 
@@ -817,7 +819,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/hooks/hooks-claude-code/src/index.ts:46`](../packages/hooks/hooks-claude-code/src/index.ts)
+Source: [`packages/hooks/hooks-claude-code/src/index.ts:45`](../packages/hooks/hooks-claude-code/src/index.ts)
 
 <a id="deepseek-aidsh-hooks-codex"></a>
 
@@ -844,7 +846,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/hooks/hooks-codex/src/index.ts:45`](../packages/hooks/hooks-codex/src/index.ts)
+Source: [`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-codex/src/index.ts)
 
 <a id="deepseek-aidsh-host-directory-picker-browse"></a>
 
@@ -1819,14 +1821,12 @@ export interface Config {
 export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
 ```
 
-Source: [`packages/session-query/session-log-export/src/index.ts:42`](../packages/session-query/session-log-export/src/index.ts)
+Source: [`packages/session-query/session-log-export/src/index.ts:45`](../packages/session-query/session-log-export/src/index.ts)
 
 <a id="deepseek-aidsh-session-persistence-jsonl"></a>
 
 ## `@deepseek-ai/dsh-session-persistence-jsonl`
 
-Requires: `sessions`
-
 ```ts config-catalog
 /** Plugin config: where the JSONL backend keeps its session logs, and the packed-row write switch. */
 export interface Config {
@@ -1848,17 +1848,13 @@ export interface Config {
   packChunks?: boolean
   /** Physical encoding; defaults to checksummed Zstandard frames. */
   compression?: JsonlCompression
-  /** Maximum cold Session preparations retained for history-to-resume reuse. */
-  preparedSessionCacheSize?: number
-  /** Fixed live-event coalescing window; not a backend completion deadline. */
-  writeBatchMaxDelayMs?: number
 }
 
 /** Physical encoding selected for JSONL session artifacts. */
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-Source: [`packages/session/session-persistence-jsonl/src/index.ts:70`](../packages/session/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session/session-persistence-jsonl/src/index.ts:73`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 <a id="deepseek-aidsh-session-projection-cache"></a>
 
@@ -1915,8 +1911,10 @@ export interface Config extends SessionQueryConfig {
   maxLimit?: number
   /** Maximum snippet length in Unicode code points. Defaults to 240. */
   snippetChars?: number
-  /** Maximum concurrent persisted-log inspections in one inherited batch read. Defaults to 4. */
-  persistedInspectConcurrency?: number
+  /** Maximum concurrent persisted-log reads in one inherited batch read. Defaults to 4. */
+  persistedReadConcurrency?: number
+  /** Maximum cold prepared-Session observations the inherited reader retains for reuse. Defaults to 5. */
+  preparedSessionCacheSize?: number
 }
 
 /** SQLite module/handle opening phase; `never` disables full-text search entirely. */
@@ -1928,7 +1926,7 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 
 Depends on: [`SessionQueryConfig`](../packages/session-query/session-query/src/index.ts)
 
-Source: [`packages/session-query/session-query-sqlite/src/index.ts:96`](../packages/session-query/session-query-sqlite/src/index.ts)
+Source: [`packages/session-query/session-query-sqlite/src/index.ts:92`](../packages/session-query/session-query-sqlite/src/index.ts)
 
 <a id="deepseek-aidsh-session-reference"></a>
 
@@ -2078,7 +2076,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/shell/shell-env/src/index.ts:29`](../packages/shell/shell-env/src/index.ts)
+Source: [`packages/shell/shell-env/src/index.ts:28`](../packages/shell/shell-env/src/index.ts)
 
 <a id="deepseek-aidsh-skill"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index e785cacb15..948f5edd49 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -113,7 +113,7 @@ export interface Config {
 
 依赖：[`AgentOptions`](subsystems/core.zh.md) · [`SessionId`](subsystems/core.zh.md)
 
-来源：[`packages/core/agent-loop/src/index.ts:311`](../packages/core/agent-loop/src/index.ts)
+来源：[`packages/core/agent-loop/src/index.ts:318`](../packages/core/agent-loop/src/index.ts)
 
 <a id="deepseek-aidsh-agent-presets"></a>
 
@@ -210,14 +210,16 @@ export interface Config {
 ```ts config-catalog
 /** Session Controller deployment policy. */
 export interface Config {
-  /** Maximum cold Session artifact size eligible for one full projection observation. */
+  /** Maximum stat-reported event count eligible for one full cold projection observation; `0` disables the event-count gate. */
+  readonly coldBlankProbeMaxEvents?: number
+  /** Maximum stat-reported artifact byte size eligible for one full cold projection observation; `0` disables the byte-size gate. */
   readonly coldBlankProbeMaxBytes?: number
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
 }
 ```
 
-来源：[`packages/api/session-controller/src/index.ts:68`](../packages/api/session-controller/src/index.ts)
+来源：[`packages/api/session-controller/src/index.ts:72`](../packages/api/session-controller/src/index.ts)
 
 <a id="deepseek-aidsh-api-settings-controller"></a>
 
@@ -819,7 +821,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/hooks/hooks-claude-code/src/index.ts:46`](../packages/hooks/hooks-claude-code/src/index.ts)
+来源：[`packages/hooks/hooks-claude-code/src/index.ts:45`](../packages/hooks/hooks-claude-code/src/index.ts)
 
 <a id="deepseek-aidsh-hooks-codex"></a>
 
@@ -846,7 +848,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/hooks/hooks-codex/src/index.ts:45`](../packages/hooks/hooks-codex/src/index.ts)
+来源：[`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-codex/src/index.ts)
 
 <a id="deepseek-aidsh-host-directory-picker-browse"></a>
 
@@ -1821,14 +1823,12 @@ export interface Config {
 export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
 ```
 
-来源：[`packages/session-query/session-log-export/src/index.ts:42`](../packages/session-query/session-log-export/src/index.ts)
+来源：[`packages/session-query/session-log-export/src/index.ts:45`](../packages/session-query/session-log-export/src/index.ts)
 
 <a id="deepseek-aidsh-session-persistence-jsonl"></a>
 
 ## `@deepseek-ai/dsh-session-persistence-jsonl`
 
-需要：`sessions` · `sessionProjections`
-
 ```ts config-catalog
 /** Plugin config: where the JSONL backend keeps its session logs, and the packed-row write switch. */
 export interface Config {
@@ -1850,17 +1850,13 @@ export interface Config {
   packChunks?: boolean
   /** Physical encoding; defaults to checksummed Zstandard frames. */
   compression?: JsonlCompression
-  /** Maximum cold Session preparations retained for history-to-resume reuse. */
-  preparedSessionCacheSize?: number
-  /** Fixed live-event coalescing window; not a backend completion deadline. */
-  writeBatchMaxDelayMs?: number
 }
 
 /** Physical encoding selected for JSONL session artifacts. */
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-来源：[`packages/session/session-persistence-jsonl/src/index.ts:70`](../packages/session/session-persistence-jsonl/src/index.ts)
+来源：[`packages/session/session-persistence-jsonl/src/index.ts:73`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 <a id="deepseek-aidsh-session-projection-cache"></a>
 
@@ -1917,8 +1913,10 @@ export interface Config extends SessionQueryConfig {
   maxLimit?: number
   /** Maximum snippet length in Unicode code points. Defaults to 240. */
   snippetChars?: number
-  /** Maximum concurrent persisted-log inspections in one inherited batch read. Defaults to 4. */
-  persistedInspectConcurrency?: number
+  /** Maximum concurrent persisted-log reads in one inherited batch read. Defaults to 4. */
+  persistedReadConcurrency?: number
+  /** Maximum cold prepared-Session observations the inherited reader retains for reuse. Defaults to 5. */
+  preparedSessionCacheSize?: number
 }
 
 /** SQLite module/handle opening phase; `never` disables full-text search entirely. */
@@ -1930,7 +1928,7 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 
 依赖：[`SessionQueryConfig`](../packages/session-query/session-query/src/index.ts)
 
-来源：[`packages/session-query/session-query-sqlite/src/index.ts:96`](../packages/session-query/session-query-sqlite/src/index.ts)
+来源：[`packages/session-query/session-query-sqlite/src/index.ts:92`](../packages/session-query/session-query-sqlite/src/index.ts)
 
 <a id="deepseek-aidsh-session-reference"></a>
 
@@ -2080,7 +2078,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/shell/shell-env/src/index.ts:29`](../packages/shell/shell-env/src/index.ts)
+来源：[`packages/shell/shell-env/src/index.ts:28`](../packages/shell/shell-env/src/index.ts)
 
 <a id="deepseek-aidsh-skill"></a>
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 28dc25a1c8..571af289d6 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: bdfb3f23e817dadebb090df154af8e1ebf018ee8
-event-producer-consumer.zh.md: 3fe1fe737cb7e99bb8e3a8641dc7bbd7b11b74a4
+event-producer-consumer.md: d04a37ee71756619b36de192011a0053e5ceccb8
+event-producer-consumer.zh.md: 226c368517d989cba2eeac515ee2c544151e8005
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index bdfb3f23e8..d04a37ee71 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -7,9 +7,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
-| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:239`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
+| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:246`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
 | `agent-preset/selected` | `emit` | [`packages/preset/agent-presets/src/types.ts:80`](../packages/preset/agent-presets/src/types.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`) | `remotes` |
-| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:166`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-presets`](../packages/preset/agent-presets), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:166`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-presets`](../packages/preset/agent-presets), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`loader-smoke`](../packages/test-support/loader-smoke), [`schedule`](../packages/schedule/schedule), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:175`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:297`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`session-telemetry`](../packages/session/session-telemetry) |
 | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:204`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs) |
@@ -45,10 +45,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:67`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
 | `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
-| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-telemetry`](../packages/session/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:105`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `remotes` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:92`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:298`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 3fe1fe737c..226c368517 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -9,9 +9,9 @@
 
 | 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
 | --- | --- | --- | --- | --- |
-| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:239`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
+| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:246`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
 | `agent-preset/selected` | `emit` | [`packages/preset/agent-presets/src/types.ts:80`](../packages/preset/agent-presets/src/types.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`) | `remotes` |
-| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:166`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-presets`](../packages/preset/agent-presets), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:166`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-presets`](../packages/preset/agent-presets), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`loader-smoke`](../packages/test-support/loader-smoke), [`schedule`](../packages/schedule/schedule), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:175`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:297`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`session-telemetry`](../packages/session/session-telemetry) |
 | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:204`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs) |
@@ -47,10 +47,10 @@
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:67`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
 | `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
-| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-telemetry`](../packages/session/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:105`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `remotes` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:92`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:298`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index 3b1f274aee..7a1a91a45a 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.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 docs/module-graph.md
-module-graph.md: a028d1efd12924f0592b1dba954071cebd9d3dbe
-module-graph.zh.md: c4efd116e5c79aa9c0210d5ff3692d7a39cd1c46
+module-graph.md: 514d09c5883ec8196e0706fbd7a3ccf45b8aafb5
+module-graph.zh.md: 444100e17ce6794efa39ef2e0a10872a6e1c3484
diff --git a/docs/module-graph.md b/docs/module-graph.md
index a028d1efd1..514d09c588 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -447,6 +447,7 @@ flowchart TD
   pkg_fs --> pkg_llm
   pkg_fs --> pkg_sandbox
   pkg_spill_local --> pkg_spill
+  pkg_session_log_export --> pkg_session_persistence
   pkg_message_feedback --> pkg_brand
   pkg_message_feedback --> pkg_llm
   pkg_message_feedback --> pkg_session
@@ -749,7 +750,6 @@ flowchart TD
   pkg_hooks_codex --> pkg_hook_protocol
   pkg_hooks_codex --> pkg_llm
   pkg_hooks_codex --> pkg_session
-  pkg_hooks_codex --> pkg_session_persistence
   pkg_hooks_codex --> pkg_session_projection
   pkg_hooks_codex --> pkg_tools
   pkg_command_compact --> pkg_commands
@@ -835,7 +835,6 @@ flowchart TD
   pkg_session_title_first_prompt_llm --> pkg_session_title
   pkg_session_title_first_prompt_llm --> pkg_session_title_llm
   pkg_shell_env --> pkg_home_paths
-  pkg_shell_env --> pkg_session_persistence
   pkg_shell_env --> pkg_shell
   pkg_shell_env --> pkg_tools
   pkg_tool_bash_persistent --> pkg_agent
@@ -1032,7 +1031,6 @@ flowchart TD
   pkg_hooks_claude_code --> pkg_hook_protocol
   pkg_hooks_claude_code --> pkg_llm
   pkg_hooks_claude_code --> pkg_session
-  pkg_hooks_claude_code --> pkg_session_persistence
   pkg_hooks_claude_code --> pkg_session_projection
   pkg_hooks_claude_code --> pkg_subagent
   pkg_hooks_claude_code --> pkg_tools
@@ -1154,7 +1152,6 @@ flowchart TD
 | [`util-workspace-path`](../packages/util/workspace-path) | `util` | — |
 | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — |
 | [`llm`](../packages/llm/llm) | `llm` | — |
-| [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | — |
 | [`api-gateway`](../packages/api/gateway) | `api` | — |
 | [`cmdline`](../packages/boot/cmdline) | `boot` | — |
 | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — |
@@ -1266,6 +1263,7 @@ flowchart TD
 | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`spill`](../packages/spill/spill) |
+| [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | [`session-persistence`](../packages/session/session-persistence) |
 | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
@@ -1328,7 +1326,7 @@ flowchart TD
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
 | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
 | [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) |
-| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
+| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
 | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction) |
 | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
 | [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1345,7 +1343,7 @@ flowchart TD
 | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
 | [`session-title-all-prompts-llm`](../packages/session/session-title-all-prompts-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
 | [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
-| [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`session-persistence`](../packages/session/session-persistence), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
+| [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
 | [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) |
@@ -1375,7 +1373,7 @@ flowchart TD
 | [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
 | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) |
 | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index c4efd116e5..444100e17c 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -449,6 +449,7 @@ flowchart TD
   pkg_fs --> pkg_llm
   pkg_fs --> pkg_sandbox
   pkg_spill_local --> pkg_spill
+  pkg_session_log_export --> pkg_session_persistence
   pkg_message_feedback --> pkg_brand
   pkg_message_feedback --> pkg_llm
   pkg_message_feedback --> pkg_session
@@ -751,7 +752,6 @@ flowchart TD
   pkg_hooks_codex --> pkg_hook_protocol
   pkg_hooks_codex --> pkg_llm
   pkg_hooks_codex --> pkg_session
-  pkg_hooks_codex --> pkg_session_persistence
   pkg_hooks_codex --> pkg_session_projection
   pkg_hooks_codex --> pkg_tools
   pkg_command_compact --> pkg_commands
@@ -837,7 +837,6 @@ flowchart TD
   pkg_session_title_first_prompt_llm --> pkg_session_title
   pkg_session_title_first_prompt_llm --> pkg_session_title_llm
   pkg_shell_env --> pkg_home_paths
-  pkg_shell_env --> pkg_session_persistence
   pkg_shell_env --> pkg_shell
   pkg_shell_env --> pkg_tools
   pkg_tool_bash_persistent --> pkg_agent
@@ -1034,7 +1033,6 @@ flowchart TD
   pkg_hooks_claude_code --> pkg_hook_protocol
   pkg_hooks_claude_code --> pkg_llm
   pkg_hooks_claude_code --> pkg_session
-  pkg_hooks_claude_code --> pkg_session_persistence
   pkg_hooks_claude_code --> pkg_session_projection
   pkg_hooks_claude_code --> pkg_subagent
   pkg_hooks_claude_code --> pkg_tools
@@ -1156,7 +1154,6 @@ flowchart TD
 | [`util-workspace-path`](../packages/util/workspace-path) | `util` | — |
 | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — |
 | [`llm`](../packages/llm/llm) | `llm` | — |
-| [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | — |
 | [`api-gateway`](../packages/api/gateway) | `api` | — |
 | [`cmdline`](../packages/boot/cmdline) | `boot` | — |
 | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — |
@@ -1268,6 +1265,7 @@ flowchart TD
 | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`spill`](../packages/spill/spill) |
+| [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | [`session-persistence`](../packages/session/session-persistence) |
 | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
@@ -1330,7 +1328,7 @@ flowchart TD
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
 | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
 | [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) |
-| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
+| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
 | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction) |
 | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
 | [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1347,7 +1345,7 @@ flowchart TD
 | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
 | [`session-title-all-prompts-llm`](../packages/session/session-title-all-prompts-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
 | [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
-| [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`session-persistence`](../packages/session/session-persistence), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
+| [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
 | [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) |
@@ -1377,7 +1375,7 @@ flowchart TD
 | [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
 | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) |
 | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index 68394c63b7..013ca16f25 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.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 docs/persistence-catalog.md
-persistence-catalog.md: 2fb2b020841a42da6f7505928a87868fc43bc559
-persistence-catalog.zh.md: 4014fd2c10e20193ea68a5f6c761c99b4569b032
+persistence-catalog.md: 1439f5db933899cd145e302d9eefcebfad94097b
+persistence-catalog.zh.md: 1c18a63f4382edafd23cf6c70dbef8922add34d3
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 2fb2b02084..1439f5db93 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -90,7 +90,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-Sources: [`packages/core/session/src/types.ts:366`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:373`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:402`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:434`](../packages/core/session/src/types.ts)
+Sources: [`packages/core/session/src/types.ts:368`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:404`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:436`](../packages/core/session/src/types.ts)
 
 ## Events
 
@@ -215,7 +215,7 @@ Source: [`packages/interaction/user-approval/src/index.ts:33`](../packages/inter
 
 Types: [StreamChunk](subsystems/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:289`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:291`](../packages/core/session/src/types.ts)
 
 <a id="assistantmessage--surface"></a>
 
@@ -237,7 +237,7 @@ Source: [`packages/core/session/src/types.ts:289`](../packages/core/session/src/
 
 Types: [TokenUsage](subsystems/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:300`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:302`](../packages/core/session/src/types.ts)
 
 ### `command/*`
 
@@ -563,7 +563,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:46`](../packages/plan/plan-mode/s
 'request/context': RequestContext
 ```
 
-Source: [`packages/core/session/src/types.ts:339`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:341`](../packages/core/session/src/types.ts)
 
 <a id="requestheader--log-only"></a>
 
@@ -582,7 +582,7 @@ Source: [`packages/core/session/src/types.ts:339`](../packages/core/session/src/
 }
 ```
 
-Source: [`packages/core/session/src/types.ts:329`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:331`](../packages/core/session/src/types.ts)
 
 ### `sandbox/*`
 
@@ -657,7 +657,7 @@ Source: [`packages/schedule/schedule/src/types.ts:219`](../packages/schedule/sch
 'session/end-seed': Record<string, never>
 ```
 
-Source: [`packages/core/session/src/types.ts:362`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:364`](../packages/core/session/src/types.ts)
 
 <a id="sessiontitle--log-only"></a>
 
@@ -717,7 +717,7 @@ Source: [`packages/session/session-log-deepseek/src/types.ts:57`](../packages/se
 'step/end': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:281`](../packages/core/session/src/types.ts)
 
 <a id="stepstart--log-only"></a>
 
@@ -728,7 +728,7 @@ Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/
 'step/start': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
 
 ### `subagent/*`
 
@@ -859,7 +859,7 @@ Source: [`packages/todo/tool-todo/src/types.ts:31`](../packages/todo/tool-todo/s
 
 Types: [ToolCallId](subsystems/core.md)
 
-Source: [`packages/core/session/src/types.ts:306`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts)
 
 <a id="toolcode-dispatch--log-only"></a>
 
@@ -934,7 +934,7 @@ Source: [`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types
 }
 ```
 
-Source: [`packages/core/session/src/types.ts:318`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:320`](../packages/core/session/src/types.ts)
 
 ### `tool-workflow/*`
 
@@ -1014,7 +1014,7 @@ Source: [`packages/workflow/tool-workflow/src/types.ts:47`](../packages/workflow
 
 Types: [TurnEndReason](subsystems/session.md)
 
-Source: [`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts)
 
 <a id="turnstart--log-only"></a>
 
@@ -1030,7 +1030,7 @@ Source: [`packages/core/session/src/types.ts:275`](../packages/core/session/src/
 'turn/start': { turn: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:268`](../packages/core/session/src/types.ts)
 
 ### `user/*`
 
@@ -1049,7 +1049,7 @@ Source: [`packages/core/session/src/types.ts:266`](../packages/core/session/src/
 'user/message': UserMessage
 ```
 
-Source: [`packages/core/session/src/types.ts:287`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:289`](../packages/core/session/src/types.ts)
 
 ### `web/*`
 
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 4014fd2c10..1c18a63f43 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -92,7 +92,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-来源：[`packages/core/session/src/types.ts:366`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:373`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:402`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:434`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:368`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:404`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:436`](../packages/core/session/src/types.ts)
 
 ## 事件
 
@@ -217,7 +217,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[StreamChunk](subsystems/llm-streaming.zh.md)
 
-来源：[`packages/core/session/src/types.ts:289`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:291`](../packages/core/session/src/types.ts)
 
 <a id="assistantmessage--surface"></a>
 
@@ -239,7 +239,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[TokenUsage](subsystems/llm-streaming.zh.md)
 
-来源：[`packages/core/session/src/types.ts:300`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:302`](../packages/core/session/src/types.ts)
 
 ### `command/*`
 
@@ -565,7 +565,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'request/context': RequestContext
 ```
 
-来源：[`packages/core/session/src/types.ts:339`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:341`](../packages/core/session/src/types.ts)
 
 <a id="requestheader--log-only"></a>
 
@@ -584,7 +584,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/core/session/src/types.ts:329`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:331`](../packages/core/session/src/types.ts)
 
 ### `sandbox/*`
 
@@ -659,7 +659,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'session/end-seed': Record<string, never>
 ```
 
-来源：[`packages/core/session/src/types.ts:362`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:364`](../packages/core/session/src/types.ts)
 
 <a id="sessiontitle--log-only"></a>
 
@@ -719,7 +719,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'step/end': { turn: number; step: number }
 ```
 
-来源：[`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:281`](../packages/core/session/src/types.ts)
 
 <a id="stepstart--log-only"></a>
 
@@ -730,7 +730,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'step/start': { turn: number; step: number }
 ```
 
-来源：[`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
 
 ### `subagent/*`
 
@@ -861,7 +861,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[ToolCallId](subsystems/core.zh.md)
 
-来源：[`packages/core/session/src/types.ts:306`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts)
 
 <a id="toolcode-dispatch--log-only"></a>
 
@@ -936,7 +936,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/core/session/src/types.ts:318`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:320`](../packages/core/session/src/types.ts)
 
 ### `tool-workflow/*`
 
@@ -1016,7 +1016,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[TurnEndReason](subsystems/session.zh.md)
 
-来源：[`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts)
 
 <a id="turnstart--log-only"></a>
 
@@ -1032,7 +1032,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'turn/start': { turn: number }
 ```
 
-来源：[`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:268`](../packages/core/session/src/types.ts)
 
 ### `user/*`
 
@@ -1051,7 +1051,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'user/message': UserMessage
 ```
 
-来源：[`packages/core/session/src/types.ts:287`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:289`](../packages/core/session/src/types.ts)
 
 ### `web/*`
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index a60f0c783f..3dac641914 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: a59a692573c2e2756e60626268314a8ade6c546e
-core.zh.md: acea4966a30ab03c24f1aea9bcd2d33a6271a28d
+core.md: 170268351454643544d5ab20e3d4b6a8fd8c6c69
+core.zh.md: 048f7ed5f2136bb583c0308635e5cddde2b96785
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index a59a692573..1702683514 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -356,13 +356,14 @@ Concrete agent factory and driver service.
 /**
  * Create an agent and session under one caller-supplied identity, owned by
  * the accessing fiber. Constructor-driven config calls mint a fresh combined
- * id before entering this boundary.
+ * id before entering this boundary. When a persistence backend is mounted,
+ * the session's durable identity and any seed are stored before publication.
  * @param id - shared agent/session identity.
  * @param options - concrete loop options.
  * @param meta - optional fresh-session workspace metadata.
  * @returns the published running agent.
  */
-create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
+async create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Promise<Agent>
 
 /**
  * Create an owned agent on a caller-supplied session id.
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index acea4966a3..048f7ed5f2 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -366,13 +366,14 @@ Concrete agent factory and driver service.
 /**
  * Create an agent and session under one caller-supplied identity, owned by
  * the accessing fiber. Constructor-driven config calls mint a fresh combined
- * id before entering this boundary.
+ * id before entering this boundary. When a persistence backend is mounted,
+ * the session's durable identity and any seed are stored before publication.
  * @param id - shared agent/session identity.
  * @param options - concrete loop options.
  * @param meta - optional fresh-session workspace metadata.
  * @returns the published running agent.
  */
-create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
+async create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Promise<Agent>
 
 /**
  * Create an owned agent on a caller-supplied session id.
diff --git a/docs/subsystems/feedback.i18n.yaml b/docs/subsystems/feedback.i18n.yaml
index 9e6b0d6424..c78fd14493 100644
--- a/docs/subsystems/feedback.i18n.yaml
+++ b/docs/subsystems/feedback.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 docs/subsystems/feedback.md
-feedback.md: 046765b65773834b1804aa2a915625a3d6c9f099
-feedback.zh.md: 55b8e7d1b5b2c8ca5613d9888ef7f415b34ed5dc
+feedback.md: 0bb01315d74cc41c1ab1008144dd8fca84efd76a
+feedback.zh.md: 46f382edd270e5bb557f304a2f770b5fe7791dc5
diff --git a/docs/subsystems/feedback.md b/docs/subsystems/feedback.md
index 046765b657..0bb01315d7 100644
--- a/docs/subsystems/feedback.md
+++ b/docs/subsystems/feedback.md
@@ -191,13 +191,13 @@ One Session sidecar row contains its header identity `{createdAt, cwd}` and feed
 
 ## Target and lifecycle authority
 
-`SessionPersistence.inspect()` supplies the target Session observation without publishing or resuming an Agent and without committing cold repair. A cold `listSnapshots()` preflight classifies definite absence; inspection failure for a catalogued Session propagates as infrastructure failure. `put` accepts only a non-empty, append-origin `assistant/message` with the requested `MessageId`; replacement-origin, usage-only empty, and non-assistant records are not feedback targets.
+A live owner's in-memory log supplies the target Session observation directly; a cold target is read through a `SessionPersistence.open(id, 'read')` handle without publishing or resuming an Agent and without writing recovery. A `stat(id)` preflight classifies definite absence; a read failure for a Session `stat` confirmed propagates as infrastructure failure. `put` accepts only a non-empty, append-origin `assistant/message` with the requested `MessageId`; replacement-origin, usage-only empty, and non-assistant records are not feedback targets.
 
 The stored `{createdAt, cwd}` identity must match the inspected header. A mismatch is treated as absence: `list` returns no items, while `put` may replace the stale row with one bound to the current header identity. Forks use a new Session identity and receive no sidecar copy even when their seed contains the same messages.
 
 ## Persistence and Remote contract
 
-The service stores whole Session rows in the `message_feedback` storage domain through `ctx.storageDomain`. Before `put` commits a row that references a target message, a matching live target passes through the canonical `ctx.sessions.flush` checkpoint; both live and cold paths are then physically read from sequence zero through `SessionPersistence.readFrom`. The resulting observation is revalidated before the sidecar write, so the durable target log always precedes its sidecar commit. `maxNoteBytes` is required and bounds note text by UTF-8 bytes; the Web Host composition sets `8192`. The package publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` unary Remote contract through `TypertRemoteService` and `@Remote`; the generated Cordis API below is the method-level authority.
+The service stores whole Session rows in the `message_feedback` storage domain through `ctx.storageDomain`. Before `put` commits a row that references a target message, a matching live target passes through the canonical `ctx.sessions.flush` checkpoint; both live and cold paths are then physically read from sequence zero through a fresh read handle, which observes at least the flushed prefix by the seam's freshness guarantee. The resulting observation is revalidated before the sidecar write, so the durable target log always precedes its sidecar commit. `maxNoteBytes` is required and bounds note text by UTF-8 bytes; the Web Host composition sets `8192`. The package publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` unary Remote contract through `TypertRemoteService` and `@Remote`; the generated Cordis API below is the method-level authority.
 
 Plugin disposal closes mutation admission, drains accepted per-Session queue work, and then closes the storage domain.
 
diff --git a/docs/subsystems/feedback.zh.md b/docs/subsystems/feedback.zh.md
index 55b8e7d1b5..46f382edd2 100644
--- a/docs/subsystems/feedback.zh.md
+++ b/docs/subsystems/feedback.zh.md
@@ -191,13 +191,13 @@ type MessageFeedbackDeleteResult =
 
 ## 目标与生命周期权威
 
-`SessionPersistence.inspect()` 提供目标 Session 的观测，且不会发布或恢复 Agent，也不会提交 cold repair。cold 路径先由 `listSnapshots()` 预检明确不存在；已进入目录的 Session 若检查失败，会按基础设施故障原样传播。`put` 只接受具有指定 `MessageId` 的非空、append-origin `assistant/message`；replacement-origin、仅承载 usage 的空记录和非 assistant 记录都不是反馈目标。
+live 持有者的内存日志直接提供目标 Session 的观测；cold 目标则通过 `SessionPersistence.open(id, 'read')` 句柄读取，既不会发布或恢复 Agent，也不会写入恢复内容。先由 `stat(id)` 预检明确不存在；`stat` 已确认存在的 Session 若读取失败，会按基础设施故障原样传播。`put` 只接受具有指定 `MessageId` 的非空、append-origin `assistant/message`；replacement-origin、仅承载 usage 的空记录和非 assistant 记录都不是反馈目标。
 
 存储的 `{createdAt, cwd}` 身份必须与检查所得 header 匹配。不匹配按不存在处理：`list` 返回空条目，`put` 则可用绑定当前 header 身份的新记录替换陈旧行。fork 使用新的 Session 身份，即使种子包含相同消息，也不获得伴随记录副本。
 
 ## 持久化与 Remote 约定
 
-服务通过 `ctx.storageDomain` 在 `message_feedback` 存储域中保存完整 Session 行。`put` 提交引用目标消息的伴随记录前，身份匹配的 live 目标先经过权威 `ctx.sessions.flush` checkpoint；随后 live 与 cold 路径都会通过 `SessionPersistence.readFrom` 从序列零做物理复读。写入伴随记录前会再次校验所得观测，因此目标日志的持久提交始终先于其伴随记录。`maxNoteBytes` 为必填项，按 UTF-8 字节限制备注文本；Web Host 组合将其设为 `8192`。该包通过 `TypertRemoteService` 与 `@Remote` 发布 Host `messageFeedback.list`、`messageFeedback.put` 和 `messageFeedback.delete` 一元 Remote 约定；下方生成的 Cordis API 是方法级权威。
+服务通过 `ctx.storageDomain` 在 `message_feedback` 存储域中保存完整 Session 行。`put` 提交引用目标消息的伴随记录前，身份匹配的 live 目标先经过权威 `ctx.sessions.flush` checkpoint；随后 live 与 cold 路径都会通过一个新开的读句柄从序列零做物理复读，依据该 seam 的新鲜度保证，它至少能观察到已 flush 的前缀。写入伴随记录前会再次校验所得观测，因此目标日志的持久提交始终先于其伴随记录。`maxNoteBytes` 为必填项，按 UTF-8 字节限制备注文本；Web Host 组合将其设为 `8192`。该包通过 `TypertRemoteService` 与 `@Remote` 发布 Host `messageFeedback.list`、`messageFeedback.put` 和 `messageFeedback.delete` 一元 Remote 约定；下方生成的 Cordis API 是方法级权威。
 
 Plugin disposal 会先关闭变更接纳，排空已进入各 Session 队列的工作，然后才关闭 storage domain。
 
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index ec456511f9..9b08566a15 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: b61ddee8d12854b330b967a09a1a685d763f0041
-persistence.zh.md: 08cc35d987360138ec096b70f8c6b11b5cba4c55
+persistence.md: 4f6069b8a926f8fe24d2271650d45dc8377fa355
+persistence.zh.md: 6f8430868a001d0da4755579d2e667097d254ac6
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index b61ddee8d1..4f6069b8a9 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -4,29 +4,112 @@ English | [中文](persistence.zh.md)
 
 The **durability seam** for the event log. [session.md](session.md) describes the in-memory `Session` — the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its provider model and shipped JSONL backend, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
 
-The seam is a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) defines locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type**. The repository ships [dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl) as its provider; out-of-tree providers may implement the same service contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
+The seam is a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) exposing `create`/`open`/`stat`/`list` over the existing `SessionEvent` — **no parallel persisted event type** — where `create` and `open` return a per-session `SessionHandle` (`read`/`append`/`flush`/`close`) that carries all log access and single-writer ownership. The repository ships [dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl) as its provider; out-of-tree providers may implement the same service contract. See the [handle-based persistence Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md) and the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
 
-## The flush checkpoint
+## `SessionHandle` — one open channel onto a stored session
 
-`session/event` is a *synchronous* notification; persistence plugins copy the event into a per-session controller without blocking the producer. The first pending event starts a fixed batching window, and later events join without resetting its deadline. Expiry starts one durable batch; events admitted during that write receive their own deadline and form a follow-up batch. `session/flush` cancels the wait and drains through quiescence, so the loop still uses it as the ordering and error-observation checkpoint before claiming the next ordinary turn. A rejected background write retains its events and pauses automatic retry; a new event starts a fresh window, while explicit flush retries immediately and reports failure through `agent/error` and the logger, never as a session event past the closed turn. Disposal performs the same final drain. The configured maximum bounds only intentional batching wait, not event-loop scheduling or backend durability latency ([decision](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
-
-## Crash recovery preserves an interrupted turn
-
-A backend that reloads a log crashed mid-turn finds an open `turn/start` with no `turn/end`. It does **not** truncate — a single turn can be huge in a long-horizon task (many steps, large tool output), and those events were durably appended before the crash. Instead it closes the orphaned turn with a synthetic `turn/end { reason: { kind: 'interrupted' } }`, keeping the interrupted execution balanced without changing any standalone events before or after it. `interrupted` is the one `TurnEndReason` no loop emits (see [session.md](session.md#why-a-turn-ended-turnendreasonmap)).
-
-Repair applies only to cold sessions. For a live id, `SessionPersistence.load(id)` waits until the authoritative in-memory snapshot is durable and returns it only when balanced; an open live turn rejects rather than receiving synthetic interruption boundaries. HMR adopts a live prefix without closing its active turn.
-
-`SessionPersistence.inspect(id)` constructs an immutable logical Session without publishing it or writing recovery. Cold inspection balances an interrupted turn in memory while leaving torn physical tails untouched; inspection of an already-live Session borrows its current immutable snapshot and may therefore contain an open turn. Coordinator-backed implementations retain the exact cold unpublished Session in a bounded LRU, so repeated history reads and a later `prepare(id)` share one read, decompression, validation, freeze, and Session construction. `prepare(id)` reserves the Session, commits pending repair, and returns a disposable publication handle; `load(id)` uses the same machinery to commit repair without publication. The [Session preparation decision](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.md) owns this lifecycle.
-
-## `SessionLocation` — optional per-session artifact target
-
-`SessionPersistence.locate(meta)` synchronously resolves a backend-owned independent artifact without reading, creating, or flushing it. JSONL returns the absolute transcript path inside its project/session directory; a backend without one independent artifact per session returns `undefined`. A returned path can therefore name a file that does not yet exist or lacks the current unflushed turn; it is a location hint, not authorization or a freshness guarantee.
+Every log read and write flows through a handle, never through id-addressed service methods: the handle is the single door a future cross-process write lease will guard. One handle type serves both accesses — a mutation on a `read` handle is a runtime `SessionReadOnlyError` rather than a typed split — and in-process single-writer ownership makes a second `open(id, 'write')` reject with `SessionAlreadyOwnedError` while an owner is active.
 
 ```ts type-equiv
 /**
- * A backend-resolved, per-session local artifact location. The path is an
- * absolute target path and can name an artifact that has not materialized yet.
- * Consumers must treat it as a location hint, never as an authorization token.
+ * One open channel onto a stored session. A handle is single-owner state, not
+ * a shared service: `read` never backtracks below what this handle already
+ * observed, a `write` handle reads its own successful appends, and `close()`
+ * is the one teardown (idempotent, uncancellable; `Symbol.asyncDispose`
+ * delegates to it). Every operation on a closed handle rejects with
+ * `SessionHandleClosedError`.
+ *
+ * Freshness across handles: once an `append` or `flush` resolves on a write
+ * handle, every read STARTED afterwards on the same backend instance — on any
+ * handle, or through `stat`/`list` — observes at least that prefix.
+ * Reads concurrent with a mutation carry no ordering promise beyond the valid
+ * contiguous prefix.
+ */
+interface SessionHandle extends AsyncDisposable {
+  /** The stored session this handle addresses. */
+  readonly id: SessionId
+  /** The immutable stored header, fixed at `create`/`open`. */
+  readonly header: SessionHeader
+  /**
+   * Exact fork-inherited prefix length stored with the log; `0` when
+   * `header.isSeeded` is false. Storage metadata paired with the header for
+   * every body read, never part of the replayable event log.
+   */
+  readonly inheritedEventCount: SessionLogOffset
+  /** Whether this handle may mutate the log. */
+  readonly access: SessionAccess
+
+  /**
+   * Read a slice of the valid contiguous logical log. The slice is a legal log
+   * prefix segment: a torn physical tail is never returned, and repeated reads
+   * on this handle never observe an older state than a prior read.
+   * @param offset - first logical event seq to include; defaults to `0`.
+   * @param length - maximum number of events to return; defaults to the rest
+   *   of the log. An offset at or past the end returns an empty list.
+   * @param options - optional cancellation.
+   * @returns the events with `seq >= offset`, at most `length` of them.
+   */
+  read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<readonly SessionEvent[]>
+
+  /**
+   * Append a contiguous batch continuing the current logical end. The first
+   * event's `seq` MUST equal the stored next-seq; committed events are never
+   * rewritten. Persistence is best-effort: on resolution the batch is
+   * accepted, ordered, and visible to reads on this backend instance, but
+   * only a resolved {@link flush} promises it survives a crash — a backend
+   * may buffer or batch physical writes behind append. Rejects with
+   * `SessionReadOnlyError` on a read handle and `SessionOwnershipLostError`
+   * when write ownership is gone.
+   * @param events - the contiguous batch, in seq order.
+   * @param options - optional cancellation observed before the write starts.
+   */
+  append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>
+
+  /**
+   * The durability barrier — the one operation that promises storage: on
+   * resolution every acknowledged append is durable and the session is
+   * materialized for other processes; an empty created session becomes
+   * durably listable here. Callers that must survive a crash flush; a backend
+   * whose `append` already persists on resolution treats this as
+   * materialize-if-needed. Rejects with `SessionReadOnlyError` on a read
+   * handle.
+   * @param options - optional cancellation observed before the barrier starts.
+   */
+  flush(options?: SessionHandleFlushOptions): Promise<void>
+
+  /**
+   * Release the handle: a read handle frees local resources; a write handle
+   * completes pending durability and releases write ownership. Idempotent,
+   * asynchronous, and deliberately not cancellable.
+   */
+  close(): Promise<void>
+}
+```
+
+A created session is observable in this process from the moment `create` resolves, while a backend may defer physical materialization (a pure optimization) until the first `append` or `flush`; other processes see only materialized sessions, and a session that never materialized before a crash never existed.
+
+## The flush checkpoint
+
+`session/event` is a *synchronous* notification; the mounted backend routes it by session id into the active write handle's bounded write-behind window without blocking the producer (the backend installs these listeners once, because persistence already enforces one active write handle per id). The first pending event starts a fixed internal batching window, and later events join without resetting its deadline. Expiry starts one durable `append` through the session's write handle; events admitted during that write receive their own deadline and form a follow-up batch. `session/flush` cancels the wait and drains through quiescence, so the loop still uses it as the ordering and error-observation checkpoint before claiming the next ordinary turn. A rejected background write retains its events in order, pauses the automatic path, and is reported through the logger; the next explicit flush retries and rejects loudly to its caller. `session/disposed` performs the same final drain and closes the handle, and `close()` itself drains the routed buffer through the still-open storage, so backend teardown's close sweep loses nothing. The window bounds only intentional batching wait, not event-loop scheduling or backend durability latency ([decision](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
+
+## Crash recovery preserves an interrupted turn
+
+A log crashed mid-turn ends with an open `turn/start` and no `turn/end`. Persistence does **not** truncate or repair it — a single turn can be huge in a long-horizon task (many steps, large tool output), and those events were durably appended before the crash. It returns the physically valid contiguous log; only the incomplete fragment of a torn physical tail, belonging to an append that never resolved, is discarded — complete records recovered from it (the JSONL backend partially decodes a torn Zstandard frame) are durably rewritten by the write path before the handle's first new append. Repair is the reader's job: resume (agent-loop) reads the stored log through its write handle, computes `interruptedTurnClosers` — missing tool errors, any open `step/end`, and a synthetic `turn/end { reason: { kind: 'interrupted' } }` — and appends them through the same handle as an ordinary batch before publishing the Session. `interrupted` is the one `TurnEndReason` no loop emits (see [session.md](session.md#why-a-turn-ended-turnendreasonmap)).
+
+Repair therefore writes only under write ownership: a live session's write handle is held by its lifecycle owner, so a concurrent `open(id, 'write')` rejects with `SessionAlreadyOwnedError` instead of racing repair against a live turn. Read-only observers (session-query) balance an interrupted cold log with the same closers in memory only, writing nothing back.
+
+Read-only observation is `open(id, 'read')`: the handle serves validated contiguous prefix slices, never a torn tail, and repeated reads on one handle never observe an older state than a prior read. There is no persistence-side prepared-Session cache: session-query owns its cold-read cache, keying one balanced cold Session per id on the `stat().revision` change token and re-reading only when the token changes. The [handle-based persistence Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md) owns this lifecycle; the [Session preparation decision](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.md) records the publication-boundary `SessionPreparation` that remains.
+
+## `SessionLocation` — refusal-diagnostics artifact target
+
+`SessionLocation` is not a consumer-facing query: log access goes through a session handle's `read`. It survives only as refusal diagnostics, letting a `SessionFormatUnsupportedError` name the raw log a build refused to interpret. JSONL supplies the absolute transcript path inside its project/session directory; a backend without one artifact per session supplies nothing.
+
+```ts type-equiv
+/**
+ * A backend-resolved, per-session local artifact location. Carried only by
+ * refusal diagnostics ({@link SessionFormatUnsupportedError}) so a user can
+ * find the raw log a build refused to interpret; it is not a consumer-facing
+ * query — log access goes through a session handle's `read`.
  */
 interface SessionLocation {
   /** Backend-specific artifact kind, for example `jsonl`. */
@@ -91,7 +174,7 @@ interface SessionHeader {
 
 ## Format refusal — logs a build cannot faithfully read
 
-A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. A header `version` ahead of `SESSION_FORMAT_VERSION` names the direction ("written by a newer harness — upgrade the harness to open it"); one behind it states that this build ships no upgrade path. After legacy-shape normalization, an event type outside this build's generated vocabulary (`KNOWN_SESSION_EVENT_TYPES`, emitted by `gen-persistence-catalog`) refuses the same way unless the event's envelope carries `ignorable: true` — silently skipping an unrecognized required event could change how the rest of the log must be read. The message appends the raw log path when the backend keeps one artifact per session, so the refused text stays reachable. The JSONL backend refuses a foreign version straight from the raw header line, before validating this format version's header shape or decoding any event row — a structurally different future format still reports the upgrade direction, never "corrupt". An out-of-tree backend must enforce the equivalent direction-aware refusal at its own physical-format boundary. Design rationale and the deferred upgrader chain live in the [session-log-version-mechanism note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md).
+A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. A header `version` ahead of `SESSION_FORMAT_VERSION` names the direction ("written by a newer harness — upgrade the harness to open it"); one behind it states that this build ships no upgrade path. An event type outside this build's generated vocabulary (`KNOWN_SESSION_EVENT_TYPES`, emitted by `gen-persistence-catalog`) refuses the same way unless the event's envelope carries `ignorable: true` — silently skipping an unrecognized required event could change how the rest of the log must be read. The message appends the raw log path when the backend keeps one artifact per session, so the refused text stays reachable. The JSONL backend refuses a foreign version straight from the raw header line, before validating this format version's header shape or decoding any event row — a structurally different future format still reports the upgrade direction, never "corrupt". An out-of-tree backend must enforce the equivalent direction-aware refusal at its own physical-format boundary. Design rationale and the deferred upgrader chain live in the [session-log-version-mechanism note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md).
 
 ## `CreateSessionOptions` — seeding and metadata
 
@@ -127,39 +210,11 @@ interface CreateSessionOptions {
 }
 ```
 
-Plain replay is `ctx.sessions.create(id, { seed: seedEvents })`; a fork additionally supplies `inheritedEventCount` and `meta.isSeeded: true`. Resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
-
-## `SessionStorageMetadata` — logical header and inherited cut
-
-Every persistence result that reads a Session body carries `SessionStorageMetadata`: the current logical header plus the separately validated inherited-event cut. Header-only listing intentionally returns only `SessionHeader`.
-
-```ts type-equiv
-/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
-interface SessionStorageMetadata {
-  /** Validated immutable Session header. */
-  readonly meta: SessionHeader
-  /** Number of leading events inherited from the Session's fork parent. */
-  readonly inheritedEventCount: SessionLogOffset
-}
-```
-
-## `SessionRawArtifact` — verbatim stored artifact text
-
-A backend's own artifact text for one session, byte-identical to what it durably wrote (decoded from its physical encoding). `readRaw` returns it without reconstructing from parsed events, so backend-specific serialization (chunk packing, key order, line breaks) survives. Consumers first test `supportsRawArtifacts`: `false` means the backend does not provide this capability, while `readRaw(...) === undefined` means a supported backend has no materialized artifact for that session.
-
-```ts type-equiv
-/** A backend's own raw artifact text for one session, verbatim. */
-interface SessionRawArtifact extends SessionStorageMetadata {
-  /** The artifact's base filename on disk, without any physical encoding suffix. */
-  readonly filename: string
-  /** The artifact's full text content, decoded from the backend's physical encoding. */
-  readonly content: string
-}
-```
+Replay/fork is therefore `ctx.agents.create({ sessionId, seed, meta })` — a fork additionally supplies `inheritedEventCount` with `meta.isSeeded: true`, and only agent-loop-published sessions persist, and the loop stores the seed through the new session's write handle before publication; resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
 
 ## Preparation and restoration ownership
 
-`SessionStore.prepare()` accepts ordinary creation options or fresh persistence graphs transferred through `RestoredSessionOptions`. The restoration branch validates and freezes the transferred header and events in place, so callers must retain no mutable aliases. `SessionPreparation` then owns the exact unpublished Session until publication or rollback; disposal is synchronous and idempotent. Persistence inspection exposes only `SessionInspection`, an immutable logical view borrowed from the same prepared Session.
+`SessionStore.prepare()` accepts ordinary creation options or fresh persistence graphs transferred through `RestoredSessionOptions`. The restoration branch validates and freezes the transferred header and events in place, so callers must retain no mutable aliases. `SessionPreparation` then owns the exact unpublished Session until publication or rollback; disposal is synchronous and idempotent. agent-loop's resume builds these graphs by reading the stored log through the session's write handle and appending any needed `interruptedTurnClosers` before preparation.
 
 ```ts type-equiv
 /**
@@ -215,31 +270,9 @@ declare class SessionPreparation implements Disposable {
 }
 ```
 
-```ts type-equiv
-/** Immutable logical session prepared from persistence or a live owner. */
-interface SessionInspection extends SessionStorageMetadata {
-  /** Validated contiguous logical event log. */
-  readonly events: readonly SessionEvent[]
-}
-```
-
-## Detached stored-log suffixes
-
-`readFrom` returns a detached `SessionEventSuffix` anchored by the requested `fromSeq`. Its event list may start above zero or be empty, so it is not a complete `SessionInspection` and must not be restored as a whole Session.
-
-```ts type-equiv
-/** Detached logical suffix returned by one explicit stored-log offset read. */
-interface SessionEventSuffix extends SessionStorageMetadata {
-  /** First requested log offset; {@link events} contains only seqs at or after it. */
-  readonly fromSeq: SessionLogOffset
-  /** Valid contiguous stored events at or after {@link fromSeq}; not a complete Session log when the offset is nonzero. */
-  readonly events: readonly SessionEvent[]
-}
-```
-
 ## Lightweight source revisions
 
-Consumers of derived state compare a cheap opaque revision before loading a full event log. The persistence backend owns its representation and changes it transactionally with append or mutating load repair; callers compare it only for equality.
+Consumers of derived read models compare a cheap opaque revision before loading a full event log. The revision is a per-backend-instance change token from `stat`/`list`: equal revisions may be treated as an unchanged log; unequal revisions promise nothing, and write-ownership churn never changes one. session-query keys its cold-read cache on it; the token plays no part in open, read, or resume.
 
 ```ts type-equiv
 /**
@@ -250,20 +283,29 @@ type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
 ```
 
 ```ts type-equiv
-/** Lightweight immutable source identity returned without loading a full log. */
+/**
+ * Lightweight stored-session observation returned by {@link SessionPersistence.stat}
+ * and {@link SessionPersistence.list} without reading the full event log.
+ */
 interface SessionPersistenceSnapshot {
-  /** Detached metadata for one materialized session. */
-  header: SessionHeader
-  /** Opaque source-qualified token that changes whenever this stored log changes. */
-  revision: SessionPersistenceRevision
+  /** Detached metadata for one stored session. */
+  readonly header: SessionHeader
+  /** Opaque change token; see {@link SessionPersistence.stat}. */
+  readonly revision: SessionPersistenceRevision
+  /** Logical event count, when the backend can provide it cheaply from metadata; otherwise absent. */
+  readonly eventCount?: number
+  /** Physical artifact byte size, when the backend can provide it cheaply (JSONL); otherwise absent. */
+  readonly sizeBytes?: number
 }
 ```
 
+The optional `eventCount`/`sizeBytes` hints let the session list's cold blank probe bound its work from metadata alone (session-controller config `coldBlankProbeMaxEvents`/`coldBlankProbeMaxBytes`) without opening any log.
+
 ## The backend
 
-The shipped provider implements the abstract `SessionPersistence` contract (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and passes the shared `runPersistenceContract` suite:
+The shipped provider implements the abstract `SessionPersistence` contract (`create`/`open`/`stat`/`list`, with per-session `SessionHandle`s carrying `read`/`append`/`flush`/`close` and optional cancellation throughout) and passes the shared persistence contract suite:
 
-- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
+- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic materialization, per-batch `fsync` appends, and torn-tail truncation before the first new append. `stat`/`list` carry `sizeBytes` and a best-effort `fs.stat`-derived revision.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -277,162 +319,77 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
-Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
+Durable append-only session storage addressed through per-session handles.
+
+Storage semantics shared by every backend: events are contiguous from seq 0 and never rewritten; a torn physical tail is never returned to a reader and is truncated by the write path before its first append; reads validate current-format records only and refuse unknown vocabulary fail-closed. `append` persists best-effort; `flush` — per handle or service-wide — is the durability barrier.
+
+Visibility: a created session is observable through `stat`/`list`/`open` in this process from the moment `create` resolves, even while a backend defers physical materialization (a pure optimization); other processes see the session only once it materializes, and a session that never materialized before a crash never existed. `SessionHandle.flush` forces materialization.
+
+Freshness: once an `append` or `flush` resolves, reads started afterwards on this backend instance observe at least that prefix.
 
 ```ts cordis-catalog
 /**
- * Resolve this backend's independent local artifact for a session without
- * reading, creating, flushing, or otherwise materializing it. A backend
- * that does not own one artifact per Session returns `undefined`.
- * @param meta - the immutable session header whose artifact is requested.
- * @returns the backend-specific absolute location, when one exists.
+ * Create a new stored session and take its write ownership.
+ * @param header - the immutable header (id, version, cwd, lineage) to store.
+ * @param options - optional cancellation.
+ * @returns a `write` handle owned by the caller; close it to release ownership.
+ * @throws {SessionAlreadyExistsError} when the id already exists.
  */
-abstract locate(meta: SessionHeader): SessionLocation | undefined
+abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>
 
 /**
- * Read a session's backend-owned artifact text verbatim — the exact durable
- * bytes the backend wrote (decoded from its physical encoding, e.g. a
- * decompressed JSONL). The returned `content` is the raw text, not a
- * reconstruction from parsed events, so it preserves backend-specific
- * serialization (chunk packing, key order, line breaks). Callers first test
- * {@link supportsRawArtifacts}; `undefined` then means only that the requested
- * session has no materialized artifact.
- * @param _id - the persisted session to read (unused by the default: no
- * per-session artifact).
- * @param signal - optional cancellation for backend read work.
- * @returns the raw artifact plus its parsed header, or `undefined` when the
- * session is absent.
- * @throws when this backend does not expose per-session raw artifacts.
- */
-readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>
-
-/**
- * Register a new session's metadata. A backend MAY defer the physical write
- * until the first {@link append} (lazy materialization), in which case a
- * created-but-never-appended session is absent from {@link list}
- * — abandoned sessions leave nothing behind.
- * @param meta - the immutable header (id, version, cwd, lineage) to record.
- * @param inheritedEventCount - exact fork-inherited prefix length. Required
- * for a seeded header and omitted only for an unseeded header.
- */
-abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>
-
-/**
- * Ensure a live session has a durable header even when it has no events.
- * Ordinary sessions remain lazily materialized; lifecycle frontends call
- * this only when an empty session itself is a durable resumable resource.
- * @param _session - exact live session whose registered header is materialized.
- */
-ensureMaterialized(_session: Session): Promise<void>
-
-/**
- * Durably persist a batch of events. Honors the append-only and contiguous-
- * seq contracts: the first event's `seq` MUST equal the stored next-seq
- * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
- * serializable `event.data` with an error naming the offending event type.
- * A seeded session's first materializing batch must reach its complete
- * inherited prefix.
- * @param id - the session the batch belongs to.
- * @param events - the contiguous batch to persist, in seq order.
- */
-abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
-
-/**
- * Prepare the exact unpublished Session used by resume. Implementations may
- * reuse object graphs retained by an earlier {@link inspect} after confirming
- * their durable revision is still current; disposal releases an unpublished
- * reservation. Revision retries require the durable log to remain unchanged
- * for one read/check round trip; continuous external writers may delay completion.
- * @param id - persisted session to prepare.
- * @param signal - optional cancellation for preparation work.
- * @returns one owned unpublished Session preparation.
- */
-async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
-
-/**
- * Load an immutable balanced logical view and commit any required cold
- * recovery. A complete interrupted final turn is preserved and durably
- * closed with missing tool errors plus any open step and turn boundaries;
- * only a torn final record is discarded. Unknown versions and corruption in
- * the committed prefix reject. Implementations MUST NOT crash-repair an
- * identity still bound to a live Session: a balanced live log may return as a
- * durable snapshot, while an open live turn rejects. Returned values may be
- * shared with immutable live or prepared state and must not be mutated.
- * Revision-based implementations may wait for one stable read/check round trip.
- * @param id - the persisted session to reload.
- * @returns the header and a log ending on a balanced `turn/end`.
- */
-abstract load(id: SessionId): Promise<SessionInspection>
-
-/**
- * Inspect an immutable logical session without committing recovery or
- * publishing it. A cold complete interrupted turn receives synthetic closers
- * in memory and a torn physical tail remains untouched. An already-live
- * Session instead yields its current immutable snapshot, which may contain an
- * open turn and its `session/end-seed` boundary. Coordinator-backed
- * implementations retain the exact cold unpublished Session for bounded
- * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
- * already committing or reserved for resume remains exclusive, and inspection
- * may borrow its immutable view. Callers borrow only the immutable header and
- * log. Continuous external writers may delay revision convergence.
- * @param id - the persisted session to inspect.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns the validated header and current logical event log.
- */
-abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
-
-/**
- * Borrow one exact inspection while retaining any reusable prepared source.
- * A cold observation must pin the exact prepared Session that a later
- * {@link prepare} reserves. Implementations must not degrade this operation
- * to a detached {@link inspect} result.
- * @param id - persisted session to observe.
- * @param signal - optional cancellation for preparation work.
- * @returns a disposable immutable observation.
- */
-abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>
-
-/**
- * Read the stored events from `fromSeq` onward — the read-from-seq
- * primitive for read models that resume from a watermark (e.g. a persisted
- * projection cache folding only the tail past its checkpoint). Unlike
- * {@link inspect}, it is a detached physical suffix read: no preparation
- * cache, torn-tail truncation, synthetic closers, or coordinator-state
- * publication. Only events from the valid contiguous stored prefix are
- * returned, so a torn fragment never reaches the caller. `fromSeq` at or
- * beyond the stored prefix returns an empty event list (never an error).
- * A backend whose medium can seek by seq may read only the suffix;
- * sequential media such as JSONL still parse the whole artifact and skip
- * forward. The primitive bounds what is returned and refolded, not every
- * backend's physical read.
- * @param id - the persisted session to read.
- * @param fromSeq - first event offset to include.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns storage metadata, the requested offset, and stored events with `seq >= fromSeq`.
- */
-abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>
-
-/**
- * Lightweight listing from metadata, without a full-log parse.
- * @param signal - optional cancellation for backend listing work.
- * @returns one header per materialized session.
- */
-abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
-
-/**
- * List materialized sessions with cheap per-log change tokens.
+ * Open an existing stored session.
  *
- * Repeated observations of an unchanged log return the same revision. A
- * successful mutating {@link load} repair changes the next listed revision.
- * Revisions also distinguish independently backed stores so backend-local
- * counters cannot compare equal across different persistence sources.
- * @param signal - optional cancellation for backend snapshot-listing work.
- * @returns one header and opaque revision per materialized session without loading full logs.
+ * `read` never takes ownership and works while another handle (or process)
+ * holds write ownership. `write` atomically claims single-writer ownership;
+ * an existing active owner rejects.
+ * @param id - the stored session to open.
+ * @param access - `read` or `write`.
+ * @param options - optional cancellation.
+ * @returns the open handle.
+ * @throws {SessionPersistenceNotFoundError} when the session does not exist.
+ * @throws {SessionAlreadyOwnedError} for `write` when ownership is taken.
  */
-abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>
+
+/**
+ * Flush every active write handle owned by this service instance in one
+ * durability barrier: each handle's routed live events drain durably and
+ * its session materializes, exactly as that handle's own
+ * `SessionHandle.flush` would. Read handles buffer nothing and are
+ * untouched. A handle closed concurrently counts as flushed — close itself
+ * drains durably.
+ * @returns resolution once every write handle active at the call has flushed.
+ * @throws {AggregateError} naming each session whose flush failed; the
+ *   remaining handles still flush.
+ */
+abstract flush(): Promise<void>
+
+/**
+ * Observe one stored session without reading its event log or taking
+ * ownership.
+ *
+ * The snapshot's `revision` is an opaque change token comparable only
+ * against revisions from the same service instance and session id: equal
+ * revisions may be treated as an unchanged log; unequal revisions promise
+ * nothing. Write-ownership churn does not change a revision. It exists for
+ * derived read-model caches keyed off `stat`/`list`; it plays no part in
+ * open, read, or resume.
+ * @param id - the stored session to observe.
+ * @param options - optional cancellation.
+ * @returns the snapshot, or `undefined` when the session does not exist.
+ */
+abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>
+
+/**
+ * List every stored session visible to this process, in no promised order.
+ * @param options - optional cancellation.
+ * @returns one snapshot per stored session.
+ */
+abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>
 ```
 
-Types: [Session](session.md) · [SessionEvent](session.md) · [SessionId](core.md) · [SessionLogOffset](session.md)
+Types: [SessionId](core.md)
 
 Source: [`packages/session/session-persistence/src/index.ts`](../../packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 08cc35d987..6f8430868a 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -4,29 +4,112 @@
 
 事件日志的**持久性 seam**。[session.md](session.zh.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的提供方模型与随产品交付的 JSONL 后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.zh.md)中逐项列举。
 
-该 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**。仓库随产品交付 [dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl) 作为提供方；仓库外提供方可以实现同一服务约定。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md)。
+该 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上暴露 `create`/`open`/`stat`/`list`——**没有平行的持久化事件类型**——其中 `create` 与 `open` 返回逐会话的 `SessionHandle`（`read`/`append`/`flush`/`close`），它承载全部日志访问与单写者所有权。仓库随产品交付 [dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl) 作为其 provider；仓库外 provider 可以实现同一服务约定。见[基于句柄的持久化 Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md)与 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md)。
 
-## flush 检查点
+## `SessionHandle`——通向已存储会话的一条打开通道
 
-`session/event` 是一个*同步*通知；持久化插件会将事件复制到逐会话控制器，而不阻塞生产方。第一个待处理事件会开启固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个持久化批次；该次写入期间接纳的事件会获得自己的截止时间，并形成后续批次。`session/flush` 会取消等待并排空至完全停稳，因此循环仍将其用作在领取下一个普通轮次之前的顺序与错误观察检查点。后台写入被拒绝时会保留对应事件并暂停自动重试；新事件会开启新的固定窗口，而显式 flush 会立即重试，并通过 `agent/error` 和 logger 报告失败，绝不会把失败记录成已关闭轮次之后的会话事件。dispose（资源释放）会执行同样的最终排空。配置的最大值只限制有意的批处理等待，不限制事件循环调度或后端完成持久化的延迟（[决策](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md)）。
-
-## 崩溃恢复保留被中断的轮次
-
-后端重新加载一个在轮次中途崩溃的日志时，会发现一个已打开的 `turn/start` 却没有 `turn/end`。它**不会**截断日志：在长周期任务中，单个轮次可能非常庞大（许多步骤、大量工具输出），而这些事件在崩溃前已被持久追加。后端改为用一个合成的 `turn/end { reason: { kind: 'interrupted' } }` 关闭这个遗留轮次，在不改变其前后任何独立事件的情况下配平被中断的执行。`interrupted` 是唯一一个不由循环发出的 `TurnEndReason`（见 [session.md](session.zh.md#why-a-turn-ended-turnendreasonmap)）。
-
-修复仅适用于冷会话。对于活跃 id，`SessionPersistence.load(id)` 会等待权威内存快照完成持久化，并且只在日志平衡时返回；若活跃轮次仍未闭合，则拒绝操作，而不是添加合成的中断边界。HMR（热模块替换）会接管活跃前缀，而不会关闭其中正在进行的轮次。
-
-`SessionPersistence.inspect(id)` 会构造一个不可变的逻辑 Session，但不发布它，也不写入恢复内容。冷检查会在内存中配平中断的轮次，同时保持撕裂的物理尾部不变；检查已处于活跃状态的 Session 则借用其当前不可变快照，因此可能包含未闭合的轮次。使用协调器的实现会在有界 LRU 中保留这个精确的冷未发布 Session，因此重复历史读取与后续 `prepare(id)` 可复用同一次读取、解压、验证、冻结及 Session 构造。`prepare(id)` 会预留该 Session、提交待处理修复并返回可 dispose 的发布句柄；`load(id)` 使用相同机制提交修复，但不会发布 Session。该生命周期由 [Session 准备阶段决策](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md)定义。
-
-## `SessionLocation`——可选的逐会话产物目标
-
-`SessionPersistence.locate(meta)` 会同步解析一个归后端所有的独立产物，而不会读取、创建或 flush 它。JSONL 返回其项目/会话目录内 transcript（文本记录）的绝对路径；不为每个会话各自拥有独立产物的后端返回 `undefined`。因此，返回的路径可能指向尚不存在的文件，或指向还不包含当前尚未 flush 轮次的文件；它是位置提示，不是授权或新鲜度保证。
+每一次日志读写都经由句柄流动，绝不经由按 id 寻址的服务方法：句柄是未来跨进程写租约将要把守的那扇唯一的门。一种句柄类型同时服务两种访问——在 `read` 句柄上执行修改是运行时的 `SessionReadOnlyError`，而非类型层面的拆分——而进程内单写者所有权使得在已有活跃持有者时第二次 `open(id, 'write')` 以 `SessionAlreadyOwnedError` 拒绝。
 
 ```ts type-equiv
 /**
- * A backend-resolved, per-session local artifact location. The path is an
- * absolute target path and can name an artifact that has not materialized yet.
- * Consumers must treat it as a location hint, never as an authorization token.
+ * One open channel onto a stored session. A handle is single-owner state, not
+ * a shared service: `read` never backtracks below what this handle already
+ * observed, a `write` handle reads its own successful appends, and `close()`
+ * is the one teardown (idempotent, uncancellable; `Symbol.asyncDispose`
+ * delegates to it). Every operation on a closed handle rejects with
+ * `SessionHandleClosedError`.
+ *
+ * Freshness across handles: once an `append` or `flush` resolves on a write
+ * handle, every read STARTED afterwards on the same backend instance — on any
+ * handle, or through `stat`/`list` — observes at least that prefix.
+ * Reads concurrent with a mutation carry no ordering promise beyond the valid
+ * contiguous prefix.
+ */
+interface SessionHandle extends AsyncDisposable {
+  /** The stored session this handle addresses. */
+  readonly id: SessionId
+  /** The immutable stored header, fixed at `create`/`open`. */
+  readonly header: SessionHeader
+  /**
+   * Exact fork-inherited prefix length stored with the log; `0` when
+   * `header.isSeeded` is false. Storage metadata paired with the header for
+   * every body read, never part of the replayable event log.
+   */
+  readonly inheritedEventCount: SessionLogOffset
+  /** Whether this handle may mutate the log. */
+  readonly access: SessionAccess
+
+  /**
+   * Read a slice of the valid contiguous logical log. The slice is a legal log
+   * prefix segment: a torn physical tail is never returned, and repeated reads
+   * on this handle never observe an older state than a prior read.
+   * @param offset - first logical event seq to include; defaults to `0`.
+   * @param length - maximum number of events to return; defaults to the rest
+   *   of the log. An offset at or past the end returns an empty list.
+   * @param options - optional cancellation.
+   * @returns the events with `seq >= offset`, at most `length` of them.
+   */
+  read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<readonly SessionEvent[]>
+
+  /**
+   * Append a contiguous batch continuing the current logical end. The first
+   * event's `seq` MUST equal the stored next-seq; committed events are never
+   * rewritten. Persistence is best-effort: on resolution the batch is
+   * accepted, ordered, and visible to reads on this backend instance, but
+   * only a resolved {@link flush} promises it survives a crash — a backend
+   * may buffer or batch physical writes behind append. Rejects with
+   * `SessionReadOnlyError` on a read handle and `SessionOwnershipLostError`
+   * when write ownership is gone.
+   * @param events - the contiguous batch, in seq order.
+   * @param options - optional cancellation observed before the write starts.
+   */
+  append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>
+
+  /**
+   * The durability barrier — the one operation that promises storage: on
+   * resolution every acknowledged append is durable and the session is
+   * materialized for other processes; an empty created session becomes
+   * durably listable here. Callers that must survive a crash flush; a backend
+   * whose `append` already persists on resolution treats this as
+   * materialize-if-needed. Rejects with `SessionReadOnlyError` on a read
+   * handle.
+   * @param options - optional cancellation observed before the barrier starts.
+   */
+  flush(options?: SessionHandleFlushOptions): Promise<void>
+
+  /**
+   * Release the handle: a read handle frees local resources; a write handle
+   * completes pending durability and releases write ownership. Idempotent,
+   * asynchronous, and deliberately not cancellable.
+   */
+  close(): Promise<void>
+}
+```
+
+已创建的会话自 `create` 完成之刻起即可在本进程内被观察到，而后端可以把物理实体化（纯粹的优化）推迟到第一次 `append` 或 `flush`；其他进程只能看到已实体化的会话，一个在崩溃前从未实体化的会话等于从未存在。
+
+## flush 检查点
+
+`session/event` 是一个*同步*通知；挂载的后端按会话 id 把它路由进活跃写句柄的有界 write-behind 窗口，而不阻塞生产方（后端一次性安装这些监听器，因为持久化已保证每个 id 只有一个活跃写句柄）。第一个待处理事件会开启固定的内部批处理窗口，后续事件会加入但不会重置其截止时间。窗口到期后会通过该会话的写句柄启动一次持久化 `append`；该次写入期间接纳的事件会获得自己的截止时间，并形成后续批次。`session/flush` 会取消等待并排空至完全停稳，因此循环仍将其用作在领取下一个普通轮次之前的顺序与错误观察检查点。后台写入被拒绝时会按序保留对应事件、暂停自动路径，并通过 logger 报告；下一次显式 flush 会重试，并向其调用方响亮地拒绝。`session/disposed` 会执行同样的最终排空并关闭句柄，而 `close()` 本身会经由仍然打开的存储排空已路由的缓冲，因此后端 teardown 的关闭清扫不丢任何数据。该窗口只限制有意的批处理等待，不限制事件循环调度或后端完成持久化的延迟（[决策](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md)）。
+
+## 崩溃恢复保留被中断的轮次
+
+一个在轮次中途崩溃的日志以打开的 `turn/start` 而无 `turn/end` 结束。持久化**不会**截断或修复它：在长周期任务中，单个轮次可能非常庞大（许多步骤、大量工具输出），而这些事件在崩溃前已被持久追加。它返回物理上有效的连续日志；只有撕裂物理尾部——属于一次从未完成的 append——中不完整的碎片会被丢弃：从中恢复的完整记录（JSONL 后端会部分解码撕裂的 Zstandard 帧）由写路径在句柄的第一次新 append 之前持久重写。修复是读方的职责：resume（agent-loop）通过其写句柄读取已存储的日志，计算 `interruptedTurnClosers`——缺失的工具错误、任何未闭合的 `step/end`，以及一个合成的 `turn/end { reason: { kind: 'interrupted' } }`——并在发布 Session 之前把它们作为普通批次通过同一句柄追加。`interrupted` 是唯一一个不由循环发出的 `TurnEndReason`（见 [session.md](session.zh.md#why-a-turn-ended-turnendreasonmap)）。
+
+因此修复只在写所有权之下写入：活跃会话的写句柄由其生命周期所有者持有，故并发的 `open(id, 'write')` 会以 `SessionAlreadyOwnedError` 拒绝，而不是让修复与活跃轮次竞速。只读观察方（session-query）仅在内存中用同样的闭合事件配平被中断的冷日志，不回写任何内容。
+
+只读观察即 `open(id, 'read')`：句柄提供经过验证的连续前缀切片，绝不返回撕裂尾部，且同一句柄上的重复读取绝不会观察到比先前读取更旧的状态。持久化侧不存在已准备 Session 缓存：session-query 拥有自己的冷读缓存，按 `stat().revision` 变更令牌为每个 id 缓存一个已配平的冷 Session，仅在令牌变化时重新读取。该生命周期由[基于句柄的持久化 Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md)定义；[Session 准备阶段决策](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md)记录仍然保留的发布边界 `SessionPreparation`。
+
+## `SessionLocation`——拒绝诊断的产物目标
+
+`SessionLocation` 不是面向消费者的查询：日志访问走会话句柄的 `read`。它仅作为拒绝诊断存在，使 `SessionFormatUnsupportedError` 能指出本构建拒绝解读的原始日志。JSONL 提供其项目/会话目录内 transcript（文本记录）的绝对路径；没有逐会话工件的后端则不提供。
+
+```ts type-equiv
+/**
+ * A backend-resolved, per-session local artifact location. Carried only by
+ * refusal diagnostics ({@link SessionFormatUnsupportedError}) so a user can
+ * find the raw log a build refused to interpret; it is not a consumer-facing
+ * query — log access goes through a session handle's `read`.
  */
 interface SessionLocation {
   /** Backend-specific artifact kind, for example `jsonl`. */
@@ -91,7 +174,7 @@ interface SessionHeader {
 
 ## 格式拒绝：本构建无法可靠读取的日志
 
-后端用 `SessionFormatUnsupportedError` 拒绝无法可靠解读的日志，它与 `SessionPersistenceCorruptionError` 区分，因为数据没有损坏。header 的 `version` 比 `SESSION_FORMAT_VERSION` 新时，消息说明方向（"由更新的 harness 写入，请升级 harness 后打开"）；比它旧时说明本构建没有升级路径。经过 legacy 形状归一化后，本构建生成词汇表（`KNOWN_SESSION_EVENT_TYPES`，由 `gen-persistence-catalog` 生成）之外的事件类型同样被拒绝，除非该事件的信封带 `ignorable: true`：静默跳过一个不认识的必需事件可能改变日志其余部分的解读方式。后端为每个会话保留独立文件时，消息附上原始日志路径，被拒绝的文本仍然可读。JSONL 后端直接从原始 header 行拒绝外来版本，先于本格式版本的 header 形状校验和任何事件行解码，因此结构完全不同的未来格式仍会报告升级方向，绝不会报"损坏"。仓库外后端必须在自己的物理格式入口执行等价的方向感知拒绝。设计理由与推迟建设的升级器链见 [session-log 版本机制 Agent Note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.zh.md)。
+后端用 `SessionFormatUnsupportedError` 拒绝无法可靠解读的日志，它与 `SessionPersistenceCorruptionError` 区分，因为数据没有损坏。header 的 `version` 比 `SESSION_FORMAT_VERSION` 新时，消息说明方向（"由更新的 harness 写入，请升级 harness 后打开"）；比它旧时说明本构建没有升级路径。本构建生成词汇表（`KNOWN_SESSION_EVENT_TYPES`，由 `gen-persistence-catalog` 生成）之外的事件类型同样被拒绝，除非该事件的信封带 `ignorable: true`：静默跳过一个不认识的必需事件可能改变日志其余部分的解读方式。后端为每个会话保留独立文件时，消息附上原始日志路径，被拒绝的文本仍然可读。JSONL 后端直接从原始 header 行拒绝外来版本，先于本格式版本的 header 形状校验和任何事件行解码，因此结构完全不同的未来格式仍会报告升级方向，绝不会报"损坏"。仓库外后端必须在自己的物理格式入口执行等价的方向感知拒绝。设计理由与推迟建设的升级器链见 [session-log 版本机制 Agent Note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.zh.md)。
 
 ## `CreateSessionOptions`：seed 与元数据
 
@@ -127,39 +210,11 @@ interface CreateSessionOptions {
 }
 ```
 
-因此，普通回放的调用方式为 `ctx.sessions.create(id, { seed: seedEvents })`；fork 还会提供 `inheritedEventCount` 与 `meta.isSeeded: true`。将一个*持久化*会话恢复为活跃 agent 的调用方式为 `ctx.agents.resume({ resumeSessionId })`。
-
-## `SessionStorageMetadata`：逻辑 header 与继承 cut
-
-每个读取 Session 正文的持久化结果都携带 `SessionStorageMetadata`：当前逻辑 header，以及单独校验的继承事件 cut。仅 header 的列表操作有意只返回 `SessionHeader`。
-
-```ts type-equiv
-/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
-interface SessionStorageMetadata {
-  /** Validated immutable Session header. */
-  readonly meta: SessionHeader
-  /** Number of leading events inherited from the Session's fork parent. */
-  readonly inheritedEventCount: SessionLogOffset
-}
-```
-
-## `SessionRawArtifact`——逐字存储工件文本
-
-后端为单个会话自持的工件文本，与其持久化写入的字节逐字一致（按物理编码解码）。`readRaw` 返回它而不从解析后事件重建，因此后端特定的序列化（chunk 打包、键序、换行）得以保留。Consumer 须先检查 `supportsRawArtifacts`：`false` 表示后端不提供此能力，而 `readRaw(...) === undefined` 表示受支持的后端没有该会话的已实体化工件。
-
-```ts type-equiv
-/** A backend's own raw artifact text for one session, verbatim. */
-interface SessionRawArtifact extends SessionStorageMetadata {
-  /** The artifact's base filename on disk, without any physical encoding suffix. */
-  readonly filename: string
-  /** The artifact's full text content, decoded from the backend's physical encoding. */
-  readonly content: string
-}
-```
+因此，回放/fork 的调用方式为 `ctx.agents.create({ sessionId, seed, meta })`——fork 还会随 `meta.isSeeded: true` 提供 `inheritedEventCount`，且只有经 agent-loop 发布的会话才会持久化，且循环会在发布之前通过新会话的写句柄存储 seed；将一个*持久化*会话恢复为活跃 agent 的调用方式为 `ctx.agents.resume({ resumeSessionId })`。
 
 ## 准备与恢复所有权
 
-`SessionStore.prepare()` 接收普通创建选项，或通过 `RestoredSessionOptions` 转移所有权的全新的持久化对象图。恢复分支会就地验证并冻结转移来的 header 与事件，因此调用方不得保留可变别名。`SessionPreparation` 随后持有该精确的未发布 Session，直至发布或回滚；dispose 是同步且幂等的。持久化检查只暴露 `SessionInspection`，即从同一个已准备 Session 借用的不可变逻辑视图。
+`SessionStore.prepare()` 接收普通创建选项，或通过 `RestoredSessionOptions` 转移所有权的全新的持久化对象图。恢复分支会就地验证并冻结转移来的 header 与事件，因此调用方不得保留可变别名。`SessionPreparation` 随后持有该精确的未发布 Session，直至发布或回滚；dispose 是同步且幂等的。agent-loop 的 resume 通过该会话的写句柄读取已存储的日志，并在准备之前追加所需的 `interruptedTurnClosers`，以此构建这些对象图。
 
 ```ts type-equiv
 /**
@@ -215,31 +270,9 @@ declare class SessionPreparation implements Disposable {
 }
 ```
 
-```ts type-equiv
-/** Immutable logical session prepared from persistence or a live owner. */
-interface SessionInspection extends SessionStorageMetadata {
-  /** Validated contiguous logical event log. */
-  readonly events: readonly SessionEvent[]
-}
-```
-
-## 分离的持久日志后缀
-
-`readFrom` 返回以请求的 `fromSeq` 为锚点、与其他状态分离的 `SessionEventSuffix`。其事件列表可能从非零位置开始，也可能为空，因此它不是完整的 `SessionInspection`，不得作为完整 Session 恢复。
-
-```ts type-equiv
-/** Detached logical suffix returned by one explicit stored-log offset read. */
-interface SessionEventSuffix extends SessionStorageMetadata {
-  /** First requested log offset; {@link events} contains only seqs at or after it. */
-  readonly fromSeq: SessionLogOffset
-  /** Valid contiguous stored events at or after {@link fromSeq}; not a complete Session log when the offset is nonzero. */
-  readonly events: readonly SessionEvent[]
-}
-```
-
 ## 轻量源修订号
 
-派生状态的消费方会在加载完整事件日志之前比较一个低开销的不透明修订号。其表示由持久化后端拥有，并随 append 或会修改数据的 load 修复以事务方式改变；调用方仅比较修订号是否相等。
+派生读取模型的消费方会在加载完整事件日志之前比较一个低开销的不透明修订号。该修订号是来自 `stat`/`list` 的逐后端实例变更令牌：修订号相等可视为日志未变；不相等则不作任何承诺，且写所有权的变动绝不会改变修订号。session-query 以它为键管理冷读缓存；该令牌在 open、read 或 resume 中不起任何作用。
 
 ```ts type-equiv
 /**
@@ -250,20 +283,29 @@ type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
 ```
 
 ```ts type-equiv
-/** Lightweight immutable source identity returned without loading a full log. */
+/**
+ * Lightweight stored-session observation returned by {@link SessionPersistence.stat}
+ * and {@link SessionPersistence.list} without reading the full event log.
+ */
 interface SessionPersistenceSnapshot {
-  /** Detached metadata for one materialized session. */
-  header: SessionHeader
-  /** Opaque source-qualified token that changes whenever this stored log changes. */
-  revision: SessionPersistenceRevision
+  /** Detached metadata for one stored session. */
+  readonly header: SessionHeader
+  /** Opaque change token; see {@link SessionPersistence.stat}. */
+  readonly revision: SessionPersistenceRevision
+  /** Logical event count, when the backend can provide it cheaply from metadata; otherwise absent. */
+  readonly eventCount?: number
+  /** Physical artifact byte size, when the backend can provide it cheaply (JSONL); otherwise absent. */
+  readonly sizeBytes?: number
 }
 ```
 
+可选的 `eventCount`/`sizeBytes` 提示让会话列表的冷空白探测（cold blank probe）仅凭元数据即可限定其工作量（session-controller 配置 `coldBlankProbeMaxEvents`/`coldBlankProbeMaxBytes`），而无需打开任何日志。
+
 ## 后端
 
-随产品交付的 provider 实现抽象 `SessionPersistence` 约定（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过共享的 `runPersistenceContract` 套件：
+随产品交付的 provider 实现抽象 `SessionPersistence` 约定（`create`/`open`/`stat`/`list`，逐会话 `SessionHandle` 承载 `read`/`append`/`flush`/`close`，全程可选支持取消），并通过共享的持久化契约套件：
 
-- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——逐会话仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
+- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——逐会话仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；具备崩溃安全的原子实体化、逐批 `fsync` 的 append，以及在第一次新 append 之前截断撕裂尾部。`stat`/`list` 携带 `sizeBytes` 与尽力而为的、由 `fs.stat` 派生的修订号。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -277,162 +319,77 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
-Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
+Durable append-only session storage addressed through per-session handles.
+
+Storage semantics shared by every backend: events are contiguous from seq 0 and never rewritten; a torn physical tail is never returned to a reader and is truncated by the write path before its first append; reads validate current-format records only and refuse unknown vocabulary fail-closed. `append` persists best-effort; `flush` — per handle or service-wide — is the durability barrier.
+
+Visibility: a created session is observable through `stat`/`list`/`open` in this process from the moment `create` resolves, even while a backend defers physical materialization (a pure optimization); other processes see the session only once it materializes, and a session that never materialized before a crash never existed. `SessionHandle.flush` forces materialization.
+
+Freshness: once an `append` or `flush` resolves, reads started afterwards on this backend instance observe at least that prefix.
 
 ```ts cordis-catalog
 /**
- * Resolve this backend's independent local artifact for a session without
- * reading, creating, flushing, or otherwise materializing it. A backend
- * that does not own one artifact per Session returns `undefined`.
- * @param meta - the immutable session header whose artifact is requested.
- * @returns the backend-specific absolute location, when one exists.
+ * Create a new stored session and take its write ownership.
+ * @param header - the immutable header (id, version, cwd, lineage) to store.
+ * @param options - optional cancellation.
+ * @returns a `write` handle owned by the caller; close it to release ownership.
+ * @throws {SessionAlreadyExistsError} when the id already exists.
  */
-abstract locate(meta: SessionHeader): SessionLocation | undefined
+abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>
 
 /**
- * Read a session's backend-owned artifact text verbatim — the exact durable
- * bytes the backend wrote (decoded from its physical encoding, e.g. a
- * decompressed JSONL). The returned `content` is the raw text, not a
- * reconstruction from parsed events, so it preserves backend-specific
- * serialization (chunk packing, key order, line breaks). Callers first test
- * {@link supportsRawArtifacts}; `undefined` then means only that the requested
- * session has no materialized artifact.
- * @param _id - the persisted session to read (unused by the default: no
- * per-session artifact).
- * @param signal - optional cancellation for backend read work.
- * @returns the raw artifact plus its parsed header, or `undefined` when the
- * session is absent.
- * @throws when this backend does not expose per-session raw artifacts.
- */
-readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>
-
-/**
- * Register a new session's metadata. A backend MAY defer the physical write
- * until the first {@link append} (lazy materialization), in which case a
- * created-but-never-appended session is absent from {@link list}
- * — abandoned sessions leave nothing behind.
- * @param meta - the immutable header (id, version, cwd, lineage) to record.
- * @param inheritedEventCount - exact fork-inherited prefix length. Required
- * for a seeded header and omitted only for an unseeded header.
- */
-abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>
-
-/**
- * Ensure a live session has a durable header even when it has no events.
- * Ordinary sessions remain lazily materialized; lifecycle frontends call
- * this only when an empty session itself is a durable resumable resource.
- * @param _session - exact live session whose registered header is materialized.
- */
-ensureMaterialized(_session: Session): Promise<void>
-
-/**
- * Durably persist a batch of events. Honors the append-only and contiguous-
- * seq contracts: the first event's `seq` MUST equal the stored next-seq
- * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
- * serializable `event.data` with an error naming the offending event type.
- * A seeded session's first materializing batch must reach its complete
- * inherited prefix.
- * @param id - the session the batch belongs to.
- * @param events - the contiguous batch to persist, in seq order.
- */
-abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
-
-/**
- * Prepare the exact unpublished Session used by resume. Implementations may
- * reuse object graphs retained by an earlier {@link inspect} after confirming
- * their durable revision is still current; disposal releases an unpublished
- * reservation. Revision retries require the durable log to remain unchanged
- * for one read/check round trip; continuous external writers may delay completion.
- * @param id - persisted session to prepare.
- * @param signal - optional cancellation for preparation work.
- * @returns one owned unpublished Session preparation.
- */
-async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
-
-/**
- * Load an immutable balanced logical view and commit any required cold
- * recovery. A complete interrupted final turn is preserved and durably
- * closed with missing tool errors plus any open step and turn boundaries;
- * only a torn final record is discarded. Unknown versions and corruption in
- * the committed prefix reject. Implementations MUST NOT crash-repair an
- * identity still bound to a live Session: a balanced live log may return as a
- * durable snapshot, while an open live turn rejects. Returned values may be
- * shared with immutable live or prepared state and must not be mutated.
- * Revision-based implementations may wait for one stable read/check round trip.
- * @param id - the persisted session to reload.
- * @returns the header and a log ending on a balanced `turn/end`.
- */
-abstract load(id: SessionId): Promise<SessionInspection>
-
-/**
- * Inspect an immutable logical session without committing recovery or
- * publishing it. A cold complete interrupted turn receives synthetic closers
- * in memory and a torn physical tail remains untouched. An already-live
- * Session instead yields its current immutable snapshot, which may contain an
- * open turn and its `session/end-seed` boundary. Coordinator-backed
- * implementations retain the exact cold unpublished Session for bounded
- * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
- * already committing or reserved for resume remains exclusive, and inspection
- * may borrow its immutable view. Callers borrow only the immutable header and
- * log. Continuous external writers may delay revision convergence.
- * @param id - the persisted session to inspect.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns the validated header and current logical event log.
- */
-abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
-
-/**
- * Borrow one exact inspection while retaining any reusable prepared source.
- * A cold observation must pin the exact prepared Session that a later
- * {@link prepare} reserves. Implementations must not degrade this operation
- * to a detached {@link inspect} result.
- * @param id - persisted session to observe.
- * @param signal - optional cancellation for preparation work.
- * @returns a disposable immutable observation.
- */
-abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>
-
-/**
- * Read the stored events from `fromSeq` onward — the read-from-seq
- * primitive for read models that resume from a watermark (e.g. a persisted
- * projection cache folding only the tail past its checkpoint). Unlike
- * {@link inspect}, it is a detached physical suffix read: no preparation
- * cache, torn-tail truncation, synthetic closers, or coordinator-state
- * publication. Only events from the valid contiguous stored prefix are
- * returned, so a torn fragment never reaches the caller. `fromSeq` at or
- * beyond the stored prefix returns an empty event list (never an error).
- * A backend whose medium can seek by seq may read only the suffix;
- * sequential media such as JSONL still parse the whole artifact and skip
- * forward. The primitive bounds what is returned and refolded, not every
- * backend's physical read.
- * @param id - the persisted session to read.
- * @param fromSeq - first event offset to include.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns storage metadata, the requested offset, and stored events with `seq >= fromSeq`.
- */
-abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>
-
-/**
- * Lightweight listing from metadata, without a full-log parse.
- * @param signal - optional cancellation for backend listing work.
- * @returns one header per materialized session.
- */
-abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
-
-/**
- * List materialized sessions with cheap per-log change tokens.
+ * Open an existing stored session.
  *
- * Repeated observations of an unchanged log return the same revision. A
- * successful mutating {@link load} repair changes the next listed revision.
- * Revisions also distinguish independently backed stores so backend-local
- * counters cannot compare equal across different persistence sources.
- * @param signal - optional cancellation for backend snapshot-listing work.
- * @returns one header and opaque revision per materialized session without loading full logs.
+ * `read` never takes ownership and works while another handle (or process)
+ * holds write ownership. `write` atomically claims single-writer ownership;
+ * an existing active owner rejects.
+ * @param id - the stored session to open.
+ * @param access - `read` or `write`.
+ * @param options - optional cancellation.
+ * @returns the open handle.
+ * @throws {SessionPersistenceNotFoundError} when the session does not exist.
+ * @throws {SessionAlreadyOwnedError} for `write` when ownership is taken.
  */
-abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>
+
+/**
+ * Flush every active write handle owned by this service instance in one
+ * durability barrier: each handle's routed live events drain durably and
+ * its session materializes, exactly as that handle's own
+ * `SessionHandle.flush` would. Read handles buffer nothing and are
+ * untouched. A handle closed concurrently counts as flushed — close itself
+ * drains durably.
+ * @returns resolution once every write handle active at the call has flushed.
+ * @throws {AggregateError} naming each session whose flush failed; the
+ *   remaining handles still flush.
+ */
+abstract flush(): Promise<void>
+
+/**
+ * Observe one stored session without reading its event log or taking
+ * ownership.
+ *
+ * The snapshot's `revision` is an opaque change token comparable only
+ * against revisions from the same service instance and session id: equal
+ * revisions may be treated as an unchanged log; unequal revisions promise
+ * nothing. Write-ownership churn does not change a revision. It exists for
+ * derived read-model caches keyed off `stat`/`list`; it plays no part in
+ * open, read, or resume.
+ * @param id - the stored session to observe.
+ * @param options - optional cancellation.
+ * @returns the snapshot, or `undefined` when the session does not exist.
+ */
+abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>
+
+/**
+ * List every stored session visible to this process, in no promised order.
+ * @param options - optional cancellation.
+ * @returns one snapshot per stored session.
+ */
+abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>
 ```
 
-Types: [Session](session.zh.md) · [SessionEvent](session.zh.md) · [SessionId](core.zh.md) · [SessionLogOffset](session.zh.md)
+Types: [SessionId](core.zh.md)
 
 Source: [`packages/session/session-persistence/src/index.ts`](../../packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index fd7e96441a..1de3205623 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
-session-projection.md: c8a5d4c1b05d830be3224e2e04db1762fe4b3c8f
-session-projection.zh.md: d46c4f1589f57e560d70871d011245a3547c7825
+session-projection.md: e02ae8e36e79c4630a3799bf125ba8567db732cd
+session-projection.zh.md: f95545ab3d5492c80400eea413ad0cfa4ff7fb90
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index c8a5d4c1b0..e02ae8e36e 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -271,9 +271,9 @@ checkpoint(session: Session): ProjectionCheckpoint
  * yields an end below every watermark and the restore rejects for a full
  * re-read.
  * @param checkpoint - persisted rows for one session (possibly stale or empty).
- * @returns the seq to hand the persistence `readFrom`, or `undefined`
- *   when no unit is registered (no read needed — {@link restore} would
- *   serve empty values regardless).
+ * @returns the offset for the stored-log suffix read (`SessionHandle.read`),
+ *   or `undefined` when no unit is registered (no read needed —
+ *   {@link restore} would serve empty values regardless).
  */
 restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined
 
@@ -294,8 +294,8 @@ viewCheckpoint( checkpoint: ProjectionCheckpoint, keys?: readonly Extract<keyof
  * Cold read: fold every persisted unit over a stored log suffix, seeding
  * each from its checkpoint row when usable — the one read recipe (cached
  * state + forward tail replay + `view`) applied without a live `Session`.
- * Call with the events returned by a persistence
- * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+ * Call with the stored events at or past `restoreFloor(checkpoint)` (a
+ * `SessionHandle.read` slice) and that same floor as
  * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
  * so a shrunk log is detected here. A row is usable iff its
  * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index d46c4f1589..f95545ab3d 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -271,9 +271,9 @@ checkpoint(session: Session): ProjectionCheckpoint
  * yields an end below every watermark and the restore rejects for a full
  * re-read.
  * @param checkpoint - persisted rows for one session (possibly stale or empty).
- * @returns the seq to hand the persistence `readFrom`, or `undefined`
- *   when no unit is registered (no read needed — {@link restore} would
- *   serve empty values regardless).
+ * @returns the offset for the stored-log suffix read (`SessionHandle.read`),
+ *   or `undefined` when no unit is registered (no read needed —
+ *   {@link restore} would serve empty values regardless).
  */
 restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined
 
@@ -294,8 +294,8 @@ viewCheckpoint( checkpoint: ProjectionCheckpoint, keys?: readonly Extract<keyof
  * Cold read: fold every persisted unit over a stored log suffix, seeding
  * each from its checkpoint row when usable — the one read recipe (cached
  * state + forward tail replay + `view`) applied without a live `Session`.
- * Call with the events returned by a persistence
- * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+ * Call with the stored events at or past `restoreFloor(checkpoint)` (a
+ * `SessionHandle.read` slice) and that same floor as
  * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
  * so a shrunk log is detected here. A row is usable iff its
  * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index 6ade7bbe1b..5371ae0b34 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/subsystems/session-query.md
-session-query.md: 4317fa3d706dd40c596114a396ba746da67a979f
-session-query.zh.md: 4b67706aea3d3f73304e4c8ad0c689a4c77a13a1
+session-query.md: 1cf3dff325db76485a0afca4ca1a882a4ff175b8
+session-query.zh.md: 2b8504dfb9ec8ee25d925135dbc99fa7beaede98
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index 4317fa3d70..1cf3dff325 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -22,7 +22,7 @@ interface SessionRecord {
   header: SessionHeader
   /** Whether the id currently exists in `ctx.sessions`. */
   live: boolean
-  /** Whether the active persistence backend currently materializes the id. */
+  /** Whether the active persistence backend currently lists the id, including a created-but-unmaterialized session it already observes. */
   persisted: boolean
 }
 ```
@@ -36,7 +36,7 @@ interface SessionLogSnapshot {
   session: SessionHeader
   /** Exact number of fork-inherited events in the observed log. */
   inheritedEventCount: SessionLogOffset
-  /** Cloned contiguous raw events after persistence repair and replay validation. */
+  /** Cloned contiguous raw events after in-memory interrupted-turn balancing and replay validation. */
   events: SessionEvent[]
 }
 ```
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index 4b67706aea..2b8504dfb9 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -22,7 +22,7 @@ interface SessionRecord {
   header: SessionHeader
   /** Whether the id currently exists in `ctx.sessions`. */
   live: boolean
-  /** Whether the active persistence backend currently materializes the id. */
+  /** Whether the active persistence backend currently lists the id, including a created-but-unmaterialized session it already observes. */
   persisted: boolean
 }
 ```
@@ -36,7 +36,7 @@ interface SessionLogSnapshot {
   session: SessionHeader
   /** Exact number of fork-inherited events in the observed log. */
   inheritedEventCount: SessionLogOffset
-  /** Cloned contiguous raw events after persistence repair and replay validation. */
+  /** Cloned contiguous raw events after in-memory interrupted-turn balancing and replay validation. */
   events: SessionEvent[]
 }
 ```
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 51e2da2af5..f9653cecea 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 40012d1fc7b5be602dd3783f1df24f8f61f8a969
-session.zh.md: 9d4f6c3ce90913e5236b011e025d8299b3192a57
+session.md: 48a80ccb92af774db2f5bedea8e2e00043932d31
+session.zh.md: df5cfd631a15bfe015c766842956cc0c344c2ccd
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 40012d1fc7..48a80ccb92 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -607,8 +607,10 @@ interface TurnEndReasonMap {
   /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */
   'max-tokens': { kind: 'max-tokens' }
   /**
-   * A persistence backend closed a crash-orphaned turn on reload. The loop never
-   * emits this marker, and the events recorded before the crash remain intact.
+   * A crash-orphaned turn was closed after the fact: agent-loop resume appends
+   * this closer for a stored log whose last turn never ended, and session-query
+   * synthesizes it on cold reads. The loop never emits this marker live, and
+   * the events recorded before the crash remain intact.
    */
   interrupted: { kind: 'interrupted' }
 }
@@ -642,7 +644,7 @@ The hook bridges' `hook/invoked` / `hook/result` pairs (from `@deepseek-ai/dsh-h
 
 ## Durability contract
 
-What a persistence backend relies on: the durable log persists every event losslessly, **including** `assistant/chunk` — `seq` must stay contiguous, so chunks cannot be filtered out of the canonical log. A backend may choose its own storage encoding for an event batch as long as `load` returns the exact appended events (the JSONL backend's default packed chunk rows are such an encoding — see [persistence.md](persistence.md)). All `event.data` must be JSON-serializable; `Session.append` enforces this at the source (throwing on non-serializable data), so a bad event never enters the log and `session.snapshotEvents()` always equals what a backend can persist. Adding an event type that carries non-serializable data, corrupts core execution nesting, or violates its owner's declared relation is a breaking change to the on-disk format.
+What a persistence backend relies on: the durable log persists every event losslessly, **including** `assistant/chunk` — `seq` must stay contiguous, so chunks cannot be filtered out of the canonical log. A backend may choose its own storage encoding for an event batch as long as a handle's `read()` returns the exact appended events (the JSONL backend's default packed chunk rows are such an encoding — see [persistence.md](persistence.md)). All `event.data` must be JSON-serializable; `Session.append` enforces this at the source (throwing on non-serializable data), so a bad event never enters the log and `session.snapshotEvents()` always equals what a backend can persist. Adding an event type that carries non-serializable data, corrupts core execution nesting, or violates its owner's declared relation is a breaking change to the on-disk format.
 
 The backends that consume this contract are on [persistence.md](persistence.md).
 
@@ -810,7 +812,7 @@ Source: [`packages/api/session-controller/src/index.ts`](../../packages/api/sess
 
 In-memory session store (`ctx.sessions`).
 
-Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
+Persistence is intentionally not implemented here — the agent lifecycle attaches a session-log writer to each published session's write handle; a session published outside that lifecycle persists nothing.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 9d4f6c3ce9..df5cfd631a 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -611,8 +611,10 @@ interface TurnEndReasonMap {
   /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */
   'max-tokens': { kind: 'max-tokens' }
   /**
-   * A persistence backend closed a crash-orphaned turn on reload. The loop never
-   * emits this marker, and the events recorded before the crash remain intact.
+   * A crash-orphaned turn was closed after the fact: agent-loop resume appends
+   * this closer for a stored log whose last turn never ended, and session-query
+   * synthesizes it on cold reads. The loop never emits this marker live, and
+   * the events recorded before the crash remain intact.
    */
   interrupted: { kind: 'interrupted' }
 }
@@ -646,7 +648,7 @@ interface TurnEndReasonMap {
 
 ## 持久性约定
 
-持久化后端依赖的约定如下：持久日志无损保存每个事件，**包括** `assistant/chunk`；`seq` 必须连续，因此不能从规范日志中过滤分片。后端可以为事件批次选择自己的存储编码，只要 `load` 返回与追加时完全一致的事件即可（JSONL 后端默认启用的打包分片行就是此类编码；见 [persistence.md](persistence.zh.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.snapshotEvents()` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
+持久化后端依赖的约定如下：持久日志无损保存每个事件，**包括** `assistant/chunk`；`seq` 必须连续，因此不能从规范日志中过滤分片。后端可以为事件批次选择自己的存储编码，只要 handle 的 `read()` 返回与追加时完全一致的事件即可（JSONL 后端默认启用的打包分片行就是此类编码；见 [persistence.md](persistence.zh.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.snapshotEvents()` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
 
 消费此约定的后端见 [persistence.md](persistence.zh.md)。
 
@@ -814,7 +816,7 @@ Source: [`packages/api/session-controller/src/index.ts`](../../packages/api/sess
 
 In-memory session store (`ctx.sessions`).
 
-Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
+Persistence is intentionally not implemented here — the agent lifecycle attaches a session-log writer to each published session's write handle; a session published outside that lifecycle persists nothing.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index e3b15dc2d8..642e39cc6a 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: 5369ed85b5382dcb07df3e458a99124107ad5e51
-subagent.zh.md: 7495890531c6faa604a96edf443543840f69ae2c
+subagent.md: 1d111706ee93328e47b0cf2ed069a8fd9cdb56ec
+subagent.zh.md: 5b7eca88e9b981c2e582a2af70140f4750914632
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 5369ed85b5..1d111706ee 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -262,7 +262,7 @@ A local one-shot provider appends the descriptor inside the child's initial turn
 
 ## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
 
-`SubagentRuntime.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query service, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: `stateOf()` for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished (`unsupported` remains in the type but is never produced); a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` requires the runtime's projection registry and throws `SubagentError` with code `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is absent, checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry into its own `running`/`idle`/`ready` vocabulary, whose `ready` names a storage-only child as resumable rather than terminal. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
+`SubagentRuntime.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions` and the session-query engine's `listSessions()` — no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `query.observeSession()` cold observation folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished (`unsupported` remains in the type but is never produced); a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry into its own `running`/`idle`/`ready` vocabulary, whose `ready` names a storage-only child as resumable rather than terminal. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
 
 `SubagentRuntime.listDescendants(rootSessionId)` applies the same live-preferred corpus and projection-backed interpretation to the root's complete descendant tree in stable pre-order. Ordinary sessions and one-shot children remain traversal nodes, so continuable descendants below them are discovered; only `origin: 'subagent'` candidates produce rows. Each returned child or diagnostic adds its position from the enumerated durable header, while a cold inspection revalidates that complete lifecycle before serving identity:
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 7495890531..5b7eca88e9 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -262,7 +262,7 @@ interface ContinuableCreateSpec {
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentRuntime.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询服务，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由 `stateOf()` 供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分（`unsupported` 仍保留在类型中但从不产出）；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。`listChildren()` 要求运行时的投影注册表；缺少会话存储时会抛出携带错误码 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 的 `SubagentError`，并在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为自己的 `running`／`idle`／`ready` 词汇，其中 `ready` 把仅存于存储的 child 命名为可恢复而非终态。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md)。
+`SubagentRuntime.listChildren(parentSessionId)` 从 `ctx.sessions` 与会话查询引擎 `listSessions()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `query.observeSession()` 冷观察上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分（`unsupported` 仍保留在类型中但从不产出）；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为自己的 `running`／`idle`／`ready` 词汇，其中 `ready` 把仅存于存储的 child 命名为可恢复而非终态。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md)。
 
 `SubagentRuntime.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
diff --git a/packages/acp/acp/src/index.ts b/packages/acp/acp/src/index.ts
index 1a349c0698..b346dd763d 100644
--- a/packages/acp/acp/src/index.ts
+++ b/packages/acp/acp/src/index.ts
@@ -225,7 +225,8 @@ export function apply(ctx: Context, config: AcpConfig): void {
       try {
         const configOptions = await record.configOptions(signal)
         assertOpen()
-        await persistence.ensureMaterialized(record.agent.session)
+        // The attached log writer's flush materializes an empty session durably.
+        await ctx.sessions.flush(record.agent.session)
         assertOpen()
         return { sessionId, configOptions }
       } catch (error: unknown) {
@@ -244,7 +245,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
       }
       activating.add(sessionId)
       return (async (): Promise<ResumeSessionResponse> => {
-        const persisted = (await persistence.list(signal)).find(header => header.id === sessionId)
+        const persisted = (await persistence.stat(sessionId, { signal }))?.header
         if (persisted === undefined || persisted.origin === 'subagent' || persisted.parentSession !== undefined) {
           throw invalidParams(`session is not resumable: ${sessionId}`)
         }
@@ -299,8 +300,8 @@ export function apply(ctx: Context, config: AcpConfig): void {
       } catch (error: unknown) {
         throw invalidParams((error as Error).message)
       }
-      const listed = await persistence.list(signal)
-      const filtered = await Promise.all(listed.map(async (header) => {
+      const listed = await persistence.list({ signal })
+      const filtered = await Promise.all(listed.map(async ({ header }) => {
         if (
           sessions.has(header.id)
             || activating.has(header.id)
diff --git a/packages/acp/acp/tests/bridge.spec.ts b/packages/acp/acp/tests/bridge.spec.ts
index 5dec9b3786..ec5036172b 100644
--- a/packages/acp/acp/tests/bridge.spec.ts
+++ b/packages/acp/acp/tests/bridge.spec.ts
@@ -7,10 +7,17 @@ import { fileURLToPath } from 'node:url'
 import { AttachmentError } from '@deepseek-ai/dsh-attachment'
 import { ToolCallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionPersistenceRevision, type SessionPersistenceSnapshot } from '@deepseek-ai/dsh-session-persistence'
 import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts'
 import { startHttpMcpFixture } from '../../../mcp/mcp-client/tests/http-fixture.ts'
 
+/** Wrap a bare header as the snapshot shape `SessionPersistence.list` now returns. */
+function snapshotOf(header: SessionHeader): SessionPersistenceSnapshot {
+  return { header, revision: SessionPersistenceRevision(`test-${header.id}`) }
+}
+
 function oneToolCall(): StreamChunk[] {
   return [
     { type: 'block-start', index: 0, blockType: 'tool-call' },
@@ -164,11 +171,16 @@ describe('automation-only ACP bridge', () => {
     await harness.client.closeSession({ sessionId: created.sessionId })
     const updatesBeforeResume = harness.updates.length
 
+    const statSpy = vi.spyOn(harness.ctx.sessionPersistence, 'stat')
+    const listSpy = vi.spyOn(harness.ctx.sessionPersistence, 'list')
     const resumed = await harness.client.resumeSession({
       sessionId: created.sessionId,
       cwd: process.cwd(),
       mcpServers: [],
     })
+    // Resume authorizes one known id through a point stat, never a corpus scan.
+    expect(statSpy).toHaveBeenCalledWith(SessionId(created.sessionId), expect.anything())
+    expect(listSpy).not.toHaveBeenCalled()
     expect(Array.isArray(resumed.configOptions)).toBe(true)
     expect(harness.updates).toHaveLength(updatesBeforeResume)
     await harness.client.prompt({ sessionId: created.sessionId, prompt: [{ type: 'text', text: 'second prompt' }] })
@@ -249,13 +261,13 @@ describe('automation-only ACP bridge', () => {
     await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
     const sessionId = SessionId('other-frontend-live')
     harness.ctx.sessions.create(sessionId, { meta: { cwd: process.cwd() } })
-    vi.spyOn(harness.ctx.sessionPersistence, 'list').mockResolvedValue([{
+    vi.spyOn(harness.ctx.sessionPersistence, 'list').mockResolvedValue([snapshotOf({
       version: 0,
       id: sessionId,
       createdAt: 1,
-      cwd: process.cwd(),
       isSeeded: false,
-    }])
+      cwd: process.cwd(),
+    })])
     const resume = vi.spyOn(harness.ctx.agents, 'resume')
 
     await expect(harness.client.listSessions({})).resolves.toEqual({ sessions: [] })
@@ -363,16 +375,20 @@ describe('automation-only ACP bridge', () => {
     await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
     const active = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
     const persistence = harness.ctx.get('sessionPersistence')!
-    vi.spyOn(persistence, 'list').mockResolvedValue([
-      { version: 0, id: SessionId(active.sessionId), createdAt: 9, cwd: process.cwd(), isSeeded: false },
-      { version: 0, id: SessionId('subagent'), createdAt: 8, cwd: '/missing/filter', isSeeded: false, origin: 'subagent' },
-      { version: 0, id: SessionId('fork'), createdAt: 7, cwd: '/missing/filter', isSeeded: true, parentSession: SessionId('parent') },
+    vi.spyOn(persistence, 'list').mockResolvedValue(([
+      { version: 0, id: SessionId(active.sessionId), createdAt: 9, isSeeded: false, cwd: process.cwd() },
+      { version: 0, id: SessionId('subagent'), createdAt: 8, isSeeded: false, cwd: '/missing/filter', origin: 'subagent' },
+      { version: 0, id: SessionId('fork'), createdAt: 7, isSeeded: false, cwd: '/missing/filter', parentSession: SessionId('parent') },
       { version: 0, id: SessionId('no-cwd'), createdAt: 6, isSeeded: false },
-      { version: 0, id: SessionId('relative'), createdAt: 5, cwd: 'relative', isSeeded: false },
-      { version: 0, id: SessionId('other'), createdAt: 4, cwd: '/missing/other', isSeeded: false },
-      { version: 0, id: SessionId('valid-b'), createdAt: 3, cwd: '/missing/filter', isSeeded: false },
-      { version: 0, id: SessionId('valid-a'), createdAt: 3, cwd: '/missing/filter', isSeeded: false },
-    ])
+      { version: 0, id: SessionId('relative'), createdAt: 5, isSeeded: false, cwd: 'relative' },
+      { version: 0, id: SessionId('other'), createdAt: 4, isSeeded: false, cwd: '/missing/other' },
+      { version: 0, id: SessionId('valid-b'), createdAt: 3, isSeeded: false, cwd: '/missing/filter' },
+      { version: 0, id: SessionId('valid-a'), createdAt: 3, isSeeded: false, cwd: '/missing/filter' },
+    ] satisfies SessionHeader[]).map(snapshotOf))
+    // Resume authorizes through a point stat, not the list scan mocked above.
+    vi.spyOn(persistence, 'stat').mockImplementation(async id => (id === SessionId('no-cwd')
+      ? snapshotOf({ version: 0, id: SessionId('no-cwd'), createdAt: 6, isSeeded: false })
+      : undefined))
 
     await expect(harness.client.listSessions({ cwd: 'relative' })).rejects.toThrow(/absolute path/)
     await expect(harness.client.listSessions({ cwd: '/missing/filter' })).resolves.toEqual({
@@ -423,7 +439,10 @@ describe('automation-only ACP bridge', () => {
     await expect(harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }))
       .rejects.toThrow(/Internal error/)
     expect(harness.ctx.agents.list()).toHaveLength(0)
-    await expect(harness.ctx.sessionPersistence.list()).resolves.toEqual([])
+    // The loop seeds the log through its write handle before activation fails,
+    // so the rolled-back session's durable log remains; only the live agent and
+    // the bridge record are rolled back.
+    await expect(harness.ctx.sessionPersistence.list()).resolves.toHaveLength(1)
 
     const created = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
     await harness.client.prompt({ sessionId: created.sessionId, prompt: [{ type: 'text', text: 'persist' }] })
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index 9e96e16e09..4ee411fe0e 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/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/api/session-controller/README.md
-README.md: b3d22a340fff6a49270de520a043a1c8dfdbf096
-README.zh.md: 45590a53db17b32cc59f6107957c284b53ee8302
+README.md: cf78a247e27ec37ff51b10bad3f925348b9e01a2
+README.zh.md: 06d61851eec1ffdc99ed9348fac8b72cbc745b50
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index b3d22a340f..cf78a247e2 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -38,7 +38,8 @@ The Session object also carries local submission echoes: `session.beginSubmissio
 
 | Field | Default | Meaning |
 |---|---:|---|
-| `coldBlankProbeMaxBytes` | `1,024` | Maximum physical size of a cold Session artifact eligible for blankness verification; `0` disables probes |
+| `coldBlankProbeMaxEvents` | `16` | Maximum stat-reported event count of a cold Session eligible for blankness verification; `0` disables the event-count gate |
+| `coldBlankProbeMaxBytes` | `1,024` | Maximum stat-reported artifact byte size of a cold Session eligible for blankness verification when the backend offers no event count; `0` disables the byte-size gate |
 | `nativeOpen` | platform-detected | Whether Session workspace paths can be handed to a native desktop opener |
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-session-controller) is the exhaustive source for accepted fields and their JSDoc.
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 45590a53db..06d61851ee 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -38,7 +38,8 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 
 | 字段 | 默认值 | 含义 |
 |---|---:|---|
-| `coldBlankProbeMaxBytes` | `1,024` | 可进行空白状态验证的冷 Session 工件最大物理大小；`0` 禁用探测 |
+| `coldBlankProbeMaxEvents` | `16` | stat 报告的事件数不超过该值的冷 Session 才可进行空白状态验证；`0` 禁用事件数门槛 |
+| `coldBlankProbeMaxBytes` | `1,024` | 后端不提供事件数时，stat 报告的工件字节数不超过该值的冷 Session 才可进行空白状态验证；`0` 禁用字节数门槛 |
 | `nativeOpen` | 平台探测 | 是否能把 Session 工作区路径交给原生桌面打开器 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-session-controller)是所有受支持字段及其 JSDoc 的完整来源。
diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts
index 759c6b7f89..e982bf6f72 100644
--- a/packages/api/session-controller/src/index.ts
+++ b/packages/api/session-controller/src/index.ts
@@ -17,7 +17,11 @@ import { SessionCommandController } from './commands.ts'
 import { SessionControlController } from './control.ts'
 import { SessionHistoryController } from './history.ts'
 import { SessionFileReferences } from './file-references.ts'
-import { ApiSessionList, DEFAULT_COLD_BLANK_PROBE_MAX_BYTES } from './list.ts'
+import {
+  ApiSessionList,
+  DEFAULT_COLD_BLANK_PROBE_MAX_BYTES,
+  DEFAULT_COLD_BLANK_PROBE_MAX_EVENTS,
+} from './list.ts'
 import { buildModelCatalog } from './catalog.ts'
 import { installModelSelectionProjection } from './model-selection-projection.ts'
 import { SessionSkillCatalog } from './skill-catalog.ts'
@@ -66,7 +70,9 @@ declare module '@deepseek-ai/cordis' {
 
 /** Session Controller deployment policy. */
 export interface Config {
-  /** Maximum cold Session artifact size eligible for one full projection observation. */
+  /** Maximum stat-reported event count eligible for one full cold projection observation; `0` disables the event-count gate. */
+  readonly coldBlankProbeMaxEvents?: number
+  /** Maximum stat-reported artifact byte size eligible for one full cold projection observation; `0` disables the byte-size gate. */
   readonly coldBlankProbeMaxBytes?: number
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
@@ -95,6 +101,7 @@ export class SessionController extends TypertRemoteService {
   ]
 
   static Config: z<Config> = z.object({
+    coldBlankProbeMaxEvents: z.natural().default(DEFAULT_COLD_BLANK_PROBE_MAX_EVENTS),
     coldBlankProbeMaxBytes: z.natural().default(DEFAULT_COLD_BLANK_PROBE_MAX_BYTES),
     nativeOpen: z.boolean(),
   })
@@ -110,7 +117,8 @@ export class SessionController extends TypertRemoteService {
 
   /**
    * @param ctx - Host context containing the Session capability assembly.
-   * @param config - cold-list observation policy.
+   * @param config - cold-list observation and native-opener deployment policy.
+   * @param internals - host integrations replaceable by direct unit tests.
    */
   constructor(ctx: Context, config: Config, internals: SessionControllerInternals = {}) {
     super(ctx, 'sessionController', { namespace: 'session' })
@@ -124,10 +132,10 @@ export class SessionController extends TypertRemoteService {
       await Promise.allSettled([...this.promotions])
     }, 'session-controller.promotions')
     this.history = new SessionHistoryController(ctx, (observation) => { this.promote(observation) })
-    this.listState = new ApiSessionList(
-      ctx,
-      config.coldBlankProbeMaxBytes ?? DEFAULT_COLD_BLANK_PROBE_MAX_BYTES,
-    )
+    this.listState = new ApiSessionList(ctx, {
+      coldBlankProbeMaxEvents: config.coldBlankProbeMaxEvents ?? DEFAULT_COLD_BLANK_PROBE_MAX_EVENTS,
+      coldBlankProbeMaxBytes: config.coldBlankProbeMaxBytes ?? DEFAULT_COLD_BLANK_PROBE_MAX_BYTES,
+    })
     this.openPath = internals.openPath ?? openNativePath
     this.canOpenPath = internals.canOpenPath
       ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath()))
diff --git a/packages/api/session-controller/src/list.ts b/packages/api/session-controller/src/list.ts
index 145c77c63a..3c9d78ecf9 100644
--- a/packages/api/session-controller/src/list.ts
+++ b/packages/api/session-controller/src/list.ts
@@ -1,6 +1,5 @@
 /** Cold-safe Session list and search projection. */
 
-import { stat } from 'node:fs/promises'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-agent-presets'
 import type { ImageAttachmentLimits } from '@deepseek-ai/dsh-attachment'
@@ -20,9 +19,20 @@ import type {
   SessionSearchValue, SessionSummary,
 } from './types.ts'
 
-/** Default maximum artifact size eligible for one cold projection observation. */
+/** Default maximum stat-reported event count eligible for one cold projection observation. */
+export const DEFAULT_COLD_BLANK_PROBE_MAX_EVENTS = 16
+
+/** Default maximum stat-reported artifact size eligible for one cold projection observation. */
 export const DEFAULT_COLD_BLANK_PROBE_MAX_BYTES = 1024
 
+/** Resolved cold-blank probe policy: each threshold gates its stat metric; `0` disables that gate. */
+export interface ColdBlankProbePolicy {
+  /** Maximum stat-reported `eventCount` eligible for a full observation. */
+  readonly coldBlankProbeMaxEvents: number
+  /** Maximum stat-reported `sizeBytes` eligible for a full observation. */
+  readonly coldBlankProbeMaxBytes: number
+}
+
 const COLD_SUMMARY_BATCH_SIZE = 16
 const SEARCH_PROVIDER_CALL_LIMIT = 100
 const SESSION_SEARCH_QUERY_MAX_CHARS = 500
@@ -82,11 +92,11 @@ export function truncateUnicodeCodePoints(value: string, maximum: number): strin
 export class ApiSessionList {
   /**
    * @param ctx - Host context carrying Session, query, persistence, and projection services.
-   * @param coldBlankProbeMaxBytes - maximum physical artifact size eligible for a full observation.
+   * @param probe - stat-metadata thresholds gating a full cold observation.
    */
   constructor(
     private readonly ctx: Context,
-    private readonly coldBlankProbeMaxBytes: number,
+    private readonly probe: ColdBlankProbePolicy,
   ) {
     ctx.sessionProjections.register<'sessionListMetadata', SessionListMetadata>({
       key: 'sessionListMetadata',
@@ -176,7 +186,7 @@ export class ApiSessionList {
       sessionId: header.id,
       updatedAt: updatedAt(header, metadata),
       running: false,
-      // A large or inaccessible cache miss remains unknown and visible.
+      // A large, metadata-less, or inaccessible cache miss remains unknown and visible.
       blank: metadata?.blank ?? false,
       ...listFields(header),
       ...(projections === undefined ? {} : { projections }),
@@ -187,15 +197,30 @@ export class ApiSessionList {
     header: SessionHeader,
     signal: AbortSignal | undefined,
   ): Promise<SessionProjectionHints | undefined> {
-    if (this.coldBlankProbeMaxBytes === 0) return undefined
+    const { coldBlankProbeMaxEvents, coldBlankProbeMaxBytes } = this.probe
+    if (coldBlankProbeMaxEvents === 0 && coldBlankProbeMaxBytes === 0) return undefined
     const persistence = this.ctx.get('sessionPersistence')
-    const location = persistence?.locate(header)
-    if (location === undefined) return undefined
+    if (persistence === undefined) return undefined
     signal?.throwIfAborted()
+    let snapshot: Awaited<ReturnType<typeof persistence.stat>>
     try {
-      if ((await stat(location.path)).size > this.coldBlankProbeMaxBytes) return undefined
-    } catch {
+      snapshot = await persistence.stat(header.id, signal === undefined ? {} : { signal })
+    } catch (error: unknown) {
+      // An unreadable single session degrades to unknown state instead of
+      // failing the whole list request.
       signal?.throwIfAborted()
+      this.ctx.logger.warn(
+        `api-session.list: cold stat for "${header.id}" failed; serving it as visible: ${String(error)}`,
+      )
+      return undefined
+    }
+    if (snapshot === undefined) return undefined
+    if (snapshot.eventCount !== undefined) {
+      if (coldBlankProbeMaxEvents === 0 || snapshot.eventCount > coldBlankProbeMaxEvents) return undefined
+    } else if (snapshot.sizeBytes !== undefined) {
+      if (coldBlankProbeMaxBytes === 0 || snapshot.sizeBytes > coldBlankProbeMaxBytes) return undefined
+    } else {
+      // The backend offers no cheap size hint, so a full observation is unbounded work.
       return undefined
     }
     try {
diff --git a/packages/api/session-controller/tests/agent.host.spec.ts b/packages/api/session-controller/tests/agent.host.spec.ts
index 3d370bcf28..566ce048c8 100644
--- a/packages/api/session-controller/tests/agent.host.spec.ts
+++ b/packages/api/session-controller/tests/agent.host.spec.ts
@@ -5,10 +5,9 @@ import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { agentPresetProjectionDefinition } from '@deepseek-ai/dsh-agent-presets'
-import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionLogOffset, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import type { SessionObservation } from '@deepseek-ai/dsh-session-query'
-import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence'
 import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
@@ -53,14 +52,6 @@ function header(id: string, cwd: string | null = '/workspace'): SessionHeader {
   }
 }
 
-function unseededInspection(
-  meta: SessionHeader,
-  events: readonly SessionEvent[] = [],
-): SessionInspection {
-  if (meta.isSeeded) throw new Error('seeded inspection fixtures require an explicit inherited cut')
-  return { meta, inheritedEventCount: SessionLogOffset(0), events }
-}
-
 function providePersistence(ctx: Context, persistence: Record<string, unknown>): () => void {
   return ctx.provide('sessionPersistence', testSessionPersistence(ctx, persistence) as never)
 }
@@ -96,18 +87,22 @@ describe('ApiSession identity failures', () => {
       .rejects.toBeInstanceOf(ApiSessionNotFound)
 
     const inspect = vi.fn(() => Promise.resolve(undefined))
+    const stat = vi.fn(() => Promise.resolve(undefined))
     const disposeMissing = providePersistence(ctx, {
       list: () => Promise.resolve([]),
+      stat,
       inspect,
     })
     await expect(inspectApiSession(ctx, SessionId('missing'))).rejects.toBeInstanceOf(ApiSessionNotFound)
-    expect(inspect).toHaveBeenCalledOnce()
+    // Absence is decided by the stat preflight; the log itself is never opened.
+    expect(stat).toHaveBeenCalledOnce()
+    expect(inspect).not.toHaveBeenCalled()
     disposeMissing()
 
     const listed = header('cwd-less-catalog', null)
     const disposeListed = providePersistence(ctx, {
       list: () => Promise.resolve([listed]),
-      inspect: () => Promise.resolve(unseededInspection(listed)),
+      inspect: () => Promise.resolve({ meta: listed, events: [] }),
     })
     await expect(inspectApiSession(ctx, listed.id)).rejects.toBeInstanceOf(ApiSessionNotFound)
     disposeListed()
@@ -116,7 +111,7 @@ describe('ApiSession identity failures', () => {
     const inspected = header('cwd-less-inspect', null)
     providePersistence(ctx, {
       list: () => Promise.resolve([catalog]),
-      inspect: () => Promise.resolve(unseededInspection(inspected)),
+      inspect: () => Promise.resolve({ meta: inspected, events: [] }),
     })
     await expect(inspectApiSession(ctx, catalog.id)).rejects.toBeInstanceOf(ApiSessionNotFound)
   })
@@ -127,11 +122,14 @@ describe('ApiSession identity failures', () => {
     await ctx.plugin(SessionStore)
     installSessionReadTestServices(ctx)
     const meta = header('signalled-inspection')
-    const inspect = vi.fn(() => Promise.resolve(unseededInspection(meta)))
-    providePersistence(ctx, { inspect })
+    const inspect = vi.fn(() => Promise.resolve({ meta, inheritedEventCount: SessionLogOffset(0), events: [] }))
+    providePersistence(ctx, {
+      list: () => Promise.resolve([meta]),
+      inspect,
+    })
     const signal = new AbortController().signal
 
-    await expect(inspectApiSession(ctx, meta.id, signal)).resolves.toEqual(unseededInspection(meta))
+    await expect(inspectApiSession(ctx, meta.id, signal)).resolves.toEqual({ meta, inheritedEventCount: SessionLogOffset(0), events: [] })
     expect(inspect).toHaveBeenCalledWith(meta.id, signal)
   })
 })
@@ -148,7 +146,6 @@ describe('ApiSession Agent lookup and recovery', () => {
     const observed = {
       source: 'prepared',
       header: meta,
-      inheritedEventCount: SessionLogOffset(0),
       events: [],
       cursor: -1,
       projections: { asOfSeq: -1, values: {} },
@@ -188,7 +185,7 @@ describe('ApiSession Agent lookup and recovery', () => {
     const ordinaryMeta = header('ordinary-race')
     providePersistence(ordinary.ctx, {
       list: () => Promise.resolve([ordinaryMeta]),
-      inspect: () => Promise.resolve(unseededInspection(ordinaryMeta)),
+      inspect: () => Promise.resolve({ meta: ordinaryMeta, events: [] }),
     })
     const winner = agent(ordinary.ctx, ordinaryMeta)
     vi.spyOn(ordinary.ctx.agents, 'resume').mockImplementation(async () => {
@@ -201,7 +198,7 @@ describe('ApiSession Agent lookup and recovery', () => {
     const childMeta = header('child-race')
     providePersistence(child.ctx, {
       list: () => Promise.resolve([childMeta]),
-      inspect: () => Promise.resolve(unseededInspection(childMeta)),
+      inspect: () => Promise.resolve({ meta: childMeta, events: [] }),
     })
     vi.spyOn(child.ctx.agents, 'resume').mockImplementation(async () => {
       child.ctx.sessions.create(childMeta.id, {
@@ -228,7 +225,7 @@ describe('ApiSession Agent lookup and recovery', () => {
     const meta = header('failed')
     providePersistence(failed.ctx, {
       list: () => Promise.resolve([meta]),
-      inspect: () => Promise.resolve(unseededInspection(meta)),
+      inspect: () => Promise.resolve({ meta, events: [] }),
     })
     vi.spyOn(failed.ctx.agents, 'resume').mockRejectedValue(new Error('factory unavailable'))
     await expect(failed.agents.resolveAgent(meta.id)).resolves.toMatchObject({
@@ -242,7 +239,6 @@ describe('ApiSession Agent lookup and recovery', () => {
     const observed = {
       source: 'prepared',
       header: meta,
-      inheritedEventCount: SessionLogOffset(0),
       events: [],
       cursor: -1,
       retain: vi.fn(),
@@ -375,27 +371,27 @@ describe('ApiSession create or adoption', () => {
     const meta = { ...header('stored'), agentPreset: 'minimal' }
     const events = [{
       type: 'agent-preset/selected',
-      seq: SessionSeq(0),
+      seq: 0,
       time: 1,
       data: { agentPreset: 'minimal' },
     }] as SessionEvent[]
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
-      inspect: () => Promise.resolve(unseededInspection(meta, events)),
+      inspect: () => Promise.resolve({ meta, events }),
     })
     ctx.provide('agentPresets', {
       resolve: (id?: string) => Promise.resolve({ id: id ?? 'minimal' }),
       mount: () => Promise.resolve(),
     } as never)
-    const resumedSession = ctx.sessions.prepare(meta.id, {
-      seed: structuredClone(events),
-      meta: structuredClone(meta),
-      inheritedEventCount: SessionLogOffset(0),
-      seedSource: 'persistence',
-    })
     const resumed = {
       id: meta.id,
-      session: resumedSession,
+      session: {
+        id: meta.id,
+        header: meta,
+        snapshotEvents: () => events,
+        eventAt: (seq: number) => events[seq],
+        seq: events.length,
+      },
       status: 'idle',
       ctx,
     } as unknown as Agent
@@ -413,7 +409,7 @@ describe('ApiSession create or adoption', () => {
     const childMeta = header('resume-child-race')
     providePersistence(child.ctx, {
       list: () => Promise.resolve([childMeta]),
-      inspect: () => Promise.resolve(unseededInspection(childMeta)),
+      inspect: () => Promise.resolve({ meta: childMeta, events: [] }),
     })
     child.ctx.provide('agentPresets', {
       resolve: () => {
@@ -432,7 +428,7 @@ describe('ApiSession create or adoption', () => {
     const stored = header('stored-cwd-conflict', '/stored')
     providePersistence(conflict.ctx, {
       list: () => Promise.resolve([stored]),
-      inspect: () => Promise.resolve(unseededInspection(stored)),
+      inspect: () => Promise.resolve({ meta: stored, events: [] }),
     })
     await expect(conflict.agents.ensureSession(stored.id, '/requested', true))
       .rejects.toBeInstanceOf(ApiSessionCwdConflict)
diff --git a/packages/api/session-controller/tests/session-cold.host.spec.ts b/packages/api/session-controller/tests/session-cold.host.spec.ts
index a6cc76c8b5..ce94fadd49 100644
--- a/packages/api/session-controller/tests/session-cold.host.spec.ts
+++ b/packages/api/session-controller/tests/session-cold.host.spec.ts
@@ -4,12 +4,10 @@
  * isolation, and prompt failure mapping.
  */
 
+import { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
 import { describe, expect, it, vi } from 'vitest'
-import { mkdtempSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import SessionStore from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import { SessionHistoryController } from '@deepseek-ai/dsh-api-session-controller/src/history.ts'
 import { subagentIdentityProjectionDefinition } from '@deepseek-ai/dsh-subagent/src/projection.ts'
@@ -20,10 +18,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionPromptRequest, SessionRequestId } from '../src/types.ts'
 import {
-  PersistenceCoordinator,
   SessionPersistenceRevision,
-  type PersistenceBackend,
-  type StoredPrefix,
+  type SessionPersistenceSnapshot,
 } from '@deepseek-ai/dsh-session-persistence'
 import { ApiSessionList } from '../src/list.ts'
 import {
@@ -49,79 +45,127 @@ function promptRequest(
 }
 
 function header(id: string, createdAt: number, extra: Partial<SessionHeader> = {}): SessionHeader {
-  return { version: 0, id: sid(id), createdAt, cwd: '/proj', isSeeded: false, ...extra }
+  return { version: 0, id: sid(id), createdAt, isSeeded: false, cwd: '/proj', ...extra }
 }
 
 function providePersistence(ctx: Context, persistence: Record<string, unknown>): () => void {
   return ctx.provide('sessionPersistence', testSessionPersistence(ctx, persistence) as never)
 }
 
+function statSnapshot(
+  meta: SessionHeader,
+  metrics: Partial<Pick<SessionPersistenceSnapshot, 'eventCount' | 'sizeBytes'>> = {},
+): SessionPersistenceSnapshot {
+  return { header: meta, revision: SessionPersistenceRevision(`test:${meta.id}:stat`), ...metrics }
+}
+
+/** A stored log whose only event is the seed boundary: still blank. */
+function blankEvents(): SessionEvent[] {
+  return [{ type: 'session/end-seed', seq: SessionSeq(0), time: 700, data: {} }] as SessionEvent[]
+}
+
+/** A stored log with one human prompt at time 1200: proven non-blank. */
+function conversationEvents(): SessionEvent[] {
+  return [
+    { type: 'turn/start', seq: SessionSeq(0), time: 800, data: { turn: 1 } },
+    {
+      type: 'user/message', seq: SessionSeq(1), time: 1200,
+      data: createUserMessage({ content: [{ type: 'text', text: 'worked' }], source: { kind: 'user' } }),
+      surfaceOp: 'append',
+    },
+  ] as SessionEvent[]
+}
+
 describe('sessions.list cold merge', () => {
-  it('fully observes only small possibly-blank artifacts and treats unavailable probes as visible', async () => {
+  it('serves cold rows from cached projections when stat offers no size metadata', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const metas = [
+      header('cached-blank', 100),
+      header('cached-conversation', 200),
+      header('uncached', 300, { parentSession: sid('session-parent'), origin: 'subagent' }),
+      header('seeded-cold', 450, { isSeeded: true }),
+      { version: 0, id: sid('missing-cwd'), createdAt: 800, isSeeded: false },
+    ]
+    const inspect = vi.fn()
+    providePersistence(ctx, {
+      list: () => Promise.resolve(metas),
+      inspect,
+    })
+    const cacheCalls: string[] = []
+    ctx.provide('sessionProjectionCache', {
+      cachedSnapshot: (meta: SessionHeader) => {
+        cacheCalls.push(String(meta.id))
+        if (meta.id === sid('cached-blank')) {
+          return { asOfSeq: 0, values: { sessionListMetadata: { blank: true, lastPromptAt: null } } }
+        }
+        if (meta.id === sid('cached-conversation')) {
+          return { asOfSeq: 1, values: { sessionListMetadata: { blank: false, lastPromptAt: 1000 } } }
+        }
+        return undefined
+      },
+    } as never)
+    const remote = createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
+
+    const response = await remote.list(request({}))
+    expect(response.ok).toBe(true)
+    if (!response.ok) throw new Error('unreachable')
+    const byId = Object.fromEntries(response.value.items.map(item => [item.sessionId, item]))
+    expect(byId['cached-blank']).toMatchObject({ blank: true, updatedAt: 100, running: false })
+    expect(byId['cached-conversation']).toMatchObject({ blank: false, updatedAt: 1000 })
+    // A cache miss with a metadata-less stat leaves blankness unknown; the row stays visible.
+    expect(byId['uncached']).toMatchObject({
+      blank: false,
+      updatedAt: 300,
+      parentSessionId: 'session-parent',
+      origin: 'subagent',
+    })
+    expect(byId['missing-cwd']).toBeUndefined()
+    // A cold seeded header never consults the cache: its cut is not 0, so a
+    // cut-0 lookup would alias a different projection identity.
+    expect(byId['seeded-cold']).toMatchObject({ blank: false, updatedAt: 450 })
+    expect(cacheCalls).not.toContain('seeded-cold')
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('fully observes only small possibly-blank logs gated by stat eventCount', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
-    const root = mkdtempSync(join(tmpdir(), 'dsh-cold-'))
-    const smallPath = join(root, 'small.log')
-    const largePath = join(root, 'large.log')
-    writeFileSync(smallPath, 'x'.repeat(1024))
-    writeFileSync(largePath, 'x'.repeat(1025))
     const metas = [
       header('small-blank', 100),
       header('small-conversation', 200),
       header('large-unknown', 300),
       header('cached-nonblank', 400),
-      header('seeded-cold', 450, { isSeeded: true }),
-      header('locationless', 500, { parentSession: sid('session-parent'), origin: 'subagent' }),
       header('vanished', 600),
-      header('read-failure', 700),
       { version: 0, id: sid('missing-cwd'), createdAt: 800, isSeeded: false },
     ]
     const inspect = vi.fn(async (id: SessionId) => {
-      if (id === sid('small-blank')) {
-        return {
-          meta: metas[0]!,
-          events: [{ type: 'session/end-seed', seq: SessionSeq(0), time: 700, data: {} }] satisfies SessionEvent[],
-        }
-      }
-      if (id === sid('small-conversation')) {
-        return {
-          meta: metas[1]!,
-          events: [
-            { type: 'turn/start', seq: SessionSeq(0), time: 800, data: { turn: 1 } },
-            {
-              type: 'user/message', seq: SessionSeq(1), time: 1200,
-              data: createUserMessage({ content: [{ type: 'text', text: 'worked' }], source: { kind: 'user' } }),
-              surfaceOp: 'append',
-            },
-          ] satisfies SessionEvent[],
-        }
-      }
-      if (id === sid('read-failure')) throw new Error('simulated read failure')
+      if (id === sid('small-blank')) return { meta: metas[0]!, events: blankEvents() }
+      if (id === sid('small-conversation')) return { meta: metas[1]!, events: conversationEvents() }
       throw new Error(`unexpected cold read: ${id}`)
     })
+    const stat = vi.fn(async (id: SessionId) => {
+      if (id === sid('small-blank')) return statSnapshot(metas[0]!, { eventCount: 1 })
+      if (id === sid('small-conversation')) return statSnapshot(metas[1]!, { eventCount: 2 })
+      if (id === sid('large-unknown')) return statSnapshot(metas[2]!, { eventCount: 17 })
+      if (id === sid('vanished')) return undefined
+      throw new Error(`unexpected stat: ${id}`)
+    })
     providePersistence(ctx, {
       list: () => Promise.resolve(metas),
-      locate: (meta: SessionHeader) => {
-        if (meta.id === sid('large-unknown') || meta.id === sid('seeded-cold')) {
-          return { kind: 'jsonl', path: largePath }
-        }
-        if (meta.id === sid('locationless')) return undefined
-        if (meta.id === sid('vanished')) return { kind: 'jsonl', path: join(root, 'vanished.log') }
-        return { kind: 'jsonl', path: smallPath }
-      },
+      stat,
       inspect,
     })
     ctx.provide('sessionProjectionCache', {
       cachedSnapshot: (meta: SessionHeader) => {
-        if (meta.id === sid('seeded-cold')) throw new Error('seeded cold listing must not guess a body cut')
         if (meta.id === sid('small-blank')) {
-          return { asOfSeq: SessionSeq(0), values: { sessionListMetadata: { blank: true, lastPromptAt: null } } }
+          return { asOfSeq: 0, values: { sessionListMetadata: { blank: true, lastPromptAt: null } } }
         }
         if (meta.id === sid('small-conversation')) {
-          return { asOfSeq: SessionSeq(0), values: { sessionListMetadata: { blank: true, lastPromptAt: 900 } } }
+          return { asOfSeq: 0, values: { sessionListMetadata: { blank: true, lastPromptAt: 900 } } }
         }
         if (meta.id === sid('cached-nonblank')) {
-          return { asOfSeq: SessionSeq(1), values: { sessionListMetadata: { blank: false, lastPromptAt: 1000 } } }
+          return { asOfSeq: 1, values: { sessionListMetadata: { blank: false, lastPromptAt: 1000 } } }
         }
         return undefined
       },
@@ -138,37 +182,80 @@ describe('sessions.list cold merge', () => {
     expect(byId['small-conversation']).toMatchObject({ blank: false, updatedAt: 1200 })
     expect(byId['large-unknown']).toMatchObject({ blank: false, updatedAt: 300 })
     expect(byId['cached-nonblank']).toMatchObject({ blank: false, updatedAt: 1000 })
-    expect(byId['seeded-cold']).toMatchObject({ blank: false, updatedAt: 450 })
-    expect(byId['locationless']).toMatchObject({
-      blank: false,
-      updatedAt: 500,
-      parentSessionId: 'session-parent',
-      origin: 'subagent',
-    })
     expect(byId['vanished']).toMatchObject({ blank: false, updatedAt: 600 })
-    expect(byId['read-failure']).toMatchObject({ blank: false, updatedAt: 700 })
     expect(byId['missing-cwd']).toBeUndefined()
-    expect(inspect).toHaveBeenCalledTimes(3)
+    // A cache row proving blank:false is never re-probed.
+    expect(stat.mock.calls.map(([id]) => id)).not.toContain(sid('cached-nonblank'))
+    expect(inspect).toHaveBeenCalledTimes(2)
     expect(inspect.mock.calls.map(([id]) => id)).toEqual(expect.arrayContaining([
       sid('small-blank'),
       sid('small-conversation'),
-      sid('read-failure'),
     ]))
   })
 
-  it('can disable bounded cold observations without hiding cold Sessions', async () => {
+  it('falls back to the stat sizeBytes gate when no eventCount is offered', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const metas = [header('small-jsonl', 100), header('large-jsonl', 200)]
+    const inspect = vi.fn(async (id: SessionId) => {
+      if (id === sid('small-jsonl')) return { meta: metas[0]!, events: conversationEvents() }
+      throw new Error(`unexpected cold read: ${id}`)
+    })
+    providePersistence(ctx, {
+      list: () => Promise.resolve(metas),
+      stat: (id: SessionId) => Promise.resolve(id === sid('small-jsonl')
+        ? statSnapshot(metas[0]!, { sizeBytes: 1024 })
+        : statSnapshot(metas[1]!, { sizeBytes: 1025 })),
+      inspect,
+    })
+    const remote = createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
+
+    const response = await remote.list(request({}))
+    if (!response.ok) throw new Error('list failed')
+    const byId = Object.fromEntries(response.value.items.map(item => [item.sessionId, item]))
+    expect(byId['small-jsonl']).toMatchObject({ blank: false, updatedAt: 1200 })
+    expect(byId['large-jsonl']).toMatchObject({ blank: false, updatedAt: 200 })
+    expect(inspect).toHaveBeenCalledTimes(1)
+    expect(inspect).toHaveBeenCalledWith(sid('small-jsonl'), expect.anything())
+  })
+
+  it('skips the observation when stat offers neither eventCount nor sizeBytes', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const meta = header('no-metrics', 100)
+    const inspect = vi.fn()
+    const stat = vi.fn(async () => statSnapshot(meta))
+    providePersistence(ctx, {
+      list: () => Promise.resolve([meta]),
+      stat,
+      inspect,
+    })
+    const remote = createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
+
+    const response = await remote.list(request({}))
+    if (!response.ok) throw new Error('list failed')
+    expect(response.value.items).toEqual([
+      expect.objectContaining({ sessionId: meta.id, blank: false, updatedAt: meta.createdAt }),
+    ])
+    expect(stat).toHaveBeenCalledOnce()
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('can disable both probe gates without hiding cold Sessions or calling stat', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const meta = header('probe-disabled', 100)
     const inspect = vi.fn()
+    const stat = vi.fn()
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
-      locate: () => ({ kind: 'jsonl', path: '/not-read' }),
+      stat,
       inspect,
     })
     const remote = createSessionTestRemote(ctx, {
       defaultModelSelection: () => ({ provider: 'p', model: 'm' }),
       cwd: '/tmp',
+      coldBlankProbeMaxEvents: 0,
       coldBlankProbeMaxBytes: 0,
     })
 
@@ -177,9 +264,179 @@ describe('sessions.list cold merge', () => {
     expect(response.value.items).toEqual([
       expect.objectContaining({ sessionId: meta.id, blank: false, updatedAt: meta.createdAt }),
     ])
+    expect(stat).not.toHaveBeenCalled()
     expect(inspect).not.toHaveBeenCalled()
   })
 
+  it('treats zero as disabling one gate without falling back to the other metric', async () => {
+    const bench = async (
+      metrics: Partial<Pick<SessionPersistenceSnapshot, 'eventCount' | 'sizeBytes'>>,
+      thresholds: { coldBlankProbeMaxEvents?: number; coldBlankProbeMaxBytes?: number },
+    ) => {
+      const ctx = new Context()
+      await ctx.plugin(SessionStore)
+      const meta = header('gate-off', 100)
+      const inspect = vi.fn()
+      providePersistence(ctx, {
+        list: () => Promise.resolve([meta]),
+        stat: () => Promise.resolve(statSnapshot(meta, metrics)),
+        inspect,
+      })
+      const remote = createSessionTestRemote(ctx, {
+        defaultModelSelection: () => ({ provider: 'p', model: 'm' }),
+        cwd: '/tmp',
+        ...thresholds,
+      })
+      const response = await remote.list(request({}))
+      if (!response.ok) throw new Error('list failed')
+      expect(response.value.items).toEqual([
+        expect.objectContaining({ sessionId: meta.id, blank: false }),
+      ])
+      expect(inspect).not.toHaveBeenCalled()
+    }
+
+    // An offered eventCount never falls through to the byte gate, even disabled.
+    await bench({ eventCount: 1, sizeBytes: 10 }, { coldBlankProbeMaxEvents: 0 })
+    await bench({ sizeBytes: 10 }, { coldBlankProbeMaxBytes: 0 })
+  })
+
+  it('prefers a Session that attaches during its bounded cold observation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    const meta = header('attached-during-probe', 100)
+    providePersistence(ctx, {
+      list: () => Promise.resolve([meta]),
+      stat: () => {
+        const session = ctx.sessions.create(meta.id, {
+          meta,
+          seed: [{ type: 'turn/start', seq: SessionSeq(0), time: 200, data: { turn: 1 } }],
+        })
+        ctx.agents.register({ id: session.id, session, status: 'running', ctx } as Agent)
+        return Promise.resolve(statSnapshot(meta, { eventCount: 1 }))
+      },
+    })
+    const remote = createSessionTestRemote(ctx, {
+      defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp',
+    })
+
+    const response = await remote.list(request({}))
+    if (!response.ok) throw new Error('list failed')
+    expect(response.value.items).toEqual([
+      expect.objectContaining({ sessionId: meta.id, running: true, blank: false }),
+    ])
+    await ctx.fiber.dispose()
+  })
+
+  it('serves a session whose cold stat fails as visible instead of failing the list', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const meta = header('broken-stat', 100)
+    providePersistence(ctx, {
+      list: () => Promise.resolve([meta]),
+      stat: () => Promise.reject(new Error('stat failed')),
+    })
+    const warned = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const remote = createSessionTestRemote(ctx, {
+      defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp',
+    })
+
+    const response = await remote.list(request({}))
+    if (!response.ok) throw new Error('list failed')
+    expect(response.value.items).toEqual([
+      expect.objectContaining({ sessionId: meta.id, running: false }),
+    ])
+    expect(warned.mock.calls.join('\n')).toContain('cold stat for "broken-stat" failed')
+    warned.mockRestore()
+    await ctx.fiber.dispose()
+  })
+
+  it('a stat rejection after cancellation propagates instead of degrading', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const meta = header('stat-abort', 100)
+    const controller = new AbortController()
+    providePersistence(ctx, {
+      list: () => Promise.resolve([meta]),
+      stat: () => {
+        controller.abort(new Error('caller left'))
+        return Promise.reject(new Error('stat failed'))
+      },
+    })
+    const remote = createSessionTestRemote(ctx, {
+      defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp',
+    })
+
+    await expect(remote.list(request({}), controller.signal)).resolves.toMatchObject({
+      ok: false,
+      error: { code: 'gateway/cancelled' },
+    })
+    await ctx.fiber.dispose()
+  })
+
+  it('serves a small cold Session as visible when its observation fails', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const meta = header('read-failure', 700)
+    const inspect = vi.fn(async () => { throw new Error('simulated read failure') })
+    providePersistence(ctx, {
+      list: () => Promise.resolve([meta]),
+      stat: () => Promise.resolve(statSnapshot(meta, { eventCount: 1 })),
+      inspect,
+    })
+    const remote = createSessionTestRemote(ctx, {
+      defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp',
+    })
+
+    const response = await remote.list(request({}))
+    if (!response.ok) throw new Error('list failed')
+    expect(response.value.items).toEqual([
+      expect.objectContaining({ sessionId: meta.id, blank: false, updatedAt: 700 }),
+    ])
+    expect(inspect).toHaveBeenCalledOnce()
+  })
+
+  it('supports an unsignalled probe whose observation has no projection block', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    installSessionReadTestServices(ctx)
+    const meta = header('unprojected-small', 100)
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve([meta]),
+      stat: () => Promise.resolve(statSnapshot(meta, { eventCount: 0 })),
+    } as never)
+    vi.spyOn(ctx.sessionQuery, 'listSessions').mockResolvedValue([{
+      header: meta, live: false, persisted: true,
+    }])
+    vi.spyOn(ctx.sessionQuery, 'observeSession').mockResolvedValue({
+      source: 'prepared', header: meta, inheritedEventCount: SessionLogOffset(0), events: [], cursor: -1,
+      retain: vi.fn(), [Symbol.dispose]: vi.fn(),
+    })
+    const list = new ApiSessionList(ctx, { coldBlankProbeMaxEvents: 16, coldBlankProbeMaxBytes: 1024 })
+
+    await expect(list.list()).resolves.toEqual([
+      expect.objectContaining({ sessionId: meta.id, blank: false }),
+    ])
+    await ctx.fiber.dispose()
+  })
+
+  it('serves a cold row visible when no persistence service can stat it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    installSessionReadTestServices(ctx)
+    const meta = header('service-less', 100)
+    vi.spyOn(ctx.sessionQuery, 'listSessions').mockResolvedValue([{
+      header: meta, live: false, persisted: true,
+    }])
+    const list = new ApiSessionList(ctx, { coldBlankProbeMaxEvents: 16, coldBlankProbeMaxBytes: 1024 })
+
+    await expect(list.list()).resolves.toEqual([
+      expect.objectContaining({ sessionId: meta.id, blank: false }),
+    ])
+    await ctx.fiber.dispose()
+  })
+
   it('prefers a live row attached during the query without folding its seed', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -227,92 +484,6 @@ describe('sessions.list cold merge', () => {
     ])
   })
 
-  it('prefers a Session that attaches during its bounded cold observation', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(AgentRegistry)
-    const root = mkdtempSync(join(tmpdir(), 'dsh-cold-race-'))
-    const path = join(root, 'small.log')
-    writeFileSync(path, 'small')
-    const meta = header('attached-during-probe', 100)
-    providePersistence(ctx, {
-      list: () => Promise.resolve([meta]),
-      locate: () => ({ kind: 'jsonl', path }),
-      inspect: () => {
-        const session = ctx.sessions.create(meta.id, {
-          meta,
-          seed: [{ type: 'turn/start', seq: SessionSeq(0), time: 200, data: { turn: 1 } }],
-        })
-        ctx.agents.register({ id: session.id, session, status: 'running', ctx } as Agent)
-        return Promise.resolve({
-          meta,
-          inheritedEventCount: SessionLogOffset(0),
-          events: [],
-        })
-      },
-    })
-    const remote = createSessionTestRemote(ctx, {
-      defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp',
-    })
-
-    const response = await remote.list(request({}))
-    if (!response.ok) throw new Error('list failed')
-    expect(response.value.items).toEqual([
-      expect.objectContaining({ sessionId: meta.id, running: true, blank: false }),
-    ])
-    await ctx.fiber.dispose()
-  })
-
-  it('propagates a cold location failure instead of returning a partial list', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const meta = header('broken-cache', 100)
-    providePersistence(ctx, {
-      list: () => Promise.resolve([meta]),
-      locate: () => { throw new Error('location failed') },
-    })
-    const remote = createSessionTestRemote(ctx, {
-      defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp',
-    })
-
-    await expect(remote.list(request({}))).resolves.toMatchObject({
-      ok: false,
-      error: { message: expect.stringContaining('location failed') as string },
-    })
-    await ctx.fiber.dispose()
-  })
-
-  it('supports an unsignalled probe whose observation has no projection registry', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(AgentRegistry)
-    installSessionReadTestServices(ctx)
-    const root = mkdtempSync(join(tmpdir(), 'dsh-cold-unprojected-'))
-    const path = join(root, 'small.log')
-    writeFileSync(path, 'small')
-    const meta = header('unprojected-small', 100)
-    ctx.provide('sessionPersistence', {
-      list: () => Promise.resolve([meta]),
-      locate: () => ({ kind: 'jsonl', path }),
-    } as never)
-    vi.spyOn(ctx.sessionQuery, 'listSessions').mockResolvedValue([{
-      header: meta, live: false, persisted: true,
-    }])
-    vi.spyOn(ctx.sessionQuery, 'observeSession').mockResolvedValue({
-      source: 'prepared',
-      header: meta,
-      inheritedEventCount: SessionLogOffset(0),
-      events: [],
-      cursor: -1,
-      retain: vi.fn(), [Symbol.dispose]: vi.fn(),
-    })
-    const list = new ApiSessionList(ctx, 1024)
-
-    await expect(list.list()).resolves.toEqual([
-      expect.objectContaining({ sessionId: meta.id, blank: false }),
-    ])
-    await ctx.fiber.dispose()
-  })
 })
 
 describe('attached updatedAt tracks human prompts', () => {
@@ -366,40 +537,25 @@ describe('attached updatedAt tracks human prompts', () => {
 })
 
 describe('cold history recovery view', () => {
-  it('shows in-memory interruption repair without activating the session', async () => {
+  it('serves the stored interrupted prefix verbatim without activating the session', async () => {
+    // Semantic crash repair is the resuming agent loop's job (it appends the
+    // closers durably through its write handle); a cold history read shows the
+    // stored prefix exactly as persisted.
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const sessionId = sid('session-interrupted')
     const meta = header(sessionId, 1000)
-    const stored: StoredPrefix<never> = {
-      meta,
-      inheritedEventCount: SessionLogOffset(0),
-      events: [{ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }],
-      revision: SessionPersistenceRevision('history-recovery-test:1'),
-    }
-    const backend: PersistenceBackend<never> = {
-      name: 'history-recovery-test',
-      loadStored: id => Promise.resolve(id === sessionId ? structuredClone(stored) : undefined),
-      readStoredRevision: id => Promise.resolve(
-        id === sessionId ? SessionPersistenceRevision('history-recovery-test:1') : undefined,
-      ),
-      appendBatch: () => Promise.resolve(),
-      commitRepair: () => Promise.resolve(),
-      list: () => Promise.resolve([structuredClone(meta)]),
-    }
-    const coordinator = new PersistenceCoordinator(ctx, backend)
+    const events = [{ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }] as SessionEvent[]
     providePersistence(ctx, {
-      list: (signal?: AbortSignal) => backend.list(signal),
-      inspect: (id: SessionId, signal?: AbortSignal) => coordinator.inspect(id, signal),
-      borrowSession: (id: SessionId, signal?: AbortSignal) => coordinator.borrowSession(id, signal),
-      locate: () => undefined,
+      list: () => Promise.resolve([structuredClone(meta)]),
+      inspect: () => Promise.resolve({ meta: structuredClone(meta), events: structuredClone(events) }),
     })
     const remote = createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const history = await remote.page({
       address: { kind: 'session', sessionId },
-      throughSeq: 1,
-      beforeSeq: 2,
+      throughSeq: 0,
+      beforeSeq: 1,
       maxMessages: 10,
     })
     if (!history.ok) throw new Error('history failed')
@@ -413,17 +569,6 @@ describe('cold history recovery view', () => {
           "time": 1,
           "type": "turn/start",
         },
-        {
-          "data": {
-            "reason": {
-              "kind": "interrupted",
-            },
-            "turn": 1,
-          },
-          "seq": 1,
-          "time": 1,
-          "type": "turn/end",
-        },
       ]
     `)
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
@@ -439,15 +584,10 @@ describe('Remote Agent and Session lookup policy', () => {
     await ctx.plugin(AgentRegistry)
     const sessionId = sid('session-remote-cold')
     const meta = header(sessionId, 1000)
-    const inspect = vi.fn(() => Promise.resolve({
-      meta,
-      inheritedEventCount: SessionLogOffset(0),
-      events: [] as SessionEvent[],
-    }))
+    const inspect = vi.fn(() => Promise.resolve({ meta, events: [] as SessionEvent[] }))
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
       inspect,
-      locate: () => undefined,
     })
     const resumedSession = { id: sessionId, header: meta, events: [] } as unknown as import('@deepseek-ai/dsh-session').Session
     const resumedAgent = { id: sessionId, session: resumedSession, status: 'idle', ctx } as Agent
@@ -487,15 +627,10 @@ describe('Remote Agent and Session lookup policy', () => {
       parentSession: sid('session-parent'),
       origin: 'subagent',
     })
-    const inspect = vi.fn(() => Promise.resolve({
-      meta: coldMeta,
-      inheritedEventCount: SessionLogOffset(0),
-      events: [] as SessionEvent[],
-    }))
+    const inspect = vi.fn(() => Promise.resolve({ meta: coldMeta, events: [] as SessionEvent[] }))
     providePersistence(ctx, {
       list: () => Promise.resolve([coldMeta]),
       inspect,
-      locate: () => undefined,
     })
     const liveSession = ctx.sessions.create(sid('session-remote-live-child'), {
       meta: { cwd: '/proj', parentSession: sid('session-parent'), origin: 'subagent' },
@@ -535,19 +670,10 @@ describe('subagent ownership fence', () => {
     const sessionId = sid('session-child')
     const meta = header('session-child', 1000, {
       parentSession: sid('session-parent'),
-      isSeeded: true,
       origin: 'subagent',
     })
     const events = [
-      {
-        type: 'turn/start',
-        seq: SessionSeq(0),
-        time: 1,
-        data: {
-          turn: 1,
-          trigger: { kind: 'message', source: { kind: 'user' } },
-        } as SessionEvent<'turn/start'>['data'],
-      },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
       {
         type: 'user/message',
         seq: SessionSeq(1),
@@ -566,16 +692,11 @@ describe('subagent ownership fence', () => {
         }),
       },
       { type: 'turn/end', seq: SessionSeq(3), time: 4, data: { turn: 1, reason: { kind: 'completed' } } },
-    ] satisfies SessionEvent[]
-    const inspect = vi.fn(() => Promise.resolve({
-      meta,
-      inheritedEventCount: SessionLogOffset(0),
-      events,
-    }))
+    ] as SessionEvent[]
+    const inspect = vi.fn(() => Promise.resolve({ meta, events }))
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
       inspect,
-      locate: () => undefined,
     })
     const resume = vi.spyOn(ctx.agents, 'resume')
     const remote = createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
@@ -615,7 +736,9 @@ describe('subagent ownership fence', () => {
     if (!create.ok) expect(create.error.code).toBe('session/agent-busy')
     expect(resume).not.toHaveBeenCalled()
     expect(ctx.agents.get(sessionId)).toBeUndefined()
-    expect(inspect).toHaveBeenCalledTimes(3)
+    // One log open serves all three cold reads: the observation cache reuses
+    // the prepared Session while the stat revision is unchanged.
+    expect(inspect).toHaveBeenCalledTimes(1)
   })
 
   it('no longer treats a descriptor-only cold child without origin as subagent-owned', async () => {
@@ -625,7 +748,6 @@ describe('subagent ownership fence', () => {
     const sessionId = sid('session-legacy-child')
     const meta = header('session-legacy-child', 1000, {
       parentSession: sid('session-parent'),
-      isSeeded: true,
     })
     const events = [
       {
@@ -634,16 +756,10 @@ describe('subagent ownership fence', () => {
         time: 1,
         data: { version: 2, mode: 'continuable', provider: 'spawn', label: 'child' },
       },
-    ] satisfies SessionEvent[]
+    ] as SessionEvent[]
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
-      inspect: () => Promise.resolve({
-        meta,
-        inheritedEventCount: SessionLogOffset(0),
-        events,
-      }),
-      locate: () => undefined,
-    })
+      inspect: () => Promise.resolve({ meta, events })    })
     // Stores whose headers predate `origin` classify a child only through the
     // descriptor event; the pre-release decision stops recognizing them, so
     // the ownership fence lets generic resume reach the registry instead of
@@ -732,8 +848,8 @@ describe('subagent ownership fence', () => {
         time: 1,
         data: { version: 2, mode: 'continuable', provider: 'spawn', label: 'ancestor' },
       }],
-      inheritedEventCount: SessionLogOffset(1),
       meta: { cwd: '/proj', parentSession: sid('session-source'), isSeeded: true },
+      inheritedEventCount: SessionLogOffset(1),
     })
     const followup = vi.fn()
     const agent = { id: session.id, session, status: 'idle', ctx, followup } as unknown as Agent
@@ -844,8 +960,10 @@ describe('degenerate composition (no persistence, no factory)', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     const inspect = vi.fn()
+    const stat = vi.fn(() => Promise.resolve(undefined))
     providePersistence(ctx, {
       list: () => Promise.resolve([]),
+      stat,
       inspect,
     })
     const remote = createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
@@ -856,7 +974,9 @@ describe('degenerate composition (no persistence, no factory)', () => {
     })
     expect(response.ok).toBe(false)
     if (!response.ok) expect(response.error.code).toBe('session/not-found')
-    expect(inspect).toHaveBeenCalledOnce()
+    // Absence is decided by the stat preflight; the log itself is never opened.
+    expect(stat).toHaveBeenCalledOnce()
+    expect(inspect).not.toHaveBeenCalled()
   })
 })
 
@@ -901,13 +1021,7 @@ describe('sessions.prompt synchronous rejection', () => {
     const meta: SessionHeader = header('race-resume', 1000)
     providePersistence(ctx, {
       list: () => Promise.resolve([meta]),
-      inspect: () => Promise.resolve({
-        meta,
-        inheritedEventCount: SessionLogOffset(0),
-        events: [] as SessionEvent[],
-      }),
-      locate: () => undefined,
-    })
+      inspect: () => Promise.resolve({ meta, events: [] as SessionEvent[] })    })
     // The raced winner: a live parent-owned subagent publishes the identity
     // while the generic cold resume is in flight, so the resume collides.
     const parentSession = ctx.sessions.create(sid('race-parent'), { meta: { cwd: '/proj' } })
diff --git a/packages/api/session-controller/tests/session-projections.host.spec.ts b/packages/api/session-controller/tests/session-projections.host.spec.ts
index 3f57e1afe2..6b97a08195 100644
--- a/packages/api/session-controller/tests/session-projections.host.spec.ts
+++ b/packages/api/session-controller/tests/session-projections.host.spec.ts
@@ -27,7 +27,7 @@ import Storage from '@deepseek-ai/dsh-storage'
 import * as StorageDomain from '@deepseek-ai/dsh-storage-domain'
 import * as StorageJson from '@deepseek-ai/dsh-storage-json'
 import type { SessionControlFrame, SessionFollowFrame } from '@deepseek-ai/dsh-api-session-controller/types'
-import { createSessionTestRemote, type TestSessionRemote } from './test-remote.ts'
+import { createSessionTestRemote, testSessionPersistence, type TestSessionRemote } from './test-remote.ts'
 
 declare module '@deepseek-ai/dsh-session-projection/types' {
   interface SessionProjectionStateMap {
@@ -434,13 +434,11 @@ describe('session.list projections column', () => {
     const { ctx } = await harness(true)
     const coldId = SessionId('session-cold-listing')
     const load = () => { throw new Error('list must not load event logs') }
-    ctx.provide('sessionPersistence', {
-      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
-      locate: () => undefined,
-      load,
+    ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, isSeeded: false, cwd: '/tmp' }],
       inspect: load,
-      readFrom: load,
-    } as never)
+      open: load,
+    }) as never)
     ctx.provide('sessionProjectionCache', {
       // The carrier hands the listed header through as the identity witness.
       cachedSnapshot: (meta: { id: unknown; createdAt: number }) =>
@@ -507,8 +505,7 @@ describe('session.list projections column', () => {
       await owner.dispose()
       expect(ctx.sessions.get(id)).toBeUndefined()
       ctx.provide('sessionPersistence', {
-        list: async () => [header],
-        locate: () => undefined,
+        list: async () => [{ header, revision: 'test:cold-host-state:1' }],
       } as never)
 
       const response = await gateway.list(request({}))
@@ -526,10 +523,9 @@ describe('session.list projections column', () => {
   it('cold rows without a cache plugin (or without a stored row) just lack the column', async () => {
     const { ctx } = await harness(true)
     const coldId = SessionId('session-cold-uncached')
-    ctx.provide('sessionPersistence', {
-      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
-      locate: () => undefined,
-    } as never)
+    ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, isSeeded: false, cwd: '/tmp' }],
+    }) as never)
     const response = await remote(ctx).list(request({}))
     if (!response.ok) throw new Error('unreachable')
     const row = response.value.items.find(item => item.sessionId === coldId)
diff --git a/packages/api/session-controller/tests/session-search.host.spec.ts b/packages/api/session-controller/tests/session-search.host.spec.ts
index 89d1a2f424..1d88f9d47a 100644
--- a/packages/api/session-controller/tests/session-search.host.spec.ts
+++ b/packages/api/session-controller/tests/session-search.host.spec.ts
@@ -17,7 +17,7 @@ import {
   type SessionSearchHit,
   type SessionSearchRequest,
 } from '@deepseek-ai/dsh-session-query'
-import { createSessionTestRemote } from './test-remote.ts'
+import { createSessionTestRemote, testSessionPersistence } from './test-remote.ts'
 import { ApiSessionList } from '../src/list.ts'
 
 const sid = (value: string): SessionId => value as SessionId
@@ -96,7 +96,7 @@ function installSearchQuery(
 describe('session.search', () => {
   it('rejects search when the query service is absent', async () => {
     const ctx = await baseContext()
-    const list = new ApiSessionList(ctx, 0)
+    const list = new ApiSessionList(ctx, { coldBlankProbeMaxEvents: 16, coldBlankProbeMaxBytes: 1024 })
 
     await expect(list.search('query', new AbortController().signal)).rejects.toMatchObject({
       code: 'gateway/internal',
@@ -113,10 +113,9 @@ describe('session.search', () => {
     }), { surfaceOp: 'append' })
     const cold = header('cold', '/cold')
     const legacy = header('legacy', null)
-    ctx.provide('sessionPersistence', {
+    ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list: () => Promise.resolve([cold, legacy]),
-      locate: () => undefined,
-    } as never)
+    }) as never)
 
     const searchSessions = vi.fn((
       _request: SessionSearchRequest,
@@ -770,10 +769,9 @@ describe('session.search', () => {
       { length: 32_751 },
       (_, index) => header(`cold-${index}`, `/cold-${index}`),
     )
-    ctx.provide('sessionPersistence', {
+    ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list: () => Promise.resolve(cold),
-      locate: () => undefined,
-    } as never)
+    }) as never)
     const searchSessions = vi.fn((_request: SessionSearchRequest) => Promise.resolve({
       items: [hit('cold-32750')],
     }))
@@ -804,14 +802,14 @@ describe('session.search', () => {
       controller.abort()
       return Promise.resolve(cold)
     })
-    let locateCalls = 0
-    ctx.provide('sessionPersistence', {
+    let statCalls = 0
+    ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list,
-      locate: () => {
-        locateCalls++
-        return undefined
+      stat: () => {
+        statCalls++
+        return Promise.resolve(undefined)
       },
-    } as never)
+    }) as never)
     const searchSessions = vi.fn()
     installSearchQuery(ctx, searchSessions)
 
@@ -825,18 +823,20 @@ describe('session.search', () => {
       error: { code: 'gateway/cancelled' },
     })
     expect(list).toHaveBeenCalledOnce()
-    expect(locateCalls).toBe(0)
+    expect(statCalls).toBe(0)
     expect(searchSessions).not.toHaveBeenCalled()
   })
 
-  it('does not stat or locate cold artifacts while collecting search visibility', async () => {
+  it('does not stat or open cold artifacts while collecting search visibility', async () => {
     const ctx = await baseContext()
     const cold = Array.from({ length: 16 }, (_, index) => header(`cold-${index}`, `/cold-${index}`))
-    const locate = vi.fn((meta: SessionHeader) => ({ kind: 'jsonl', path: `/logs/${meta.id}.jsonl` }))
-    ctx.provide('sessionPersistence', {
+    const stat = vi.fn()
+    const inspect = vi.fn()
+    ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list: () => Promise.resolve(cold),
-      locate,
-    } as never)
+      stat,
+      inspect,
+    }) as never)
     const searchSessions = vi.fn(() => Promise.resolve({ items: [] }))
     installSearchQuery(ctx, searchSessions)
 
@@ -848,7 +848,8 @@ describe('session.search', () => {
       ok: true,
       value: { items: [], hasMore: false },
     })
-    expect(locate).not.toHaveBeenCalled()
+    expect(stat).not.toHaveBeenCalled()
+    expect(inspect).not.toHaveBeenCalled()
     expect(searchSessions).toHaveBeenCalledOnce()
   })
 
diff --git a/packages/api/session-controller/tests/test-remote.ts b/packages/api/session-controller/tests/test-remote.ts
index 2794e52ffe..1b5859b509 100644
--- a/packages/api/session-controller/tests/test-remote.ts
+++ b/packages/api/session-controller/tests/test-remote.ts
@@ -1,15 +1,20 @@
 /** Test-only direct Remote face over the Session Controller's internal controllers. */
 
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ModelSelection as AgentModelSelection } from '@deepseek-ai/dsh-agent'
-import { SessionLogOffset } from '@deepseek-ai/dsh-session'
-import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import {
-  SessionPersistenceCorruptionError,
   SessionPersistenceNotFoundError,
   SessionPersistenceRevision,
-  type BorrowedSessionSource,
-  type SessionInspection,
+  SessionReadOnlyError,
+  type SessionAccess,
+  type SessionHandle,
+  type SessionHandleReadOptions,
+  type SessionPersistenceListOptions,
+  type SessionPersistenceOpenOptions,
+  type SessionPersistenceSnapshot,
+  type SessionPersistenceStatOptions,
 } from '@deepseek-ai/dsh-session-persistence'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SessionQueryEngine from '@deepseek-ai/dsh-session-query'
@@ -78,6 +83,7 @@ export interface TestSessionRemote {
 export interface TestSessionRemoteDefaults {
   readonly defaultModelSelection: () => AgentModelSelection
   readonly cwd: string
+  readonly coldBlankProbeMaxEvents?: number
   readonly coldBlankProbeMaxBytes?: number
   readonly nativeOpen?: boolean
   readonly saveDefaultModelSelection?: (selection: AgentModelSelection) => void | Promise<void>
@@ -87,63 +93,102 @@ export interface TestSessionRemoteDefaults {
 
 const installed = new WeakMap<Context, SessionController>()
 
+/** Compact header-and-events point read a persistence double declares per session. */
+interface TestSessionInspection {
+  readonly meta: SessionHeader
+  readonly events: readonly SessionEvent[]
+}
+
 type LegacyTestPersistence = Record<string, unknown> & {
+  readonly list?: (signal?: AbortSignal) => Promise<readonly SessionHeader[]>
   readonly inspect?: (
     sessionId: SessionId,
     signal?: AbortSignal,
-  ) => Promise<SessionInspection | undefined>
-  readonly borrowSession?: (
+  ) => Promise<TestSessionInspection | undefined>
+  readonly stat?: (
     sessionId: SessionId,
-    signal?: AbortSignal,
-  ) => Promise<BorrowedSessionSource>
+    options?: SessionPersistenceStatOptions,
+  ) => Promise<SessionPersistenceSnapshot | undefined>
+  readonly open?: (
+    sessionId: SessionId,
+    access: SessionAccess,
+    options?: SessionPersistenceOpenOptions,
+  ) => Promise<SessionHandle>
 }
 
-/** Add the preparation-backed point-read contract to compact persistence doubles. */
-export function testSessionPersistence(
-  ctx: Context,
-  persistence: LegacyTestPersistence,
-): LegacyTestPersistence {
-  if (persistence.borrowSession !== undefined) return persistence
+/** One immutable read handle over a double's inspected header and events. */
+function testReadHandle(
+  sessionId: SessionId,
+  inspection: TestSessionInspection,
+): SessionHandle {
+  const events = Object.freeze([...inspection.events])
   return {
-    ...persistence,
-    borrowSession: async (sessionId, signal) => {
-      signal?.throwIfAborted()
-      const inspection = await persistence.inspect?.(sessionId, signal)
-      signal?.throwIfAborted()
-      if (inspection === undefined) throw new SessionPersistenceNotFoundError(sessionId)
-      try {
-        const inheritedEventCount = (inspection as Partial<SessionInspection>).inheritedEventCount
-        if (inspection.meta.isSeeded && inheritedEventCount === undefined) {
-          throw new Error('seeded test persistence must provide inheritedEventCount')
-        }
-        const cut = SessionLogOffset(inheritedEventCount ?? 0)
-        const preparedSession = ctx.sessions.prepare(inspection.meta.id, {
-          seed: [...inspection.events],
-          meta: inspection.meta,
-          inheritedEventCount: cut,
-          seedSource: 'persistence',
-        })
-        return {
-          source: 'prepared',
-          inspection: {
-            meta: preparedSession.header,
-            inheritedEventCount: preparedSession.inheritedEventCount,
-            events: Object.freeze([...inspection.events]),
-          },
-          revision: SessionPersistenceRevision(`test:${sessionId}:${String(preparedSession.seq)}`),
-          preparedSession,
-          [Symbol.dispose]: () => {},
-        }
-      } catch (error: unknown) {
-        throw new SessionPersistenceCorruptionError(
-          `test session "${sessionId}" failed validation: ${String(error)}`,
-          { cause: error },
-        )
-      }
+    id: sessionId,
+    header: inspection.meta,
+    inheritedEventCount: SessionLogOffset(0),
+    access: 'read',
+    read: (offset = 0, length?: number, options?: SessionHandleReadOptions) => {
+      options?.signal?.throwIfAborted()
+      return Promise.resolve(events.slice(offset, length === undefined ? undefined : offset + length))
     },
+    append: () => Promise.reject(new SessionReadOnlyError(sessionId, 'append')),
+    flush: () => Promise.reject(new SessionReadOnlyError(sessionId, 'flush')),
+    close: () => Promise.resolve(),
+    [Symbol.asyncDispose]: () => Promise.resolve(),
   }
 }
 
+/**
+ * Adapt a compact header/inspect persistence double onto the handle-based
+ * abstract the production readers consume: `list` snapshots wrap the double's
+ * headers, `stat` derives a metadata-less snapshot from the listing (so the
+ * cold-blank probe skips unless the double declares its own `stat`), and
+ * `open` serves immutable read handles over the double's `inspect` result.
+ */
+export function testSessionPersistence(
+  _ctx: Context,
+  persistence: LegacyTestPersistence,
+): Record<string, unknown> {
+  const listHeaders = async (signal?: AbortSignal): Promise<readonly SessionHeader[]> =>
+    await persistence.list?.(signal) ?? []
+  const adapted: Record<string, unknown> = {
+    ...persistence,
+    list: async (options?: SessionPersistenceListOptions) =>
+      (await listHeaders(options?.signal)).map(header => ({
+        header,
+        revision: SessionPersistenceRevision(`test:${header.id}:list`),
+      })),
+  }
+  if (persistence.stat === undefined) {
+    adapted.stat = async (
+      sessionId: SessionId,
+      options?: SessionPersistenceStatOptions,
+    ): Promise<SessionPersistenceSnapshot | undefined> => {
+      options?.signal?.throwIfAborted()
+      const header = (await listHeaders(options?.signal)).find(listed => listed.id === sessionId)
+      return header === undefined
+        ? undefined
+        : { header, revision: SessionPersistenceRevision(`test:${sessionId}:stat`) }
+    }
+  }
+  if (persistence.open === undefined) {
+    adapted.open = async (
+      sessionId: SessionId,
+      access: SessionAccess,
+      options?: SessionPersistenceOpenOptions,
+    ): Promise<SessionHandle> => {
+      options?.signal?.throwIfAborted()
+      if (access !== 'read') {
+        throw new Error(`test persistence double only serves read handles (requested "${access}")`)
+      }
+      const inspection = await persistence.inspect?.(sessionId, options?.signal)
+      if (inspection === undefined) throw new SessionPersistenceNotFoundError(sessionId)
+      return testReadHandle(sessionId, inspection)
+    }
+  }
+  return adapted
+}
+
 /** Concrete point-read query used by Session Controller tests that do not exercise search. */
 class TestSessionQuery extends SessionQueryEngine {
   override searchSessions(): Promise<never> {
@@ -198,6 +243,9 @@ function installControllers(
     controller = new SessionController(
       ctx,
       {
+        ...defaults.coldBlankProbeMaxEvents === undefined
+          ? {}
+          : { coldBlankProbeMaxEvents: defaults.coldBlankProbeMaxEvents },
         ...defaults.coldBlankProbeMaxBytes === undefined
           ? {}
           : { coldBlankProbeMaxBytes: defaults.coldBlankProbeMaxBytes },
diff --git a/packages/api/session-controller/tests/transport.host.spec.ts b/packages/api/session-controller/tests/transport.host.spec.ts
index b6eeda6b41..d88f79e2d9 100644
--- a/packages/api/session-controller/tests/transport.host.spec.ts
+++ b/packages/api/session-controller/tests/transport.host.spec.ts
@@ -183,6 +183,7 @@ describe('SessionHistoryController', () => {
       events: readonly SessionEvent[]
     }>()
     ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
+      list: () => Promise.resolve([header]),
       inspect: () => inspected.promise,
     }) as never)
     const abort = new AbortController()
@@ -468,7 +469,7 @@ describe('SessionHistoryController', () => {
     const { ctx, transport } = await setup()
     const sessionId = SessionId('corrupt-cold')
     const failure = new Error('cold log is corrupt')
-    const header = { version: 0, id: sessionId, createdAt: 1, cwd: '/workspace' }
+    const header = { version: 0, id: sessionId, createdAt: 1, isSeeded: false, cwd: '/workspace' }
     ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list: () => Promise.resolve([header]),
       inspect: () => Promise.reject(failure),
@@ -525,8 +526,10 @@ describe('SessionHistoryController', () => {
       .rejects.toMatchObject({ code: 'session/not-found' })
 
     const inspect = vi.fn(() => Promise.resolve(undefined))
+    const stat = vi.fn(() => Promise.resolve(undefined))
     ctx.provide('sessionPersistence', testSessionPersistence(ctx, {
       list: () => Promise.resolve([]),
+      stat,
       inspect,
     }) as never)
     await expect(transport.page({ address: ordinary, throughSeq: -1 }, signal()))
@@ -540,7 +543,9 @@ describe('SessionHistoryController', () => {
       },
       throughSeq: -1,
     }, signal())).rejects.toMatchObject({ code: 'subagent/not-found' })
-    expect(inspect).toHaveBeenCalledTimes(2)
+    // Absence is decided by the stat preflight; no log open is attempted.
+    expect(stat).toHaveBeenCalledTimes(2)
+    expect(inspect).not.toHaveBeenCalled()
   })
 
   it('rejects incomplete cold metadata before serving a source', async () => {
diff --git a/packages/compaction/compaction-basic/tests/compaction-loop-repro.spec.ts b/packages/compaction/compaction-basic/tests/compaction-loop-repro.spec.ts
index f7b44e1940..c695031a0d 100644
--- a/packages/compaction/compaction-basic/tests/compaction-loop-repro.spec.ts
+++ b/packages/compaction/compaction-basic/tests/compaction-loop-repro.spec.ts
@@ -225,7 +225,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
       ...await next(), provider: 'mock', model: 'mock',
     }))
     try {
-      const agent = ctx.agentLoop.create(SessionId('routed-pressure'), {
+      const agent = await ctx.agentLoop.create(SessionId('routed-pressure'), {
         provider: 'unconfigured-agent-fallback',
         model: 'unconfigured-agent-fallback',
       })
@@ -246,7 +246,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
   it('runs automatic pressure between the completed tool step and the next step', async () => {
     const { ctx } = await harness(8)
     try {
-      const agent = ctx.agentLoop.create(SessionId('post-step-order'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('post-step-order'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'do tool work' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
 
@@ -278,7 +278,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
   it('the head checkpoint the loop lands is a balanced cut on both sides', async () => {
     const { ctx } = await harness(8)
     try {
-      const agent = ctx.agentLoop.create(SessionId('repro'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('repro'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'do a long multi-step task' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
 
diff --git a/packages/compaction/compaction-basic/tests/manual-compaction.spec.ts b/packages/compaction/compaction-basic/tests/manual-compaction.spec.ts
index 4aa8d27cde..0bc8c8e6ae 100644
--- a/packages/compaction/compaction-basic/tests/manual-compaction.spec.ts
+++ b/packages/compaction/compaction-basic/tests/manual-compaction.spec.ts
@@ -110,7 +110,7 @@ async function loopHarness(): Promise<LoopHarness> {
   const adapter = new TextAdapter()
   ctx.llm.registerAdapter([MODEL], adapter)
   const compact = new GatedCompactionEngine(ctx, { auto: false })
-  const agent = ctx.agentLoop.create(SessionId('manual-compact'), { provider: MODEL, model: MODEL })
+  const agent = await ctx.agentLoop.create(SessionId('manual-compact'), { provider: MODEL, model: MODEL })
   const log: string[] = []
   ctx.on('session/event', (_session, event) => {
     if (event.type === 'turn/start') log.push('turn/start')
diff --git a/packages/context/agent-instructions/tests/agent-instructions.spec.ts b/packages/context/agent-instructions/tests/agent-instructions.spec.ts
index af270437b1..28669e88d0 100644
--- a/packages/context/agent-instructions/tests/agent-instructions.spec.ts
+++ b/packages/context/agent-instructions/tests/agent-instructions.spec.ts
@@ -2548,7 +2548,7 @@ describe('dynamic nested workspace context injection', () => {
       await mountWorkspaceContextPlugin(ctx, { dshHome: home, maxBytes: 65536 })
       await ctx.plugin(AgentLoop, { agents: [] })
       ctx.llm.registerAdapter(['mock'], adapter)
-      const agent = ctx.agentLoop.create(SessionId('workspace-context-abort'), { provider: 'mock', model: 'mock' }, { cwd: root })
+      const agent = await ctx.agentLoop.create(SessionId('workspace-context-abort'), { provider: 'mock', model: 'mock' }, { cwd: root })
       ctx.tools.register(defineContentToolFixture({
         name: 'abort_step',
         description: 'Abort the current test step.',
diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts
index ec8976fead..63d1bcb2b0 100644
--- a/packages/context/time-context/tests/time-context.spec.ts
+++ b/packages/context/time-context/tests/time-context.spec.ts
@@ -453,7 +453,7 @@ describe('real agent-loop request history', () => {
       subject.cancel({ kind: 'user' })
       return next()
     })
-    const agent = ctx.agentLoop.create(SessionId(`late-${mode}`), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId(`late-${mode}`), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'start' }], source: { kind: 'user' } }))
     await agent.whenIdle()
@@ -476,7 +476,7 @@ describe('real agent-loop request history', () => {
         return [{ type: 'text' as const, text: 'advanced' }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('loop'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('loop'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'start' }], source: { kind: 'user' } }))
     await agent.whenIdle()
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index 5f61e791ac..7541d9a310 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/agent-loop/README.md
-README.md: 60d1e75a5038500a42244a45fb077e1eb71da092
-README.zh.md: 166ba6ff366f9a8c8c687b4521bb04b591814851
+README.md: 5e4ab0a741f0b7dae821e52f1a9b0a1faa90ceed
+README.zh.md: ef47f897978c8254242075a559f56faa2dceca19
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 60d1e75a50..5e4ab0a741 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -103,7 +103,11 @@ After `agent/request`, `ctx.llm.prepareCall()` validates adapter-owned fields an
 
 ### Creation and teardown
 
-Creation is one rollback-covered transaction: construct a private session, concrete agent, and scoped context; await optional setup; enter both registries; announce `session/created` then `agent/created`; emit `agent/session-start`; only then start the driver. A setup throw, commit failure, or owner disposal rolls the transaction back without publishing either id. Teardown runs stop-and-drain, unwind the scope, detach the agent, then detach the session, and every detach is bound to the exact entered object so a stale disposer cannot remove a later same-id replacement.
+Creation is one rollback-covered transaction: construct a private session, concrete agent, and scoped context; await optional setup; enter both registries; announce `session/created` then `agent/created`; emit `agent/session-start`; only then start the driver. A setup throw, commit failure, or owner disposal rolls the transaction back without publishing either id. Teardown runs stop-and-drain, closes the session's write path, unwinds the scope, detaches the agent, then detaches the session, and every detach is bound to the exact entered object so a stale disposer cannot remove a later same-id replacement.
+
+### Persistence integration
+
+The loop is the production acquisition point for session write handles. When `ctx.sessionPersistence` is mounted, `create`/`createAgent` call `persistence.create(header)` — storing the durable identity and taking write ownership before publication — and append the constructor seed through the handle; `resume` calls `persistence.open(id, 'write')` first (excluding a concurrent resume of the same id), reads the physically valid log through the handle, and appends `interruptedTurnClosers` for a log crashed mid-turn as an ordinary batch — semantic crash repair is the agent layer's job, not a storage entry point. Immediately before publication, `appendUnstoredSuffix` stores any events appended during the setup window (seed markers, delegation policy records), which never re-emit through `session/event`. Once published, the mounted backend routes the session's `session/event` batches, `session/flush` barriers, and `session/disposed` retirement into the active write handle by session id; the loop touches storage only through the handle it owns. The memoized teardown closes the handle — close drains any routed buffer — after the loop commits the session's closing events, provably releasing write ownership. Without a backend, sessions are memory-only and nothing else changes.
 
 ### Turn and step flow
 
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index 166ba6ff36..ef47f89797 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -103,7 +103,11 @@ const handle = await ctx.agents.create({
 
 ### 创建与拆除
 
-创建是同一个受回滚保护的事务：构造私有会话、具象 agent 与带作用域上下文；等待可选 setup；进入两个注册表；依次宣告 `session/created` 与 `agent/created`；发出 `agent/session-start`；此后才启动驱动器。Setup 抛出、commit 失败或所有者 dispose 都会回滚事务而不发布任一 id。Teardown 顺序是停止并排空、撤销作用域、detach agent、再 detach 会话，且每次 detach 都绑定到确切进入的对象，因此陈旧 disposer 无法移除之后出现的同 id 替代项。
+创建是同一个受回滚保护的事务：构造私有会话、具象 agent 与带作用域上下文；等待可选 setup；进入两个注册表；依次宣告 `session/created` 与 `agent/created`；发出 `agent/session-start`；此后才启动驱动器。Setup 抛出、commit 失败或所有者 dispose 都会回滚事务而不发布任一 id。Teardown 顺序是停止并排空、关闭会话的写路径、撤销作用域、detach agent、再 detach 会话，且每次 detach 都绑定到确切进入的对象，因此陈旧 disposer 无法移除之后出现的同 id 替代项。
+
+### 持久化集成
+
+循环是会话写句柄在生产环境中的获取点。挂载 `ctx.sessionPersistence` 后，`create`/`createAgent` 调用 `persistence.create(header)`——在发布之前存储持久身份并取得写所有权——并通过句柄追加构造 seed；`resume` 先调用 `persistence.open(id, 'write')`（排除同 id 的并发恢复），通过句柄读取物理上有效的日志，并为在轮次中途崩溃的日志把 `interruptedTurnClosers` 作为普通批次追加——语义崩溃修复是 agent 层的职责，而非存储入口。发布前的最后一刻，`appendUnstoredSuffix` 存储 setup 窗口期间追加的事件（seed 标记、委派策略记录），它们绝不会经由 `session/event` 重新发出。发布之后，挂载的后端按会话 id 把该会话的 `session/event` 批次、`session/flush` 屏障与 `session/disposed` 退役路由进活跃写句柄；循环只通过它拥有的句柄触碰存储。记忆化的 teardown 在循环提交会话的收尾事件之后关闭句柄——close 会排空任何已路由的缓冲——可证明地释放写所有权。没有后端时，会话只存在于内存中，其余一切不变。
 
 ### 轮次与步骤流程
 
diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts
index 572f2bcc7b..743f386bfc 100644
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -24,13 +24,14 @@ import type {
 } from '@deepseek-ai/dsh-agent'
 import { errorChain, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-settings'
-import { SessionPreparation, SessionSeq } from '@deepseek-ai/dsh-session'
+import { interruptedTurnClosers, SessionLogOffset, SessionPreparation, SessionSeq } from '@deepseek-ai/dsh-session'
 import type { Session, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
 import type {} from '@deepseek-ai/dsh-session-projection'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
-import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+import { SessionPersistenceNotFoundError } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionHandle, SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import { ReactLoopAgent } from './agent.ts'
 import { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from './constants.ts'
 
@@ -202,6 +203,12 @@ function assertAgentOptions(options: AgentOptions): void {
   }
 }
 
+/** One session's owned write handle plus the count of events already stored through it. */
+interface StoredSession {
+  readonly handle: SessionHandle
+  storedCount: number
+}
+
 /** Prepared-but-unpublished agent resources sharing one memoized teardown. */
 interface PreparedAgent {
   agent: ReactLoopAgent
@@ -421,7 +428,10 @@ export class AgentLoop extends Service implements AgentFactory {
         const configuredId = sessionId ?? brandString<SessionId>(`${id}-session-${randomUUID()}`)
         const persistence = sessionId === undefined ? undefined : ctx.get('sessionPersistence')
         if (persistence === undefined) {
-          this.create(configuredId, options, meta)
+          const startup = this.create(configuredId, options, meta).then(() => undefined, (error: unknown) => {
+            this.reportConfiguredStartupFailure(id, 'restore', configuredId, error)
+          })
+          this.ownership.trackStartup(startup)
         } else {
           const startup = this.restoreOrCreateConfigured(ctx, persistence, configuredId, options, meta).catch((error: unknown) => {
             this.reportConfiguredStartupFailure(id, 'restore', configuredId, error)
@@ -481,13 +491,11 @@ export class AgentLoop extends Service implements AgentFactory {
       return
     } catch (error: unknown) {
       if (!this.ownership.isActive()) return
-      // A load is the per-id serialization barrier for eager write-behind and
-      // lifecycle retirement. Only a genuinely absent artifact falls back to
-      // first creation; corruption and backend failures stay loud.
-      const exists = (await persistence.list()).some(header => header.id === sessionId)
-      if (exists) throw error
+      // Only a genuinely absent stored session falls back to first creation;
+      // corruption, ownership conflicts, and backend failures stay loud.
+      if (!(error instanceof SessionPersistenceNotFoundError)) throw error
     }
-    this.create(sessionId, agentOptions, meta)
+    await this.create(sessionId, agentOptions, meta)
   }
 
   /** Wait for a draining same-id lifecycle to finish registry teardown. */
@@ -519,7 +527,14 @@ export class AgentLoop extends Service implements AgentFactory {
    * BEFORE publication, so a mid-setup unload rolls everything back; `signal`
    * fuses caller cancellation with lifecycle teardown for setup awaits.
    */
-  private prepare(ownerCtx: Context, id: SessionId, options: AgentOptions, session: Session, callerSignal?: AbortSignal): PreparedAgent {
+  private prepare(
+    ownerCtx: Context,
+    id: SessionId,
+    options: AgentOptions,
+    session: Session,
+    callerSignal?: AbortSignal,
+    handle?: SessionHandle,
+  ): PreparedAgent {
     assertAgentOptions(options)
     ownerCtx.fiber.assertActive()
     // Every caller reaches prepare() synchronously from a service method
@@ -555,12 +570,16 @@ export class AgentLoop extends Service implements AgentFactory {
     let disposing: Promise<void> | undefined
     const machineReady = Promise.withResolvers<void>()
     // Reverse teardown, memoized so every racing owner awaits one quiescence:
-    // stop the machine, leave the registries, unwind the scope, release
-    // bookkeeping.
+    // stop the machine, drain and close the session's write path, leave the
+    // registries, unwind the scope, release bookkeeping.
     const dispose = (ownerTriggered = false): Promise<void> => (disposing ??= (async () => {
       abort.abort(new Error(`agent "${id}" lifecycle disposed`))
       callerSignal?.removeEventListener('abort', onCallerAbort)
       this.ownership.signal.removeEventListener('abort', onFactoryTeardown)
+      // Teardown failures are collected, never swallowed: registry, scope,
+      // and ownership cleanup always run to quiescence, then the memoized
+      // disposal rejects with what failed so every racing owner observes it.
+      const failures: unknown[] = []
       try {
         // Disposal IS a disposed-cause cancel followed by quiescence. New work
         // sent after this point is the sender's bug — the registries are about
@@ -571,14 +590,28 @@ export class AgentLoop extends Service implements AgentFactory {
           await machine.whenIdle()
           await machine.scope.dispose()
         }
+      } catch (error: unknown) {
+        failures.push(error)
+      }
+      // The loop above committed its closing events synchronously into the
+      // session; handle close drains them durably before releasing the write
+      // path. The close drain can be the first operation that surfaces a
+      // durability failure, so its error is retained, not logged away.
+      try {
+        await handle?.close()
+      } catch (error: unknown) {
+        failures.push(error)
+      }
+      try {
+        detachAgent?.()
+        detachSession?.()
       } finally {
-        try {
-          detachAgent?.()
-          detachSession?.()
-        } finally {
-          untrack()
-          if (!ownerTriggered) await unfollowOwner()
-        }
+        untrack()
+        if (!ownerTriggered) await unfollowOwner()
+      }
+      if (failures.length === 1) throw failures[0]
+      if (failures.length > 1) {
+        throw new AggregateError(failures, `agent "${id}" disposal failed`)
       }
     })())
     const untrack = this.ownership.track(dispose)
@@ -619,6 +652,8 @@ export class AgentLoop extends Service implements AgentFactory {
         publish: (source) => {
           assertLive()
           detachSession = agent.ctx.sessions.enter(session)
+          // The mounted backend routes announced live events into the active
+          // write handle by session id; the loop only owns the handle itself.
           detachAgent = loopCtx.agents.enter(agent, ownerCtx.agent)
           agent.ctx.sessions.announce(session)
           assertLive()
@@ -635,7 +670,8 @@ export class AgentLoop extends Service implements AgentFactory {
       }
     } catch (error: unknown) {
       machineReady.resolve()
-      void dispose()
+      // Rollback swallows a disposal rejection: the setup failure is primary.
+      void dispose().catch(() => {})
       throw error
     }
   }
@@ -643,21 +679,70 @@ export class AgentLoop extends Service implements AgentFactory {
   /**
    * Create an agent and session under one caller-supplied identity, owned by
    * the accessing fiber. Constructor-driven config calls mint a fresh combined
-   * id before entering this boundary.
+   * id before entering this boundary. When a persistence backend is mounted,
+   * the session's durable identity and any seed are stored before publication.
    * @param id - shared agent/session identity.
    * @param options - concrete loop options.
    * @param meta - optional fresh-session workspace metadata.
    * @returns the published running agent.
    */
-  create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent {
+  async create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Promise<Agent> {
     using preparation = SessionPreparation.create(this.runtime.ctx.sessions.prepare(id, { meta }))
-    const prepared = this.prepare(this.ctx, id, options, preparation.session)
+    const stored = await this.createStoredSession(preparation.session)
+    let prepared: PreparedAgent
     try {
-      return prepared.publish('startup').agent
+      prepared = this.prepare(this.ctx, id, options, preparation.session, undefined, stored?.handle)
     } catch (error: unknown) {
-      void prepared.dispose()
+      await stored?.handle.close().catch(() => {})
       throw error
     }
+    try {
+      await this.appendUnstoredSuffix(stored, preparation.session)
+      return prepared.publish('startup').agent
+    } catch (error: unknown) {
+      // Rollback swallows a disposal rejection: the setup failure is primary.
+      void prepared.dispose().catch(() => {})
+      throw error
+    }
+  }
+
+  /**
+   * Take a fresh session's write ownership when persistence is mounted.
+   * Nothing is appended here: the constructor seed (which never re-emits
+   * through `session/event`) is stored by `appendUnstoredSuffix` at the
+   * publication commit point, so a failed or cancelled validation or setup
+   * closes an unmaterialized handle and leaves no stored residue — the same
+   * id can be created again.
+   * @param session - the unpublished session to store.
+   * @param signal - optional cancellation forwarded to the backend create.
+   * @returns the owned handle and stored cursor, or `undefined` without a backend.
+   */
+  private async createStoredSession(session: Session, signal?: AbortSignal): Promise<StoredSession | undefined> {
+    const persistence = this.runtime.ctx.get('sessionPersistence')
+    if (persistence === undefined) return undefined
+    const handle = await persistence.create(session.header, {
+      inheritedEventCount: session.inheritedEventCount,
+      ...signal === undefined ? {} : { signal },
+    })
+    return { handle, storedCount: 0 }
+  }
+
+  /**
+   * Durably store the session events appended since the last stored cursor.
+   * Pre-publication appends (constructor seed markers, setup-window events
+   * such as delegation policy records) never re-emit through `session/event`,
+   * so publication must flush them through the handle before live events
+   * start routing into it.
+   * @param stored - the session's owned handle and stored cursor, if any.
+   * @param session - the unpublished session whose suffix is stored.
+   */
+  private async appendUnstoredSuffix(stored: StoredSession | undefined, session: Session): Promise<void> {
+    if (stored === undefined) return
+    const suffix = session.snapshotEvents(SessionLogOffset(stored.storedCount))
+    if (suffix.length > 0) await stored.handle.append(suffix)
+    // Advance by what was stored, not to `session.seq`: an event appended
+    // during the await must stay unstored for the next flush.
+    stored.storedCount += suffix.length
   }
 
   /**
@@ -672,15 +757,34 @@ export class AgentLoop extends Service implements AgentFactory {
       ...options.meta === undefined ? {} : { meta: options.meta },
       ...options.inheritedEventCount === undefined ? {} : { inheritedEventCount: options.inheritedEventCount },
     }))
-    const published = this.setupAndPublish(
-      ownerCtx,
-      options.sessionId,
-      preparation,
-      options.agentOptions ?? {},
-      options.setup,
-      options.signal,
-      'startup',
-    )
+    const published = (async () => {
+      let stored: StoredSession | undefined
+      try {
+        // raceAbortCall normalizes a pre-aborted or mid-create abort and
+        // closes a handle that finishes creating after abandonment.
+        stored = options.signal === undefined
+          ? await this.createStoredSession(preparation.session)
+          : await raceAbortCall(
+            () => this.createStoredSession(preparation.session, options.signal),
+            options.signal,
+            options.sessionId,
+            (abandoned) => { void abandoned?.handle.close().catch(() => {}) },
+          )
+      } catch (error: unknown) {
+        preparation[Symbol.dispose]()
+        throw error
+      }
+      return this.setupAndPublish(
+        ownerCtx,
+        options.sessionId,
+        preparation,
+        options.agentOptions ?? {},
+        options.setup,
+        options.signal,
+        'startup',
+        stored,
+      )
+    })()
     this.ownership.trackWrapper(published)
     return published
   }
@@ -694,16 +798,26 @@ export class AgentLoop extends Service implements AgentFactory {
     setup: AgentSetup | undefined,
     signal: AbortSignal | undefined,
     source: SessionStartSource,
+    stored?: StoredSession,
   ): Promise<AgentHandle> {
     using ownedPreparation = preparation
     const session = ownedPreparation.session
-    const prepared = this.prepare(ownerCtx, id, agentOptions, session, signal)
+    let prepared: PreparedAgent
+    try {
+      prepared = this.prepare(ownerCtx, id, agentOptions, session, signal, stored?.handle)
+    } catch (error: unknown) {
+      await stored?.handle.close().catch(() => {})
+      throw error
+    }
     try {
       const setupCommit = await raceAbort(setup?.(prepared.agent.ctx), prepared.signal, id)
       setupCommit?.commit()
+      await this.appendUnstoredSuffix(stored, session)
       return prepared.publish(source)
     } catch (error: unknown) {
-      await prepared.dispose()
+      // Rollback swallows a disposal rejection (a failing final handle close):
+      // the setup failure is the primary error the caller must see.
+      await prepared.dispose().catch(() => {})
       throw error
     }
   }
@@ -730,9 +844,9 @@ export class AgentLoop extends Service implements AgentFactory {
   ): Promise<AgentHandle> {
     const id = options.resumeSessionId
     const published = (async () => {
-      // The load may outlive its owner: race it against caller cancellation,
-      // owner-fiber unload, and factory teardown so a never-settling backend
-      // cannot pin the identity.
+      // The open and read may outlive their owner: race them against caller
+      // cancellation, owner-fiber unload, and factory teardown so a
+      // never-settling backend cannot pin the identity.
       const ownerAbort = new AbortController()
       const unfollowOwner = ownerCtx.effect(() => () => {
         ownerAbort.abort(new Error(`agent "${id}" setup aborted: owner disposed during setup`))
@@ -742,20 +856,42 @@ export class AgentLoop extends Service implements AgentFactory {
         ownerAbort.signal,
         this.ownership.signal,
       ])
+      let handle: SessionHandle | undefined
+      let stored: StoredSession | undefined
       let preparation: SessionPreparation | undefined
       try {
         try {
-          preparation = await raceAbortCall(
-            () => persistence.prepare(id, fused),
+          // Taking write ownership FIRST excludes a concurrent resume of the
+          // same id (in this process, a live agent's handle holds the claim).
+          handle = await raceAbortCall(
+            () => persistence.open(id, 'write', { signal: fused }),
             fused,
             id,
-            (abandoned) => { abandoned[Symbol.dispose]() },
+            (abandoned) => { void abandoned.close() },
           )
+          // Semantic crash repair is the agent layer's job: persistence hands
+          // back the physically valid log; an interrupted final turn receives
+          // synthetic closers (missing tool errors, step/end, turn/end) that
+          // are appended through the same handle as an ordinary batch.
+          const persisted = await handle.read(0, undefined, { signal: fused })
+          fused.throwIfAborted()
+          const closers = interruptedTurnClosers(persisted)
+          if (closers.length > 0) await handle.append(closers)
+          preparation = SessionPreparation.create(this.runtime.ctx.sessions.prepare(id, {
+            seed: [...persisted, ...closers],
+            meta: structuredClone(handle.header),
+            inheritedEventCount: handle.inheritedEventCount,
+            seedSource: 'persistence',
+          }))
+          stored = { handle, storedCount: persisted.length + closers.length }
+          await this.appendUnstoredSuffix(stored, preparation.session)
         } finally {
           await unfollowOwner()
         }
         ownerCtx.fiber.assertActive()
         if (!this.ownership.isActive()) throw new Error('agent loop is not active')
+        const owned = stored
+        handle = undefined // ownership passes to setupAndPublish/prepare
         return await this.setupAndPublish(
           ownerCtx,
           id,
@@ -764,9 +900,11 @@ export class AgentLoop extends Service implements AgentFactory {
           options.setup,
           options.signal,
           'resume',
+          owned,
         )
       } finally {
         preparation?.[Symbol.dispose]()
+        await handle?.close().catch(() => {})
       }
     })()
     this.ownership.trackWrapper(published)
diff --git a/packages/core/agent-loop/tests/agent-initiator.spec.ts b/packages/core/agent-loop/tests/agent-initiator.spec.ts
index bdee0222c0..5f41c9c004 100644
--- a/packages/core/agent-loop/tests/agent-initiator.spec.ts
+++ b/packages/core/agent-loop/tests/agent-initiator.spec.ts
@@ -130,8 +130,8 @@ describe('AgentLoop initiator scope', () => {
     await ctx.plugin(AgentLoop, { agents: [] })
     ctx.llm.registerAdapter(['mock'], adapter)
 
-    const a = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
-    const b = ctx.agentLoop.create(SessionId('b'), { provider: 'mock', model: 'mock' })
+    const a = await ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
+    const b = await ctx.agentLoop.create(SessionId('b'), { provider: 'mock', model: 'mock' })
     const idleA = waitForIdle(ctx, a)
     const idleB = waitForIdle(ctx, b)
     send(a, 'a')
@@ -154,7 +154,7 @@ describe('AgentLoop initiator scope', () => {
       textResponse('second done'),
     ])
     const { ctx } = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('signal-owner'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('signal-owner'), { provider: 'mock', model: 'mock' })
     let signals: AbortSignal[] = []
     let preStepSignals: AbortSignal[] = []
     const capture = (signal: AbortSignal | undefined): void => {
diff --git a/packages/core/agent-loop/tests/agent.spec.ts b/packages/core/agent-loop/tests/agent.spec.ts
index 9507844521..2ec5bcf01c 100644
--- a/packages/core/agent-loop/tests/agent.spec.ts
+++ b/packages/core/agent-loop/tests/agent.spec.ts
@@ -31,7 +31,7 @@ describe('Agent', () => {
   it('idle inject() durably stages context without opening a turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.inject(createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'p' } }))
 
@@ -43,7 +43,7 @@ describe('Agent', () => {
 
   it('inject() preserves an explicitly empty plugin source', async () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.inject(createUserMessage({ content: [{ type: 'text', text: 'empty plugin source' }], source: { kind: 'plugin', plugin: '' } }))
 
@@ -54,7 +54,7 @@ describe('Agent', () => {
 
   it('emits exact inserted, claimed, and discarded inbox messages', async () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
-    const agent = ctx.agentLoop.create(SessionId('inbox-events'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('inbox-events'), { provider: 'mock', model: 'mock' })
     const inserted: unknown[] = []
     const claimed: unknown[] = []
     const discarded: unknown[] = []
@@ -92,7 +92,7 @@ describe('Agent', () => {
 
   it('idle inject() rejects invalid input before enqueue', async () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     expect(() => {
       agent.inject(createUserMessage({ content: [{ type: 'text', text: 'x', bad: 1n } as never], source: { kind: 'plugin', plugin: 'p' } }))
@@ -103,7 +103,7 @@ describe('Agent', () => {
   it('steer() while idle becomes a woken prompt turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.steer(createUserMessage({ content: [{ type: 'text', text: 'steer idle' }], source: { kind: 'plugin', plugin: 'test' } }))
     await agent.whenIdle()
@@ -114,7 +114,7 @@ describe('Agent', () => {
 
   it('emits one running and idle transition for one completed turn', async () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     const statuses: string[] = []
     ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent) statuses.push(status)
@@ -128,7 +128,7 @@ describe('Agent', () => {
 
   it('whenIdle() resolves immediately without active work', async () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     await agent.whenIdle()
 
@@ -137,7 +137,7 @@ describe('Agent', () => {
 
   it('whenIdle() waits for active work until explicit cancellation', async () => {
     const ctx = await harness(new MockAdapter(['hang']))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'queued')
     let settled = false
@@ -153,7 +153,7 @@ describe('Agent', () => {
   it('contains a throwing status listener on both transitions', async () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/status', ({ status }) => {
       throw new Error(`bad ${status} listener`)
     })
diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts
index 4c148d663d..6a8e085acc 100644
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -60,7 +60,7 @@ describe('Agent.cancel()', () => {
   it('cancel() on an idle agent with nothing queued is a no-op; the next prompt runs (F2 leak guard)', async () => {
     const adapter = new MockAdapter([textResponse('reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // The loop is parked at the idle wait with nothing queued. A cancel here must
     // NOT arm the marker — otherwise the next legitimate prompt would be dropped.
@@ -77,7 +77,7 @@ describe('Agent.cancel()', () => {
   it('cancel({ keepInbox: true }) does not restore work already claimed by a waking send', async () => {
     const adapter = new MockAdapter([textResponse('wake reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({
       content: [{ type: 'text', text: 'preserved' }],
@@ -109,7 +109,7 @@ describe('Agent.cancel()', () => {
       textResponse('wake reply'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('keep-after-abort'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('keep-after-abort'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'active')
     await new Promise(resolve => setTimeout(resolve, 30))
@@ -131,7 +131,7 @@ describe('Agent.cancel()', () => {
   it('cancel({ keepInbox: true }) latches a waking send landing in the abort-to-idle window', async () => {
     const adapter = new MockAdapter(['hang', textResponse('B reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('latch-window'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('latch-window'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'active')
     await new Promise(resolve => setTimeout(resolve, 30))
@@ -156,7 +156,7 @@ describe('Agent.cancel()', () => {
   it('cancel() without keepInbox clears a latched wake alongside the inbox', async () => {
     const adapter = new MockAdapter(['hang', textResponse('C reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('latch-cleared'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('latch-cleared'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'active')
     await new Promise(resolve => setTimeout(resolve, 30))
@@ -178,7 +178,7 @@ describe('Agent.cancel()', () => {
   it('removing the latched wake before convergence suppresses the replay', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('removed-latched-wake'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('removed-latched-wake'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'active')
     await new Promise(resolve => setTimeout(resolve, 30))
@@ -205,7 +205,7 @@ describe('Agent.cancel()', () => {
     // be latched across the whole window, not just the same-tick case.
     const adapter = new MockAdapter(['hang-slow', textResponse('B reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('slow-convergence'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('slow-convergence'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'A')
     await new Promise(resolve => setTimeout(resolve, 30))
@@ -246,7 +246,7 @@ describe('Agent.cancel()', () => {
   it('cancel after waking send closes its synchronously opened turn without a step', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'drop me first')
     send(agent, 'drop me second')
@@ -294,7 +294,7 @@ describe('Agent.cancel()', () => {
   it('a whenIdle() waiter registered BEFORE a pre-step cancel resolves (F1 hang guard)', async () => {
     const adapter = new MockAdapter([textResponse('x')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // This waiter cannot rely on a running→idle transition because cancellation
     // drops the turn before it runs; the skip path must settle it directly.
@@ -313,7 +313,7 @@ describe('Agent.cancel()', () => {
   it('idle-listener cancellation settles its waiter without cancelling later work', async () => {
     const adapter = new MockAdapter([textResponse('first reply'), textResponse('later reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('idle-listener-cancel'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('idle-listener-cancel'), { provider: 'mock', model: 'mock' })
 
     const replacementRegistered = Promise.withResolvers<undefined>()
     let replacementObservation: Promise<{ status: string; requests: number; turns: number }> | undefined
@@ -352,7 +352,7 @@ describe('Agent.cancel()', () => {
       textResponse('wake reply'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('idle-listener-post-cancel-send'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('idle-listener-post-cancel-send'), { provider: 'mock', model: 'mock' })
 
     const replacementRegistered = Promise.withResolvers<undefined>()
     let replacementIdle: Promise<void> | undefined
@@ -386,7 +386,7 @@ describe('Agent.cancel()', () => {
   it('cancel() mid-step aborts the active turn and drops every queued tail item', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -420,7 +420,7 @@ describe('Agent.cancel()', () => {
         return [{ type: 'text', text: 'ran' }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('cancel-after-assistant-message'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('cancel-after-assistant-message'), { provider: 'mock', model: 'mock' })
     const dispose = ctx.on('session/event', (session, event) => {
       if (session === agent.session && event.type === 'assistant/message') {
         agent.cancel({ kind: 'user' })
@@ -462,7 +462,7 @@ describe('Agent.cancel()', () => {
   it('a prompt sent AFTER a cancelled turn settles runs normally (marker reset)', async () => {
     const adapter = new MockAdapter(['hang', textResponse('second reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // First turn hangs; cancel it mid-step.
     send(agent, 'first')
@@ -484,7 +484,7 @@ describe('Agent.cancel()', () => {
   it('cancel mid-stream finalizes the streamed prefix onto the surface', async () => {
     const adapter = new MockAdapter(['hang', textResponse('after')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('partial-finalize'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('partial-finalize'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -523,7 +523,7 @@ describe('Agent.cancel()', () => {
       ],
     }])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('reasoning-finalize'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('reasoning-finalize'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -549,7 +549,7 @@ describe('Agent.cancel()', () => {
       ],
     }])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('tool-call-drop'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('tool-call-drop'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -570,7 +570,7 @@ describe('Agent.cancel()', () => {
       { type: 'finish', reason: { kind: 'error', failure: { message: 'boom', code: 'SERVER_ERROR' } } },
     ]])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('recovery-cancel'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('recovery-cancel'), { provider: 'mock', model: 'mock' })
     // Cancellation lands while agent/request-error is in flight — the window
     // dsh-llm-retry opens when its backoff waits after appending llm/retry.
     ctx.on('agent/request-error', async ({ agent: subject }) => {
@@ -597,7 +597,7 @@ describe('Agent.cancel()', () => {
       textResponse('recovered'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('retry-discards-content'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('retry-discards-content'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/request-error', async () => ({ kind: 'retry' as const }))
 
     send(agent, 'go')
@@ -626,7 +626,7 @@ describe('Agent.cancel()', () => {
       ],
     }])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('nothing-to-finalize'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('nothing-to-finalize'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -639,7 +639,7 @@ describe('Agent.cancel()', () => {
   it('cancel from a synchronous step/start session-event listener drops the step (post-step-start window)', async () => {
     const adapter = new MockAdapter([textResponse('should not stream')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // A step/start session-event listener fires AFTER step/start is appended
     // (and after the pre-step extension point), so cancelling there lands in the SECOND
@@ -705,7 +705,7 @@ describe('Agent.cancel()', () => {
   it('cancel during the stopping window ends the turn aborted and runs no further step', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     const reasons: TurnEndReason[] = []
@@ -734,7 +734,7 @@ describe('Agent.cancel()', () => {
   it('cancel from a synchronous agent/status(running) listener drops the turn (window 2)', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // `agent/status` is synchronous, so cancellation can land before the
     // durable turn-start commit and must drop the reserved work.
@@ -757,7 +757,7 @@ describe('Agent.cancel()', () => {
   it('a running-listener cancellation replays replacement work at convergence', async () => {
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let replaced = false
     const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
@@ -788,7 +788,7 @@ describe('Agent.cancel()', () => {
   it('a prompt queued during pre-step cancellation replays at convergence', async () => {
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'A')
     const idle = agent.whenIdle()
@@ -811,7 +811,7 @@ describe('Agent.cancel()', () => {
   it("cancel clears the turn's steering — it is not re-enqueued as a fresh turn", async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -843,7 +843,7 @@ describe('Agent.cancel()', () => {
       textResponse('wake reply'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('abort-observer-replacement'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('abort-observer-replacement'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'original')
     await expect.poll(() => adapter.requests.length).toBe(1)
@@ -886,7 +886,7 @@ describe('Agent.cancel()', () => {
   it('keeps the first typed cause for an active turn', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('typed-first-wins'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('typed-first-wins'), { provider: 'mock', model: 'mock' })
     const supplied: { kind: 'parent' | 'user' } = { kind: 'parent' }
 
     send(agent, 'go')
@@ -934,7 +934,7 @@ describe('Agent.cancel()', () => {
       ? [toolCallResponse('blocked-tool', 'blocked', {})]
       : [textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId(`cooperative-${stage}`), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId(`cooperative-${stage}`), { provider: 'mock', model: 'mock' })
     const started = Promise.withResolvers<undefined>()
     const blockUntilAbort = async (signal: AbortSignal): Promise<void> => {
       started.resolve(undefined)
diff --git a/packages/core/agent-loop/tests/config-session-id.spec.ts b/packages/core/agent-loop/tests/config-session-id.spec.ts
index a19b5da3f5..038c6e97d3 100644
--- a/packages/core/agent-loop/tests/config-session-id.spec.ts
+++ b/packages/core/agent-loop/tests/config-session-id.spec.ts
@@ -5,10 +5,12 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import LlmRuntime from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId, SessionPreparation } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import type { SessionHandle } from '@deepseek-ai/dsh-session-persistence'
 
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import AgentLoop, { CONFIGURED_AGENT_IDENTITIES_KEY } from '@deepseek-ai/dsh-agent-loop'
@@ -37,6 +39,16 @@ async function makeCoreContext(): Promise<Context> {
   return ctx
 }
 
+/** Read one stored session's physical validated log through a read handle. */
+async function readStoredEvents(ctx: Context, sessionId: SessionId): Promise<readonly SessionEvent[]> {
+  const handle = await ctx.sessionPersistence.open(sessionId, 'read')
+  try {
+    return await handle.read()
+  } finally {
+    await handle.close()
+  }
+}
+
 describe('config-driven session id', () => {
   it('applies launcher identities by configured id without changing unmatched entries', async () => {
     const ctx = await makeCoreContext()
@@ -51,9 +63,11 @@ describe('config-driven session id', () => {
         { id: 'unchanged', sessionId: SessionId('config-unchanged'), model: 'mock' },
       ],
     })
+    await expect.poll(() => ctx.agents.get(SessionId('launcher-fresh'))).toBeDefined()
     expect(ctx.agents.get(SessionId('launcher-fresh'))?.session.id).toBe('launcher-fresh')
     expect(ctx.agents.get(SessionId('launcher-resumed'))).toBeUndefined()
     expect(ctx.agents.get(SessionId('config-resumed'))).toBeUndefined()
+    await expect.poll(() => ctx.agents.get(SessionId('config-unchanged'))).toBeDefined()
     expect(ctx.agents.get(SessionId('config-unchanged'))?.session.id).toBe('config-unchanged')
     await ctx.fiber.dispose()
   })
@@ -72,6 +86,7 @@ describe('config-driven session id', () => {
     await exact.plugin(AgentLoop, {
       agents: [{ id: 'main', sessionId: SessionId('config-exact'), model: 'mock' }],
     })
+    await expect.poll(() => exact.agents.get(SessionId('config-exact'))).toBeDefined()
     expect(exact.agents.get(SessionId('config-exact'))?.session.id).toBe('config-exact')
     await exact.fiber.dispose()
 
@@ -128,8 +143,8 @@ describe('config-driven session id', () => {
     second.followup(createUserMessage({ content: [{ type: 'text', text: 'continue' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, second)
     await ctx.sessions.flush(second.session)
-    const loaded = await ctx.sessionPersistence.load(SessionId('config-exact-reload'))
-    expect(loaded.events.filter(event => event.type === 'turn/start')).toHaveLength(2)
+    const stored = await readStoredEvents(ctx, SessionId('config-exact-reload'))
+    expect(stored.filter(event => event.type === 'turn/start')).toHaveLength(2)
 
     await secondLoop.dispose()
     await ctx.fiber.dispose()
@@ -157,7 +172,7 @@ describe('config-driven session id', () => {
     first.followup(createUserMessage({ content: [{ type: 'text', text: 'persist before replacement' }], source: { kind: 'user' } }))
     await idle
     await ctx.sessions.flush(first.session)
-    expect(JSON.stringify((await ctx.sessionPersistence.inspect(sessionId)).events))
+    expect(JSON.stringify(await readStoredEvents(ctx, sessionId)))
       .toContain('persist before replacement')
 
     const firstDisposal = firstLoop.dispose()
@@ -201,7 +216,7 @@ describe('config-driven session id', () => {
     })
     first.inject(createUserMessage({ content: [{ type: 'text', text: 'persist before cancellation' }], source: { kind: 'plugin', plugin: 'test' } }))
     await ctx.sessions.flush(first.session)
-    expect(JSON.stringify((await ctx.sessionPersistence.inspect(sessionId)).events))
+    expect(JSON.stringify(await readStoredEvents(ctx, sessionId)))
       .toContain('persist before cancellation')
 
     const firstDisposal = firstLoop.dispose()
@@ -217,7 +232,28 @@ describe('config-driven session id', () => {
     await ctx.fiber.dispose()
   })
 
-  it('contains an exact-id persistence lookup failure', async () => {
+  it('contains a configured fresh-create failure without persistence', async () => {
+    const ctx = await makeCoreContext()
+    const failures: unknown[] = []
+    ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+
+    // A relative cwd fails session preparation inside the plain create path
+    // (no backend mounted): the failure is reported, not crashed on.
+    await ctx.plugin(AgentLoop, {
+      agents: [{ id: 'main', model: 'mock', cwd: 'relative' }],
+    })
+
+    await expect.poll(() => failures.length).toBe(1)
+    expect(failures[0]).toBeInstanceOf(Error)
+    expect((failures[0] as Error).message).toMatch(/absolute path/)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('config-driven restore'))
+    expect(ctx.agents.list()).toEqual([])
+    warn.mockRestore()
+    await ctx.fiber.dispose()
+  })
+
+  it('contains an exact-id persistence open failure', async () => {
     const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-failure-'))
     dirs.push(root)
     const ctx = await makeCoreContext()
@@ -231,7 +267,7 @@ describe('config-driven session id', () => {
     ctx.on('agent-loop/config-start-failed', ({ sessionId, error }) => {
       failures.push({ sessionId, error })
     })
-    vi.spyOn(ctx.sessionPersistence, 'list').mockRejectedValue(failure)
+    vi.spyOn(ctx.sessionPersistence, 'open').mockRejectedValue(failure)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
 
     await ctx.plugin(AgentLoop, {
@@ -269,7 +305,7 @@ describe('config-driven session id', () => {
     // oxlint-disable-next-line typescript/prefer-promise-reject-errors
     ctx.on('agent-loop/config-start-failed', () => Promise.reject(unrenderable) as never)
     ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
-    vi.spyOn(ctx.sessionPersistence, 'list').mockRejectedValue(unrenderable)
+    vi.spyOn(ctx.sessionPersistence, 'open').mockRejectedValue(unrenderable)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
 
     await ctx.plugin(AgentLoop, {
@@ -290,15 +326,15 @@ describe('config-driven session id', () => {
   })
 
   it.each(['resolve', 'reject'] as const)(
-    'abandons an exact-id preparation that later %s when AgentLoop disposal starts',
+    'abandons an exact-id open that later %ss when AgentLoop disposal starts',
     async (outcome) => {
       const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-dispose-'))
       dirs.push(root)
       const ctx = await makeCoreContext()
       await ctx.plugin(JsonlSessionPersistence, { root })
-      const preparing = Promise.withResolvers<SessionPreparation>()
-      vi.spyOn(ctx.sessionPersistence, 'prepare').mockReturnValue(preparing.promise)
-      const released = vi.fn()
+      const opening = Promise.withResolvers<SessionHandle>()
+      vi.spyOn(ctx.sessionPersistence, 'open').mockReturnValue(opening.promise)
+      const closed = vi.fn(async () => {})
       const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
       const failures: unknown[] = []
       ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
@@ -308,15 +344,13 @@ describe('config-driven session id', () => {
       })
       await loop.dispose()
       if (outcome === 'resolve') {
-        preparing.resolve(SessionPreparation.create(
-          ctx.sessions.prepare(SessionId('config-exact-dispose')),
-          { release: released },
-        ))
+        opening.resolve({ close: closed } as unknown as SessionHandle)
       } else {
-        preparing.reject(new Error('startup cancelled by teardown'))
+        opening.reject(new Error('startup cancelled by teardown'))
       }
       await Promise.resolve()
-      if (outcome === 'resolve') await expect.poll(() => released).toHaveBeenCalledOnce()
+      // The abandoned handle is closed; the rejected open is silently released.
+      if (outcome === 'resolve') await expect.poll(() => closed).toHaveBeenCalledOnce()
       expect(ctx.agents.get(SessionId('config-exact-dispose'))).toBeUndefined()
       expect(failures).toEqual([])
       expect(warn).not.toHaveBeenCalled()
@@ -359,19 +393,22 @@ describe('config-driven session id', () => {
     await ctx1.plugin(SystemPrompt)
     await ctx1.plugin(ToolRuntime)
     await ctx1.plugin(AgentRegistry)
-    await ctx1.plugin(AgentLoop, { agents: [{ id: SessionId('cfg'), provider: 'mock', model: 'mock' }] })
     await ctx1.plugin(JsonlSessionPersistence, { root })
+    await ctx1.plugin(AgentLoop, { agents: [{ id: SessionId('cfg'), provider: 'mock', model: 'mock' }] })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg')]))
+    await expect.poll(() => ctx1.agents.list().length).toBe(1)
     const a1 = ctx1.agents.list()[0] as Agent
     expect(a1.id).toBe(a1.session.id)
     expect(a1.session.id).toMatch(idPattern)
     expect(ctx1.agents.get(SessionId('cfg'))).toBeUndefined()
     a1.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
     await waitForIdle(ctx1, a1)
+    await ctx1.sessions.flush(a1.session)
+    expect(JSON.stringify(await readStoredEvents(ctx1, a1.session.id))).toContain('cfg')
     await ctx1.fiber.dispose()
 
     // Run 2 over the SAME root: a fresh id means no on-disk collision (a fixed
-    // ${id}-session would crash here with "already has a persisted log").
+    // ${id}-session would crash here with "already exists").
     const ctx2 = new Context()
     await ctx2.plugin(LlmRuntime)
     await ctx2.plugin(SessionStore)
@@ -379,9 +416,10 @@ describe('config-driven session id', () => {
     await ctx2.plugin(SystemPrompt)
     await ctx2.plugin(ToolRuntime)
     await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [{ id: SessionId('cfg'), provider: 'mock', model: 'mock' }] })
     await ctx2.plugin(JsonlSessionPersistence, { root })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: SessionId('cfg'), provider: 'mock', model: 'mock' }] })
     ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg2')]))
+    await expect.poll(() => ctx2.agents.list().length).toBe(1)
     const a2 = ctx2.agents.list()[0] as Agent
     expect(a2.id).toBe(a2.session.id)
     expect(a2.session.id).toMatch(idPattern)
@@ -404,12 +442,13 @@ describe('config-driven session id', () => {
     await ctx1.plugin(SystemPrompt)
     await ctx1.plugin(ToolRuntime)
     await ctx1.plugin(AgentRegistry)
-    await ctx1.plugin(AgentLoop, { agents: [] })
     await ctx1.plugin(JsonlSessionPersistence, { root })
+    await ctx1.plugin(AgentLoop, { agents: [] })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('first')]))
-    const a1 = (await ctx1.agents.create({ sessionId: SessionId('sticky-1') })).agent
-    a1.followup(createUserMessage({ content: [{ type: 'text', text: 'remember me' }], source: { kind: 'user' } }))
-    await waitForIdle(ctx1, a1)
+    const h1 = await ctx1.agents.create({ sessionId: SessionId('sticky-1') })
+    h1.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'remember me' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx1, h1.agent)
+    await h1.dispose()
     await ctx1.fiber.dispose()
 
     // Resume waits for the injected persistence service, so poll until the
@@ -455,9 +494,10 @@ describe('config-driven session id', () => {
 
     // The deferred resume fails (no such session on disk). It must be contained:
     // a warning is logged, no agent is registered, and the app stays up.
-    await new Promise(r => setTimeout(r, 200))
+    await expect.poll(() => warn.mock.calls.some(call =>
+      typeof call[0] === 'string' && call[0].includes('config-driven resume of "does-not-exist" failed'),
+    )).toBe(true)
     expect(ctx.agents.list()).toEqual([])
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('config-driven resume of "does-not-exist" failed'))
     warn.mockRestore()
     await ctx.fiber.dispose()
   })
@@ -471,12 +511,12 @@ describe('startup reporting after factory teardown', () => {
     await ctx.plugin(JsonlSessionPersistence, { root })
     ctx.llm.registerAdapter(['mock'], new MockAdapter([textResponse('x')]))
 
-    // A restore lookup that hangs until after the loop is gone: the eventual
+    // A restore open that hangs until after the loop is gone: the eventual
     // failure lands with ownership inactive and must be silently dropped.
-    const gate = Promise.withResolvers<never>()
-    // The teardown path may drop the pending lookup without awaiting it.
+    const gate = Promise.withResolvers<SessionHandle>()
+    // The teardown path may drop the pending open without awaiting it.
     gate.promise.catch(() => undefined)
-    vi.spyOn(ctx.sessionPersistence, 'list').mockReturnValue(gate.promise)
+    vi.spyOn(ctx.sessionPersistence, 'open').mockReturnValue(gate.promise)
     const failures: unknown[] = []
     ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts
index ab338d3b01..950133c56b 100644
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -68,7 +68,7 @@ describe('assistant replay provider and model fields', () => {
     response[response.length - 1] = { type: 'finish', reason: { kind: 'stop' }, replayState }
     const adapter = new MockAdapter([response])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('replay-state'), { provider: 'mock', model: 'next-model' })
+    const agent = await ctx.agentLoop.create(SessionId('replay-state'), { provider: 'mock', model: 'next-model' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -90,7 +90,7 @@ describe('abort during tool execution ends the turn', () => {
       textResponse('after wake'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-abort-injection'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-abort-injection'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineContentToolFixture({
       name: 'aborter',
       description: '',
@@ -143,7 +143,7 @@ describe('abort during tool execution ends the turn', () => {
       { type: 'finish', reason: { kind: 'tool-calls' } },
     ] satisfies StreamChunk[]])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-later-abort-context'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-later-abort-context'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineContentToolFixture({
       name: 'first',
       description: '',
@@ -192,7 +192,7 @@ describe('abort during tool execution ends the turn', () => {
   it('closes an empty admitted batch as a turn without a step', async () => {
     const adapter = new MockAdapter([textResponse('must not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-empty-batch'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-empty-batch'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/pre-step', ({ agent: subject }, next) => {
       if (subject !== agent) return next()
       return Promise.resolve({ kind: 'enter', messages: [] })
@@ -213,8 +213,8 @@ describe('abort during tool execution ends the turn', () => {
     const ctx = await harness(adapter)
     const started = Promise.withResolvers<undefined>()
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('a-dispose-injection'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('a-dispose-injection'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     ctx.tools.register(defineContentToolFixture({
       name: 'waiter',
@@ -269,7 +269,7 @@ describe('abort during tool execution ends the turn', () => {
       textResponse('later turn'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineContentToolFixture({
       name: 'aborter',
       description: '',
@@ -323,7 +323,7 @@ describe('steering from late extension points is never stranded', () => {
       textResponse('continued because of steering'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steeredOnce = false
     ctx.on('agent/turn-stopping', () => {
@@ -347,7 +347,7 @@ describe('plugin exceptions are contained', () => {
   it('a throwing agent/turn-stopping listener ends the turn with an error, loop survives', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/turn-stopping', async () => {
@@ -378,8 +378,8 @@ describe('disposal leaves the two-state status contract balanced', () => {
     const ctx = await harness(adapter)
 
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const statuses: string[] = []
@@ -409,8 +409,8 @@ describe('disposal leaves the two-state status contract balanced', () => {
     const ctx = await harness(adapter)
 
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     ctx.on('agent/status', ({ status }) => {
@@ -441,7 +441,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('an agent without a model fails the step with a clear error (not NO_ADAPTER for "default")', async () => {
     const adapter = new MockAdapter([textResponse('never')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), {}) // no model
+    const agent = await ctx.agentLoop.create(SessionId('a1'), {}) // no model
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -457,7 +457,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('the agent/request waterfall can supply the model for a model-less agent', async () => {
     const adapter = new MockAdapter([textResponse('routed')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), {}) // no model — router plugin decides
+    const agent = await ctx.agentLoop.create(SessionId('a1'), {}) // no model — router plugin decides
 
     ctx.on('agent/request', async (_payload, next) => {
       return { ...await next(), provider: 'mock', model: 'mock' }
@@ -472,7 +472,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('durable inbox splices carry exact messages and the claimed steer preserves its source', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineContentToolFixture({
       name: 'noop',
       description: '',
@@ -523,7 +523,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
       createUserMessage({ content: [{ type: 'text', text: 'first steer' }], source: { kind: 'user' } }),
       createUserMessage({ content: [{ type: 'text', text: 'second steer' }], source: { kind: 'user' } }),
     ]
-    const agent = ctx.agentLoop.create(SessionId('claim-order'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('claim-order'), { provider: 'mock', model: 'mock' })
     let execution = 0
     ctx.tools.register(defineContentToolFixture({
       name: 'steer_next',
@@ -567,7 +567,7 @@ describe('turn numbering continues across seeded sessions', () => {
   it('a forked agent continues turn numbers after the seed log', async () => {
     const first = new MockAdapter([textResponse('turn one')])
     const ctx = await harness(first)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'first')
     await waitForIdle(ctx, agent)
 
@@ -634,7 +634,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([errorStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-finish-error'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-finish-error'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     const errors: unknown[] = []
@@ -665,7 +665,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([abortedStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-finish-aborted'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-finish-aborted'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -683,7 +683,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([errorStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-finish-error-nocode'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-finish-error-nocode'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -699,7 +699,7 @@ describe('step boundary publication order', () => {
   it('the step/start event is in session.snapshotEvents() when its session/event listener fires', async () => {
     const adapter = new MockAdapter([textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-step-order'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-step-order'), { provider: 'mock', model: 'mock' })
 
     const observed: { turn: number; step: number; lastEventType: string | undefined; sawStepStart: boolean }[] = []
     ctx.on('session/event', (subject, event) => {
@@ -754,7 +754,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing step/start observer cannot change a successful turn', async () => {
     const adapter = new MockAdapter([textResponse('request completed')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-stepstart'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-stepstart'), { provider: 'mock', model: 'mock' })
 
     // Session owns post-commit containment. The loop sees a successful append,
     // runs the request, and balances the ordinary step and turn boundaries.
@@ -785,7 +785,7 @@ describe('turn and step boundary recovery', () => {
   it('a pre-commit turn/start rejection leaves no durable turn state', async () => {
     const adapter = new MockAdapter([])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-turnstart-veto'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-turnstart-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -813,7 +813,7 @@ describe('turn and step boundary recovery', () => {
   it('a pre-commit step/start validation failure does not invent a step boundary', async () => {
     const adapter = new MockAdapter([textResponse('never reached')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-stepstart-veto'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-stepstart-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -842,7 +842,7 @@ describe('turn and step boundary recovery', () => {
   it('a step/end validation failure surfaces the resulting open-step invariant', async () => {
     const adapter = new MockAdapter([textResponse('completed before close validation')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-stepend-veto'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-stepend-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -879,7 +879,7 @@ describe('turn and step boundary recovery', () => {
     const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', failure: { message: 'provider 500', code: 'SERVER' } } }]
     const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-errorlistener'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-errorlistener'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('agent/error', () => { if (!threw) { threw = true; throw new Error('boom error-listener') } })
@@ -915,8 +915,8 @@ describe('turn and step boundary recovery', () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await balancedHarness(adapter)
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('a-dispose'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('a-dispose'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -941,8 +941,8 @@ describe('turn and step boundary recovery', () => {
     const adapter = new MockAdapter([textResponse('never reached')])
     const ctx = await balancedHarness(adapter)
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('a-prestep-dispose-throw'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('a-prestep-dispose-throw'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     let threw = false
@@ -972,7 +972,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing turn/start observer cannot starve the loop or later turns', async () => {
     const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-preturn'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-preturn'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_session, event) => {
@@ -1005,7 +1005,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing step/end observer cannot rewrite the turn outcome', async () => {
     const adapter = new MockAdapter([textResponse('all good'), textResponse('turn 2 ok')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-stepend-throw'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-stepend-throw'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -1046,7 +1046,7 @@ describe('turn and step boundary recovery', () => {
     const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', failure: { message: 'provider 500', code: 'SERVER' } } }]
     const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-stependthrow'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-stependthrow'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -1080,7 +1080,7 @@ describe('turn and step boundary recovery', () => {
     // boundary stays authoritative and the loop continues normally.
     const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-turnendappend'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-turnendappend'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -1126,7 +1126,7 @@ describe('tool result call identity', () => {
       return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: 'ok' }] })
     }, { prepend: true })
 
-    const agent = ctx.agentLoop.create(SessionId('a-callid'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-callid'), { provider: 'mock', model: 'mock' })
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
 
@@ -1176,8 +1176,8 @@ describe('disposal and cancellation during pre-step assembly', () => {
     })
 
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('a-dispose-assemble'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('a-dispose-assemble'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1226,8 +1226,8 @@ describe('disposal and cancellation during pre-step assembly', () => {
     })
 
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('a-cancel-assemble'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('a-cancel-assemble'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1277,8 +1277,8 @@ describe('disposal and cancellation during pre-step assembly', () => {
     })
 
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('a-dispose-prestep'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('a-dispose-prestep'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1324,8 +1324,8 @@ describe('disposal and cancellation during pre-step assembly', () => {
     })
 
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('a-cancel-prestep'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('a-cancel-prestep'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1373,8 +1373,8 @@ describe('disposal and cancellation during pre-step assembly', () => {
     })
 
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('a-dispose-no-leak'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('a-dispose-no-leak'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     send(agent, 'go')
diff --git a/packages/core/agent-loop/tests/coverage-edges.spec.ts b/packages/core/agent-loop/tests/coverage-edges.spec.ts
index 6c9ecc2020..f8ea231143 100644
--- a/packages/core/agent-loop/tests/coverage-edges.spec.ts
+++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts
@@ -63,7 +63,7 @@ describe('tool JSON parse', () => {
         return [{ type: 'text', text: typeof args === 'string' ? `raw: ${args}` : JSON.stringify(args) }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
@@ -96,7 +96,7 @@ describe('tool JSON parse', () => {
         return [{ type: 'text', text: 'ran with empty args' }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
@@ -109,7 +109,7 @@ describe('thrown-value propagation', () => {
   it('preserves non-Error throws from pre-commit dispatch validation', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
@@ -142,7 +142,7 @@ describe('thrown-value propagation', () => {
   it('preserves non-Error throws from the agent/request waterfall', async () => {
     const adapter = new MockAdapter([textResponse('irrelevant')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/request', async (_payload, next) => {
@@ -166,7 +166,7 @@ describe('durable error rendering', () => {
   it('renders a coded error thrown from a plugin', async () => {
     const adapter = new MockAdapter([textResponse('turn 1')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/request', async (_payload, next) => {
@@ -196,8 +196,8 @@ describe('disposed vs aborted branching', () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -223,7 +223,7 @@ describe('structured tool error propagation (the runtime-validation Agent Note,
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineContentToolFixture({
       name: 'boom',
       description: 'always fails',
@@ -251,7 +251,7 @@ describe('request-error action edges', () => {
       textResponse('never used'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('retry-after-cancel'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('retry-after-cancel'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/request-error', async ({ agent: subject }) => {
       subject.cancel({ kind: 'user' })
       return { kind: 'retry' }
@@ -272,7 +272,7 @@ describe('request-error action edges', () => {
       () => { throw new LlmError('busy', 'RATE_LIMIT') },
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('retry-raced'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('retry-raced'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/request-error', async ({ agent: subject, signal }, next) => {
       await next()
       subject.cancel({ kind: 'user' })
@@ -293,7 +293,7 @@ describe('stream failure edges', () => {
   it('rethrows a mid-stream throw that carries no adapter failure facts', async () => {
     const adapter = new MockAdapter([textResponse('will be vetoed')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('stream-no-facts'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('stream-no-facts'), { provider: 'mock', model: 'mock' })
     let recoveries = 0
     ctx.on('agent/request-error', async () => { recoveries += 1 })
     // A pre-commit chunk veto throws INSIDE the stream-consumption try, but it
@@ -322,7 +322,7 @@ describe('post-turn continuation edges', () => {
   it('whenIdle resolves for a waiter whose awaited run fails', async () => {
     const adapter = new MockAdapter([textResponse('unused')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('whenidle-reject'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('whenidle-reject'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -343,7 +343,7 @@ describe('persistent step-close rejection', () => {
   it('still publishes the terminal status when both step-close attempts are vetoed', async () => {
     const adapter = new MockAdapter([textResponse('will not close')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('stepend-double-veto'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('stepend-double-veto'), { provider: 'mock', model: 'mock' })
     // Persistently reject step/end: the catch's own close attempt fails too,
     // and the contained failure must not strand status at running.
     ctx.on('internal/dispatch', (_mode, name, args) => {
@@ -370,7 +370,7 @@ describe('tool result meta persistence', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('tool-meta'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('tool-meta'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'meta-tool',
       description: 'carries presentation meta',
@@ -397,7 +397,7 @@ describe('turn close failure containment', () => {
   it('a rejected turn/end append is contained: warn + agent/error, no retry', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('turnend-veto'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('turnend-veto'), { provider: 'mock', model: 'mock' })
     let vetoed = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -427,7 +427,7 @@ describe('recovery without a retry action', () => {
       () => { throw new LlmError('down', 'SERVICE_UNAVAILABLE') },
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('recovery-no-retry'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('recovery-no-retry'), { provider: 'mock', model: 'mock' })
     let recoveries = 0
     ctx.on('agent/request-error', async () => { recoveries += 1 })
 
@@ -456,7 +456,7 @@ describe('unrenderable failure settlement', () => {
       },
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('unrenderable'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('unrenderable'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await agent.whenIdle()
@@ -474,7 +474,7 @@ describe('unrenderable failure settlement', () => {
 describe('driver bookkeeping edges', () => {
   it('rejects a direct turn invocation without a driver reservation', async () => {
     const ctx = await harness(new MockAdapter([]))
-    const agent = ctx.agentLoop.create(SessionId('turn-without-reservation'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('turn-without-reservation'), { provider: 'mock', model: 'mock' })
 
     await expect((agent as unknown as { turn(): Promise<boolean> }).turn())
       .rejects.toThrow('turn without driver reservation')
@@ -484,7 +484,7 @@ describe('driver bookkeeping edges', () => {
   it('closes an entered turn as blocked when its next step is rejected', async () => {
     const adapter = new MockAdapter([textResponse('first step')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('reject-next-step'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('reject-next-step'), { provider: 'mock', model: 'mock' })
     let proposals = 0
     ctx.on('agent/pre-step', async (_payload, next) => {
       proposals += 1
@@ -518,7 +518,7 @@ describe('driver bookkeeping edges', () => {
       ] satisfies StreamChunk[],
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('finish-after-close'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('finish-after-close'), { provider: 'mock', model: 'mock' })
     void LlmError
 
     send(agent, 'go')
diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts
index d836d6e8f9..8ef5929522 100644
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -64,7 +64,7 @@ describe('agent/pre-step', () => {
   it('enter (default via next) records the user/message unchanged', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const seen: string[] = []
     ctx.on('agent/pre-step', async ({ messages }, next) => {
@@ -92,7 +92,7 @@ describe('agent/pre-step', () => {
       parameters: { text: { type: 'string', required: true } },
       execute: async ({ text }) => [{ type: 'text', text }],
     }))
-    const agent = ctx.agentLoop.create(SessionId('prompt-coordinates'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('prompt-coordinates'), { provider: 'mock', model: 'mock' })
     const seen: Array<{ turn: number; step: number; messages: number }> = []
     ctx.on('agent/pre-step', async ({ messages, turn, step }, next) => {
       seen.push({ turn, step, messages: messages.length })
@@ -111,7 +111,7 @@ describe('agent/pre-step', () => {
   it('publishes frozen input without replacing its identity', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('owned-input'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('owned-input'), { provider: 'mock', model: 'mock' })
     const entered = Promise.withResolvers<undefined>()
     const decision = Promise.withResolvers<PreStepDecision>()
     const observed: UserMessage[] = []
@@ -161,7 +161,7 @@ describe('agent/pre-step', () => {
   it('enter with content rewrites the prompt before it is recorded', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/pre-step', async ({ messages }): Promise<PreStepDecision> =>
       ({
@@ -182,7 +182,7 @@ describe('agent/pre-step', () => {
   it('enter with additional messages records separately sourced context in the turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/pre-step', async ({ messages }): Promise<PreStepDecision> =>
       ({
@@ -209,7 +209,7 @@ describe('agent/pre-step', () => {
   it('does not open another step when a completed turn rewrites pending input to empty', async () => {
     const adapter = new MockAdapter([textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('empty-completed-continuation'), {
+    const agent = await ctx.agentLoop.create(SessionId('empty-completed-continuation'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -236,7 +236,7 @@ describe('agent/pre-step', () => {
   it('reject closes the claimed prompt turn without a step or model call', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/pre-step', async (): Promise<PreStepDecision> => ({ kind: 'reject' }))
 
@@ -259,7 +259,7 @@ describe('agent/pre-step', () => {
   it('stages inject and steer during pre-step for the entered turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('pre-step-outbox'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('pre-step-outbox'), { provider: 'mock', model: 'mock' })
     const entered = Promise.withResolvers<undefined>()
     const decision = Promise.withResolvers<PreStepDecision>()
     let claimed: UserMessage[] = []
@@ -320,7 +320,7 @@ describe('agent/pre-step', () => {
   it('preserves input staged after the blocked batch was claimed', async () => {
     const adapter = new MockAdapter([textResponse('retried')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('blocked-pre-step-outbox'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('blocked-pre-step-outbox'), { provider: 'mock', model: 'mock' })
     const entered = Promise.withResolvers<undefined>()
     const decision = Promise.withResolvers<PreStepDecision>()
     const disposeBlock = ctx.on('agent/pre-step', async () => {
@@ -370,7 +370,7 @@ describe('agent/pre-step', () => {
       textResponse('wake reply'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('rejected-pre-step-order'), {
+    const agent = await ctx.agentLoop.create(SessionId('rejected-pre-step-order'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -425,7 +425,7 @@ describe('agent/pre-step', () => {
   it('preserves context-only injection staged after pre-step began', async () => {
     const adapter = new MockAdapter([textResponse('continued')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('rejected-pre-step-context'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('rejected-pre-step-context'), { provider: 'mock', model: 'mock' })
     const entered = Promise.withResolvers<undefined>()
     const decision = Promise.withResolvers<PreStepDecision>()
     const disposeBlock = ctx.on('agent/pre-step', async () => {
@@ -460,7 +460,7 @@ describe('agent/pre-step', () => {
   it('leaves inbox state unchanged when its durable append fails', async () => {
     const adapter = new MockAdapter([])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('rejected-pre-step-append-failure'), {
+    const agent = await ctx.agentLoop.create(SessionId('rejected-pre-step-append-failure'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -482,7 +482,7 @@ describe('agent/pre-step', () => {
       textResponse('wake reply'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/pre-step', async ({ messages }, next): Promise<PreStepDecision> => {
       const text = messages.flatMap(message => message.content)
@@ -518,7 +518,7 @@ describe('agent/pre-step', () => {
   it('a throwing pre-step listener reports the driver error and retains adjacent work', async () => {
     const adapter = new MockAdapter([textResponse('after')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('agent/pre-step', async ({ messages }) => {
@@ -563,7 +563,7 @@ describe('agent/session-start', () => {
     const sources: SessionStartSource[] = []
     ctx.on('agent/session-start', ({ source }) => void sources.push(source))
 
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     // fires synchronously at create, before any turn
     expect(sources).toEqual(['startup'])
     expect(events(agent).some(e => e.type === 'turn/start')).toBe(false)
@@ -582,7 +582,7 @@ describe('agent/session-start', () => {
       agent.inject(createUserMessage({ content: [{ type: 'text', text: 'session preamble' }], source: { kind: 'plugin', plugin: 'test' } }))
     })
 
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
@@ -600,7 +600,7 @@ describe('agent/session-start', () => {
     ctx.on('agent/session-start', () => { throw new Error('session-start hook broke') })
 
     // create must not throw — the listener error is contained/logged
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     expect(agent.id).toBe(SessionId('a1'))
 
     // and the agent still runs
@@ -627,7 +627,7 @@ describe('tool additionalContexts buffering across a step', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // Each call attaches one context naming itself.
     ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> =>
@@ -674,7 +674,7 @@ describe('tool additionalContexts buffering across a step', () => {
         return [{ type: 'text', text: 'outer result' }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -700,7 +700,7 @@ describe('tools/pre-execute gate (native-plugin permission pattern, end-to-end t
       name: 'danger', description: 'danger', parameters: {},
       async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
       if (exec.name === 'danger') return { kind: 'deny', reason: 'blocked dangerous tool' }
@@ -764,7 +764,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'please echo hi')
     await waitForIdle(ctx, agent)
@@ -787,7 +787,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
     await ctx.plugin(NativeGuard)
-    const agent = ctx.agentLoop.create(SessionId('a2'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a2'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -806,7 +806,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
     await fiber.dispose()
 
     // After disposal, a destructive prompt is NOT blocked (the listener is gone).
-    const agent = ctx.agentLoop.create(SessionId('a3'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a3'), { provider: 'mock', model: 'mock' })
     send(agent, 'run rm -rf /')
     await waitForIdle(ctx, agent)
     // the prompt ran (not rejected) — proving the pre-step listener was disposed
diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts
index d3235a3970..b8e155e446 100644
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -56,10 +56,10 @@ describe('agent loop', () => {
     'rejects invalid AgentOptions.maxTokens %s before publication',
     async (maxTokens) => {
       const ctx = await harness(new MockAdapter([]))
-      expect(() => ctx.agentLoop.create(
+      await expect(ctx.agentLoop.create(
         SessionId('invalid-max-tokens'),
         { provider: 'mock', model: 'mock', maxTokens },
-      )).toThrow('agent maxTokens must be a positive safe integer')
+      )).rejects.toThrow('agent maxTokens must be a positive safe integer')
       expect(ctx.agents.list()).toEqual([])
       expect(ctx.sessions.list()).toEqual([])
     },
@@ -68,7 +68,7 @@ describe('agent loop', () => {
   it('seeds a valid AgentOptions.maxTokens into the first model request', async () => {
     const adapter = new MockAdapter([textResponse('bounded')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(
+    const agent = await ctx.agentLoop.create(
       SessionId('valid-max-tokens'),
       { provider: 'mock', model: 'mock', maxTokens: 256 },
     )
@@ -86,7 +86,7 @@ describe('agent loop', () => {
       defaultEffort: effort,
     })
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(
+    const agent = await ctx.agentLoop.create(
       SessionId('configured-reasoning-effort'),
       { provider: 'mock', model: 'mock', reasoningEffort: effort },
     )
@@ -110,7 +110,7 @@ describe('agent loop', () => {
   it('cancels queued wakeup work together with an active maintenance task', async () => {
     const adapter = new MockAdapter([textResponse('park reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('cancel-maintenance-wakeup'), {
+    const agent = await ctx.agentLoop.create(SessionId('cancel-maintenance-wakeup'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -138,10 +138,31 @@ describe('agent loop', () => {
     expect(adapter.requests).toHaveLength(1)
   })
 
+  it('rejects a second maintenance task while one is active', async () => {
+    const ctx = await harness(new MockAdapter([]))
+    const agent = await ctx.agentLoop.create(SessionId('maintenance-busy'), {
+      provider: 'mock',
+      model: 'mock',
+    })
+    const started = Promise.withResolvers<undefined>()
+    const finish = Promise.withResolvers<undefined>()
+    const maintenance = agent.runMaintenance(async () => {
+      started.resolve(undefined)
+      await finish.promise
+    })
+    await started.promise
+
+    expect(() => agent.runMaintenance(async () => {})).toThrow(/already has active work/)
+
+    finish.resolve(undefined)
+    await maintenance
+    await agent.whenIdle()
+  })
+
   it('replays a wake latched behind maintenance at convergence', async () => {
     const adapter = new MockAdapter([textResponse('wake reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('maintenance-wake-replay'), {
+    const agent = await ctx.agentLoop.create(SessionId('maintenance-wake-replay'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -165,7 +186,7 @@ describe('agent loop', () => {
   it('suppresses the replay when a latched maintenance wake is removed', async () => {
     const adapter = new MockAdapter([])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('maintenance-wake-removed'), {
+    const agent = await ctx.agentLoop.create(SessionId('maintenance-wake-removed'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -192,7 +213,7 @@ describe('agent loop', () => {
   it('runs a simple turn: queued message → model → idle, with ordered events', async () => {
     const adapter = new MockAdapter([textResponse('hello there')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // All boundaries — turn and step — are durable session events on the
     // session/event feed (no agent/* mirror). Record them in fire order to
@@ -239,7 +260,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: `echo: ${args.text}` }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use the tool')
     await waitForIdle(ctx, agent)
@@ -276,7 +297,7 @@ describe('agent loop', () => {
         return []
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -310,7 +331,7 @@ describe('agent loop', () => {
     ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -358,7 +379,7 @@ describe('agent loop', () => {
       const config = await next()
       return { ...config, provider: 'mock', model: 'mock' }
     })
-    const agent = ctx.agentLoop.create(SessionId('a-late-model'), {})
+    const agent = await ctx.agentLoop.create(SessionId('a-late-model'), {})
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -375,7 +396,7 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     ctx.on('system-prompt/assemble', async () => ({ sections: [], contexts: [], tools: [], variables: {} }))
-    const agent = ctx.agentLoop.create(SessionId('a-no-system'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-no-system'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -395,7 +416,7 @@ describe('agent loop', () => {
     const ctx = await harness(adapter)
     let mode = 'read-only'
     const dispose = ctx.systemPrompt.context({ name: 'policy', order: 0, text: () => `Mode: ${mode}.` })
-    const agent = ctx.agentLoop.create(SessionId('a-runtime-context'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-runtime-context'), { provider: 'mock', model: 'mock' })
     const contextEvents = () => agent.session.snapshotEvents().flatMap(event =>
       event.type === 'user/message'
         && event.data.source.kind === 'plugin'
@@ -445,7 +466,7 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
     ctx.systemPrompt.context({ name: 'policy', order: 0, text: 'Mode: read-only.' })
-    const agent = ctx.agentLoop.create(SessionId('a-runtime-context-compacted'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-runtime-context-compacted'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -480,7 +501,7 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
     const dispose = ctx.systemPrompt.context({ name: 'policy', order: 0, text: 'Mode: read-only.' })
-    const agent = ctx.agentLoop.create(SessionId('a-runtime-context-compacted-clear'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-runtime-context-compacted-clear'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -512,7 +533,7 @@ describe('agent loop', () => {
   it('does not clear runtime context after an unrelated replacement', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a-runtime-context-unrelated-compaction'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-runtime-context-unrelated-compaction'), { provider: 'mock', model: 'mock' })
     const original = agent.session.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'old context' }],
       source: { kind: 'plugin', plugin: 'test-context' },
@@ -536,7 +557,7 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     ctx.systemPrompt.context({ name: 'policy', order: 0, text: 'Mode: read-only.' })
-    const agent = ctx.agentLoop.create(SessionId('a-runtime-context-malformed'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a-runtime-context-malformed'), { provider: 'mock', model: 'mock' })
     agent.session.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'broken' }, { type: 'text', text: 'snapshot' }],
       source: { kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' },
@@ -560,7 +581,7 @@ describe('agent loop', () => {
   it('records raw chunks for replay as assistant/chunk session events', async () => {
     const adapter = new MockAdapter([textResponse('abc')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -584,7 +605,7 @@ describe('agent loop', () => {
     ])
     const ctx = await harness(adapter)
 
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineContentToolFixture({
       name: 'slow',
       description: '',
@@ -618,7 +639,7 @@ describe('agent loop', () => {
   it('starts idle steering synchronously and enters later steering at the next step', async () => {
     const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const idle = waitForIdle(ctx, agent)
     agent.steer(createUserMessage({ content: [{ type: 'text', text: 'first idle steer' }], source: { kind: 'user' } }))
@@ -643,7 +664,7 @@ describe('agent loop', () => {
   it('stops after a throwing pre-step listener and retains later steering until a wakeup', async () => {
     const adapter = new MockAdapter([textResponse('recovered')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('failed-steering'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('failed-steering'), { provider: 'mock', model: 'mock' })
     let fail = true
     ctx.on('agent/pre-step', ({ agent: subject }, next) => {
       if (subject !== agent || !fail) return next()
@@ -671,7 +692,7 @@ describe('agent loop', () => {
   it('inject() while idle durably stages context without opening a turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.inject(createUserMessage({ content: [{ type: 'text', text: 'file changed: a.ts' }], source: { kind: 'plugin', plugin: 'watcher' } }))
     expect(agent.status).toBe('idle')
@@ -700,7 +721,7 @@ describe('agent loop', () => {
   it('inject() persists structured context content verbatim with durable source', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('raw-context'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('raw-context'), { provider: 'mock', model: 'mock' })
     const text = '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>'
     agent.inject(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'plugin', plugin: 'agent-instructions' } }))
     send(agent, 'go')
@@ -720,7 +741,7 @@ describe('agent loop', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let visibleDuringTool = false
     ctx.tools.register(defineContentToolFixture({
       name: 'noticer',
@@ -775,7 +796,7 @@ describe('agent loop', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('invalid-context'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('invalid-context'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineContentToolFixture({
       name: 'invalid-injector',
       description: 'attempts an invalid context injection',
@@ -801,7 +822,7 @@ describe('agent loop', () => {
       textResponse('step 3'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
@@ -829,7 +850,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -845,7 +866,7 @@ describe('agent loop', () => {
       textResponse('next turn reply'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineContentToolFixture({
       name: 'finalize',
       description: '',
@@ -875,7 +896,7 @@ describe('agent loop', () => {
   it('agent/request waterfall switches models by returning a replacement config; the switch is logged', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/request', async (_payload, next) => {
       const config = await next()
@@ -905,7 +926,7 @@ describe('agent loop', () => {
       name: 'echo', description: 'echo', parameters: {},
       async execute() { return [{ type: 'text', text: 'echoed' }] },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const fires: { turn: number; step: number; signal: AbortSignal }[] = []
     ctx.on('agent/pre-step', ({ agent: subject, turn, step, signal }, next) => {
@@ -926,7 +947,7 @@ describe('agent loop', () => {
   it('agent/pre-step fires before its step boundary opens and before the request', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let boundaryOpen = true
     ctx.on('agent/pre-step', ({ agent: subject }, next) => {
@@ -944,7 +965,7 @@ describe('agent loop', () => {
   it('a throwing agent/pre-step listener fails the proposal, not the loop', async () => {
     const adapter = new MockAdapter([textResponse('second turn ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let throwOnce = true
     ctx.on('agent/pre-step', (_payload, next) => {
@@ -976,7 +997,7 @@ describe('agent loop', () => {
   it('cancel() mid-stream ends the turn with reason aborted', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -996,7 +1017,7 @@ describe('agent loop', () => {
     // turn stops by default and ends max-tokens, not completed.
     const adapter = new MockAdapter([maxTokensResponse('truncat')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -1019,7 +1040,7 @@ describe('agent loop', () => {
       textResponse('second half'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
@@ -1069,7 +1090,7 @@ describe('agent loop', () => {
     // stop. The per-turn reason must be independent — turn 2 ends completed.
     const adapter = new MockAdapter([maxTokensResponse('cut'), textResponse('clean')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -1102,7 +1123,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: 'should not run' }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -1152,7 +1173,7 @@ describe('agent loop', () => {
       parameters: { text: { type: 'string' } },
       async execute() { return [{ type: 'text', text: 'should not run' }] },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -1186,7 +1207,7 @@ describe('agent loop', () => {
     // a durable successful-call boundary for replay consumers.
     const adapter = new MockAdapter([[{ type: 'finish', reason: { kind: 'stop' } }]])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -1230,7 +1251,7 @@ describe('agent loop', () => {
       },
     ], textResponse('continued')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -1293,7 +1314,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let threw = false
     // Post-commit session observers cannot control the loop. The tool call still
     // drives the second model request, and the turn completes normally.
@@ -1312,7 +1333,7 @@ describe('agent loop', () => {
   it('contains a reentrant send attempted during durable inbox publication', async () => {
     const adapter = new MockAdapter([textResponse('first')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let nested = false
     ctx.on('session/event', (session, event) => {
@@ -1337,7 +1358,7 @@ describe('agent loop', () => {
   it('preserves independent turn sources across an adjacent microtask send', async () => {
     const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const idle = waitForIdle(ctx, agent)
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'user message' }], source: { kind: 'user' } }))
@@ -1359,7 +1380,7 @@ describe('agent loop', () => {
   it('keeps a session-listener send after dequeue in the following turn', async () => {
     const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const turns: number[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
@@ -1395,7 +1416,7 @@ describe('agent loop', () => {
       textResponse('second'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agentRef.current = agent
 
     const idle = waitForIdle(ctx, agent)
@@ -1415,7 +1436,7 @@ describe('agent loop', () => {
   it('records normalized model errors on the turn boundary', async () => {
     const adapter = new MockAdapter([]) // script exhausted → throws
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const errors: unknown[] = []
     const reasons: TurnEndReason[] = []
@@ -1444,8 +1465,8 @@ describe('agent loop', () => {
     const ctx = await harness(adapter)
 
     let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      agent = await inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     expect(ctx.agents.get(SessionId('scoped'))).toBe(agent)
@@ -1522,7 +1543,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'run')
     await waitForIdle(ctx, agent)
 
diff --git a/packages/core/agent-loop/tests/properties.spec.ts b/packages/core/agent-loop/tests/properties.spec.ts
index 1dc37ffc14..68e170f27e 100644
--- a/packages/core/agent-loop/tests/properties.spec.ts
+++ b/packages/core/agent-loop/tests/properties.spec.ts
@@ -113,7 +113,7 @@ describe('agent loop scheduling properties', () => {
       async (texts) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
+          const agent = await ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
           const { seen: trace } = recordStatus(ctx, agent)
           const idle = nextIdle(ctx, agent)
           // Send all in one synchronous tick: they queue before the loop wakes.
@@ -141,7 +141,7 @@ describe('agent loop scheduling properties', () => {
       async (texts) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
+          const agent = await ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
           for (const text of texts) {
             const idle = nextIdle(ctx, agent)
             agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }))
@@ -166,7 +166,7 @@ describe('agent loop scheduling properties', () => {
       async (steps) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
+          const agent = await ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
           // Capture before each send; the last waiter covers the final turn, and
           // awaiting an already-settled earlier waiter is harmless.
           let lastIdle: Promise<void> | undefined
diff --git a/packages/core/agent-loop/tests/request-cache.e2e.ts b/packages/core/agent-loop/tests/request-cache.e2e.ts
index e8f0bab180..960dccf608 100644
--- a/packages/core/agent-loop/tests/request-cache.e2e.ts
+++ b/packages/core/agent-loop/tests/request-cache.e2e.ts
@@ -73,7 +73,7 @@ function waitForIdle(context: Context, agent: Agent): Promise<void> {
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('log-derived request cache hits (real API)', () => {
   it('every request after the first hits the provider prefix cache', async () => {
     ctx = await loopHarness()
-    const agent = ctx.agentLoop.create(SessionId('cache-e2e'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    const agent = await ctx.agentLoop.create(SessionId('cache-e2e'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
 
     // Turn 1: forces a tool call → at least two steps (two model requests).
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'Look up the key "deploy-color" with the lookup tool and tell me the value.' }], source: { kind: 'user' } }))
diff --git a/packages/core/agent-loop/tests/request-error.spec.ts b/packages/core/agent-loop/tests/request-error.spec.ts
index 17af91a06e..616a817082 100644
--- a/packages/core/agent-loop/tests/request-error.spec.ts
+++ b/packages/core/agent-loop/tests/request-error.spec.ts
@@ -33,7 +33,7 @@ describe('agent/request-error', () => {
   it('does not offer middleware failures to request recovery', async () => {
     const adapter = new MockAdapter([textResponse('unused')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('request-error-narrow'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('request-error-narrow'), { provider: 'mock', model: 'mock' })
     let recoveries = 0
     ctx.on('agent/request', () => {
       throw new LlmError('middleware failed', 'MIDDLEWARE')
@@ -56,7 +56,7 @@ describe('agent/request-error', () => {
       textResponse('ok'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('request-error-retry'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('request-error-retry'), { provider: 'mock', model: 'mock' })
     const seen: {
       turn: number
       step: number
@@ -105,7 +105,7 @@ describe('agent/request-error', () => {
   it('lets cancellation win over a retry action', async () => {
     const adapter = new MockAdapter([fail('busy', 'RATE_LIMIT'), textResponse('unused')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('request-error-cancel'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('request-error-cancel'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/request-error', async ({ agent: subject }) => {
       subject.cancel({ kind: 'user' })
       return { kind: 'retry' }
@@ -125,7 +125,7 @@ describe('agent/request-error', () => {
   it('does not retry when the recovery listener fails before returning its action', async () => {
     const adapter = new MockAdapter([fail('busy', 'RATE_LIMIT'), textResponse('unused')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('request-error-recovery-failed'), {
+    const agent = await ctx.agentLoop.create(SessionId('request-error-recovery-failed'), {
       provider: 'mock',
       model: 'mock',
     })
diff --git a/packages/core/agent-loop/tests/request-reconstruction.spec.ts b/packages/core/agent-loop/tests/request-reconstruction.spec.ts
index d6332965ec..93459584a7 100644
--- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts
+++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts
@@ -81,7 +81,7 @@ describe('request stability across the loop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -102,7 +102,7 @@ describe('request stability across the loop', () => {
   it('a later turn append-extends the previous turn (one conversation, one log)', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -118,7 +118,7 @@ describe('request stability across the loop', () => {
   it('starts a new request series only when the admitted step explicitly asks for one', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/pre-step', async ({ turn }, next) => {
       const decision = await next()
       return decision.kind === 'enter' && turn === 2
@@ -139,7 +139,7 @@ describe('request stability across the loop', () => {
   it('retains the explicit series boundary when that request also changes its header', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/pre-step', async ({ turn }, next) => {
       const decision = await next()
       return decision.kind === 'enter' && turn === 2
@@ -168,7 +168,7 @@ describe('request stability across the loop', () => {
   it('keeps the series declaration when an outer listener rebuilds the enter decision', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     // Context-appending wrapper in the tool-cordis / session-reference shape:
     // it rebuilds the downstream decision, so it must spread it to keep fields
     // it does not own — a bare `{ kind: 'enter', messages }` drops the series.
@@ -208,7 +208,7 @@ describe('request stability across the loop', () => {
     }
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')], reasoning)
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('effort'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('effort'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/request', async ({ turn }, next) => {
       const config = await next()
       return turn === 2 ? { ...config, reasoningEffort: ReasoningEffortId('max') } : config
@@ -259,7 +259,7 @@ describe('request stability across the loop', () => {
   it('logs an adapter-owned maxTokens default before dispatch', async () => {
     const adapter = new MockAdapter([textResponse('bounded')], undefined, 256_000)
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('adapter-max-tokens'), {
+    const agent = await ctx.agentLoop.create(SessionId('adapter-max-tokens'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -281,7 +281,7 @@ describe('request stability across the loop', () => {
       ['deepseek', deepseek],
       ['other', other],
     ])
-    const agent = ctx.agentLoop.create(SessionId('adapter-max-tokens-switch'), {
+    const agent = await ctx.agentLoop.create(SessionId('adapter-max-tokens-switch'), {
       provider: 'deepseek',
       model: 'deepseek-model',
     })
@@ -314,7 +314,7 @@ describe('request stability across the loop', () => {
       ['deepseek', deepseek],
       ['other', other],
     ])
-    const agent = ctx.agentLoop.create(SessionId('explicit-max-tokens-switch'), {
+    const agent = await ctx.agentLoop.create(SessionId('explicit-max-tokens-switch'), {
       provider: 'deepseek',
       model: 'deepseek-model',
       maxTokens: 4_096,
@@ -369,7 +369,7 @@ describe('request stability across the loop', () => {
       defaultEffort: ReasoningEffortId('max'),
     })
     const disposeFirst = ctx.llm.registerAdapter(['mock'], first)
-    const agent = ctx.agentLoop.create(SessionId('effort-hmr'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('effort-hmr'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await started.promise
@@ -438,7 +438,7 @@ describe('request stability across the loop', () => {
         }
       }([])
       const ctx = await harness(adapter)
-      const agent = ctx.agentLoop.create(SessionId(`reasoning-${kind}`), {
+      const agent = await ctx.agentLoop.create(SessionId(`reasoning-${kind}`), {
         provider: 'mock',
         model: 'mock',
       })
@@ -473,7 +473,7 @@ describe('request stability across the loop', () => {
         yield* textResponse('owned')
       })()
     })
-    const agent = ctx.agentLoop.create(SessionId('listener-owned'), {
+    const agent = await ctx.agentLoop.create(SessionId('listener-owned'), {
       provider: 'listener',
       model: 'virtual',
     })
@@ -495,7 +495,7 @@ describe('request stability across the loop', () => {
   it('a compaction replace rewrites the resend, and the log explains it', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/request', async ({ turn }, next) => {
       const config = await next()
       return turn === 2 ? { ...config, maxTokens: 1_024 } : config
@@ -533,7 +533,7 @@ describe('request stability across the loop', () => {
       textResponse('recovered'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('same-step-compaction'), {
+    const agent = await ctx.agentLoop.create(SessionId('same-step-compaction'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -564,7 +564,7 @@ describe('request stability across the loop', () => {
   it('a real system-prompt change is a full changed-header snapshot; a stable new turn reuses it', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two'), textResponse('three')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -588,7 +588,7 @@ describe('request stability across the loop', () => {
   it('an inject() during the agent/request waterfall joins the NEXT request (the step/start boundary)', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let injected = false
     ctx.on('agent/request', async (_payload, next) => {
@@ -616,7 +616,7 @@ describe('request stability across the loop', () => {
   it('a mutation attempt on the frozen request content throws into the step (loud, not silent)', async () => {
     const adapter = new MockAdapter([textResponse('one')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('llm/stream', (options, next) => {
       // The historical failure mode this design kills: a listener rewriting
@@ -640,7 +640,7 @@ describe('request stability across the loop', () => {
   it('a fresh loop instance over a seeded log anchors with a resume snapshot and stays cache-aligned', async () => {
     const adapter = new MockAdapter([textResponse('one')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('gen1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('gen1'), { provider: 'mock', model: 'mock' })
     send(agent, 'first')
     await waitForIdle(ctx, agent)
 
@@ -668,7 +668,7 @@ describe('request stability across the loop', () => {
   it('a delegating listener cannot mutate the seed through next() — the fold stays log-true', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/request', async (_payload, next) => {
       const config = await next()
@@ -703,7 +703,7 @@ describe('request stability across the loop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -764,7 +764,7 @@ describe('request/context capacity records', () => {
   it('records capacity once and skips it while the route is unchanged', async () => {
     const adapter = capacityAdapter({ mock: 128_000 }, [textResponse('a'), textResponse('b')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('capacity-dedup'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('capacity-dedup'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -786,7 +786,7 @@ describe('request/context capacity records', () => {
       [textResponse('a'), textResponse('b')],
     )
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('capacity-switch'), { provider: 'mock', model: 'small' })
+    const agent = await ctx.agentLoop.create(SessionId('capacity-switch'), { provider: 'mock', model: 'small' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -803,7 +803,7 @@ describe('request/context capacity records', () => {
 
   it('records and deduplicates a route whose adapter advertises no capacity', async () => {
     const ctx = await harness(new MockAdapter([textResponse('a'), textResponse('b')]))
-    const agent = ctx.agentLoop.create(SessionId('capacity-absent'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('capacity-absent'), { provider: 'mock', model: 'mock' })
     send(agent, 'first')
     await waitForIdle(ctx, agent)
     send(agent, 'second')
@@ -816,7 +816,7 @@ describe('request/context capacity records', () => {
   it('clears a previous capacity when the next route advertises none', async () => {
     const adapter = capacityAdapter({ known: 64_000 }, [textResponse('a'), textResponse('b')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('capacity-clear'), { provider: 'mock', model: 'known' })
+    const agent = await ctx.agentLoop.create(SessionId('capacity-clear'), { provider: 'mock', model: 'known' })
     let model = 'known'
     ctx.on('agent/request', ({ agent: subject }, next) => subject === agent
       ? Promise.resolve({ provider: 'mock', model })
diff --git a/packages/core/agent-loop/tests/resume.spec.ts b/packages/core/agent-loop/tests/resume.spec.ts
index 457de1a306..229229b5b1 100644
--- a/packages/core/agent-loop/tests/resume.spec.ts
+++ b/packages/core/agent-loop/tests/resume.spec.ts
@@ -1,15 +1,16 @@
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ToolCallId, createMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { afterEach, describe, expect, it, vi, type MockInstance } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import { mkdtemp, rm } from 'node:fs/promises'
+import { appendFile, mkdtemp, readdir, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import LlmRuntime from '@deepseek-ai/dsh-llm'
-import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionId, SessionLogOffset, SessionPreparation, SessionSeq } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionHeader, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionLogOffset, SessionSeq, Session, SessionId, TOOL_OUTCOME_UNKNOWN } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import type { SessionHandle } from '@deepseek-ai/dsh-session-persistence'
 
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -25,7 +26,7 @@ async function persistentHarness(adapter: MockAdapter): Promise<{ ctx: Context;
   return { ctx: await mountPersistentHarness(root, adapter), root }
 }
 
-async function mountPersistentHarness(root: string, adapter: MockAdapter): Promise<Context> {
+async function mountPersistentHarness(root: string, adapter: MockAdapter, compression?: 'none'): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(LlmRuntime)
   await ctx.plugin(SessionStore)
@@ -33,14 +34,34 @@ async function mountPersistentHarness(root: string, adapter: MockAdapter): Promi
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRuntime)
   await ctx.plugin(AgentRegistry)
+  // The backend mounts BEFORE the loop so root teardown unwinds the loop
+  // first: live agents drain their writers into still-open handles.
+  await ctx.plugin(JsonlSessionPersistence, { root, ...compression === undefined ? {} : { compression } })
   await ctx.plugin(AgentLoop, { agents: [] })
-  await ctx.plugin(JsonlSessionPersistence, { root })
   ctx.llm.registerAdapter(['mock'], adapter)
   return ctx
 }
 
+/** Seed one stored session through the persistence seam (header minted by the store). */
+async function seedStoredSession(ctx: Context, sessionId: SessionId, events: readonly SessionEvent[]): Promise<void> {
+  const detached = ctx.sessions.prepare(sessionId)
+  const handle = await ctx.sessionPersistence.create(detached.header)
+  await handle.append(events)
+  await handle.close()
+}
+
+/** Read one stored session's physical validated log through a read handle. */
+async function readStoredEvents(ctx: Context, sessionId: SessionId): Promise<readonly SessionEvent[]> {
+  const handle = await ctx.sessionPersistence.open(sessionId, 'read')
+  try {
+    return await handle.read()
+  } finally {
+    await handle.close()
+  }
+}
+
 async function persistSession(sessionId: SessionId): Promise<string> {
-  const { ctx, root } = await persistentHarness(new MockAdapter([textResponse('seed')]))
+  const { ctx, root } = await persistentHarness(new MockAdapter([]))
   // Persistence deliberately has no artifact for a truly empty session. A
   // balanced completed turn is the smallest resumable log and avoids running
   // the model merely to construct this lifecycle fixture.
@@ -48,27 +69,15 @@ async function persistSession(sessionId: SessionId): Promise<string> {
     { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
     { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
-  const session = ctx.sessions.create(sessionId, { seed })
-  await ctx.sessions.flush(session)
+  await seedStoredSession(ctx, sessionId, seed)
   await ctx.fiber.dispose()
   return root
 }
 
-/** Build a detached preparation for lifecycle-race test doubles. */
-function preparationFromSnapshot(
-  ctx: Context,
-  snapshot: {
-    meta: SessionHeader
-    inheritedEventCount: SessionLogOffsetType
-    events: readonly SessionEvent[]
-  },
-): SessionPreparation {
-  return SessionPreparation.create(ctx.sessions.prepare(snapshot.meta.id, {
-    seed: structuredClone(snapshot.events) as SessionEvent[],
-    meta: structuredClone(snapshot.meta),
-    inheritedEventCount: snapshot.inheritedEventCount,
-    seedSource: 'persistence',
-  }))
+/** A handle stand-in for abandoned-open races; only `close()` is ever reachable. */
+function abandonedHandleStub(): { handle: SessionHandle; close: ReturnType<typeof vi.fn> } {
+  const close = vi.fn(async () => {})
+  return { handle: { close } as unknown as SessionHandle, close }
 }
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
@@ -96,84 +105,7 @@ function throwUnknown(value: unknown): never {
 }
 
 describe('the session-persistence Agent Note: AgentLoop factory create/resume', () => {
-  it('resumes a pre-react-loop session including pre-identity message events', async () => {
-    const sessionId = SessionId('pre-identity-resume')
-    const first = await persistentHarness(new MockAdapter([]))
-    await first.ctx.sessionPersistence.create({
-      version: SESSION_FORMAT_VERSION,
-      id: sessionId,
-      createdAt: 1,
-      isSeeded: false,
-    })
-    await first.ctx.sessionPersistence.append(sessionId, [
-      {
-        type: 'turn/start', seq: 0, time: 1,
-        data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
-      },
-      {
-        type: 'user/message',
-        seq: 1,
-        time: 2,
-        data: { content: [{ type: 'text', text: 'old question' }], source: { kind: 'user' } },
-        surfaceOp: 'append',
-      },
-      { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
-      {
-        type: 'assistant/message',
-        seq: 3,
-        time: 4,
-        data: {
-          turn: 1,
-          step: 1,
-          content: [{ type: 'text', text: 'old answer' }],
-          provenance: { provider: 'mock', model: 'mock' },
-        },
-        surfaceOp: 'append',
-      },
-      {
-        type: 'steering/message',
-        seq: 4,
-        time: 5,
-        data: {
-          turn: 1,
-          content: [{ type: 'text', text: 'old steering' }],
-          source: { kind: 'user' },
-        },
-        surfaceOp: 'append',
-      },
-      { type: 'step/end', seq: 5, time: 6, data: { turn: 1, step: 1 } },
-      { type: 'turn/end', seq: 6, time: 7, data: { turn: 1, reason: { kind: 'completed' } } },
-    ] as unknown as SessionEvent[])
-    await first.ctx.fiber.dispose()
-
-    const ctx = await mountPersistentHarness(first.root, new MockAdapter([textResponse('new answer')]))
-    const handle = await ctx.agents.resume({
-      resumeSessionId: sessionId,
-      agentOptions: { provider: 'mock', model: 'mock' },
-    })
-    expect(handle.agent.session.deriveMessages()).toMatchObject([
-      { id: `legacy-message:${sessionId}:1`, role: 'user' },
-      { id: `legacy-message:${sessionId}:3`, role: 'assistant' },
-      { id: `legacy-message:${sessionId}:4`, role: 'user' },
-    ])
-    expect(handle.agent.inbox.nextTurn).toEqual([])
-    expect(handle.agent.inbox.nextStep).toEqual([])
-
-    handle.agent.followup(createUserMessage({
-      content: [{ type: 'text', text: 'new question' }],
-      source: { kind: 'user' },
-    }))
-    await waitForIdle(ctx, handle.agent)
-    expect(handle.agent.session.deriveMessages()).toHaveLength(5)
-    expect(handle.agent.session.snapshotEvents().at(-1)).toMatchObject({
-      type: 'turn/end',
-      data: { reason: { kind: 'completed' } },
-    })
-    await handle.dispose()
-    await ctx.fiber.dispose()
-  })
-
-  it('normalizes a non-Error resume publication failure for rollback and rethrows it', async () => {
+  it('normalizes a non-Error resume publication failure for rollback and releases the write handle', async () => {
     const sessionId = SessionId('unknown-resume-failure-s')
     const root = await persistSession(sessionId)
     const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
@@ -186,6 +118,9 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
 
     expect(ctx.agents.get(SessionId('unknown-resume-failure'))).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    // Rollback closed the write handle: write ownership is claimable again.
+    const reopened = await ctx.sessionPersistence.open(sessionId, 'write')
+    await reopened.close()
     await ctx.fiber.dispose()
   })
 
@@ -208,6 +143,302 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     await ctx.fiber.dispose()
   })
 
+  it('a created agent stores its seed and live turn durably through its handle', async () => {
+    const seed: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    const { ctx } = await persistentHarness(new MockAdapter([textResponse('stored')]))
+    const sessionId = SessionId('durable-create')
+    const handle = await ctx.agents.create({
+      sessionId,
+      seed,
+      meta: { cwd: '/w' },
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, handle.agent)
+    await handle.dispose()
+
+    const stored = await readStoredEvents(ctx, sessionId)
+    const seqs = stored.map(event => event.seq)
+    expect(seqs).toEqual(seqs.map((_, index) => index))
+    // The constructor seed (turn 1 + its end-seed marker) precedes the live turn 2.
+    expect(stored.slice(0, 2).map(event => event.type)).toEqual(['turn/start', 'turn/end'])
+    expect(stored[2]?.type).toBe('session/end-seed')
+    const turnStarts = stored.filter(event => event.type === 'turn/start')
+    expect(turnStarts.map(event => event.type === 'turn/start' && event.data.turn)).toEqual([1, 2])
+    expect(stored.some(event => event.type === 'turn/end' && event.data.turn === 2)).toBe(true)
+    expect(JSON.stringify(stored)).toContain('stored')
+    await ctx.fiber.dispose()
+  })
+
+  it('a rejecting final writer close releases the registries, then rejects disposal', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([textResponse('hi')]))
+    const sessionId = SessionId('drain-close-fails')
+    const handle = await ctx.agents.create({ sessionId })
+    const persisted = await ctx.sessionPersistence.open(sessionId, 'read')
+    await persisted.close()
+    const stored = [...(ctx.sessionPersistence as unknown as {
+      tracker: { openHandles: Set<SessionHandle> }
+    }).tracker.openHandles].find(open => open.id === sessionId && open.access === 'write')
+    if (stored === undefined) throw new Error('missing owned write handle')
+    // The real close still runs (releasing write ownership); the injected
+    // failure models a drain that reports a durability error at close.
+    const realClose = stored.close.bind(stored)
+    vi.spyOn(stored, 'close').mockImplementation(async () => {
+      await realClose()
+      throw new Error('close exploded')
+    })
+
+    await expect(handle.dispose()).rejects.toThrow('close exploded')
+    // Teardown reached quiescence before the rejection: the agent and session
+    // are unregistered, and write ownership is released — the never-flushed
+    // session reports absence, not an ownership conflict.
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    await expect(ctx.sessionPersistence.open(sessionId, 'write')).rejects.toThrow('not found')
+    await ctx.fiber.dispose()
+  })
+
+  it('combines a machine-teardown failure with a close failure into one rejection', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([textResponse('hi')]))
+    const sessionId = SessionId('drain-both-fail')
+    const handle = await ctx.agents.create({ sessionId })
+    const stored = [...(ctx.sessionPersistence as unknown as {
+      tracker: { openHandles: Set<SessionHandle> }
+    }).tracker.openHandles].find(open => open.id === sessionId && open.access === 'write')
+    if (stored === undefined) throw new Error('missing owned write handle')
+    const machine = handle.agent as Agent & { scope: { dispose: () => Promise<void> } }
+    vi.spyOn(machine.scope, 'dispose').mockRejectedValue(new Error('scope exploded'))
+    vi.spyOn(stored, 'close').mockRejectedValue(new Error('close exploded'))
+
+    const failure = await handle.dispose().then(() => undefined, (error: unknown) => error)
+    if (!(failure instanceof AggregateError)) throw new Error('expected an AggregateError rejection')
+    expect(failure.message).toContain(`agent "${sessionId}" disposal failed`)
+    expect(failure.errors.map(error => (error as Error).message)).toEqual(['scope exploded', 'close exploded'])
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('agent dispose releases write ownership of its stored session', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([textResponse('hi')]))
+    const sessionId = SessionId('ownership-release')
+    const handle = await ctx.agents.create({ sessionId })
+
+    await expect(ctx.sessionPersistence.open(sessionId, 'write'))
+      .rejects.toThrow(/already owned by an active write handle/)
+
+    // Materialize the log so the session outlives its creator handle.
+    handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, handle.agent)
+    await handle.dispose()
+    const reopened = await ctx.sessionPersistence.open(sessionId, 'write')
+    expect(reopened.access).toBe('write')
+    await reopened.close()
+    await ctx.fiber.dispose()
+  })
+
+  it('a stored-session create failure rolls the fresh identity back', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([]))
+    const sessionId = SessionId('create-backend-fail')
+    vi.spyOn(ctx.sessionPersistence, 'create').mockRejectedValueOnce(new Error('backend create failed'))
+
+    await expect(ctx.agents.create({ sessionId })).rejects.toThrow('backend create failed')
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+
+    // The identity was fully released: the same id creates cleanly afterwards.
+    const retry = await ctx.agents.create({ sessionId })
+    await retry.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('a seed append failure closes the fresh write handle and rethrows', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([]))
+    const sessionId = SessionId('seed-append-fail')
+    const seed: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    const originalCreate = ctx.sessionPersistence.create.bind(ctx.sessionPersistence)
+    let closeSpy: MockInstance<() => Promise<void>> | undefined
+    ctx.sessionPersistence.create = async (header, options) => {
+      const handle = await originalCreate(header, options)
+      vi.spyOn(handle, 'append').mockRejectedValue(new Error('seed append failed'))
+      closeSpy = vi.spyOn(handle, 'close')
+      return handle
+    }
+
+    await expect(ctx.agents.create({ sessionId, seed })).rejects.toThrow('seed append failed')
+    expect(closeSpy).toHaveBeenCalled()
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    // The closed never-materialized creation left no stored session behind.
+    await expect(ctx.sessionPersistence.open(sessionId, 'write'))
+      .rejects.toThrow(/not found/)
+    await ctx.fiber.dispose()
+  })
+
+
+  it('a setup failure before publication leaves no stored residue; the id creates again', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([]))
+    const sessionId = SessionId('setup-fail-no-residue')
+    const seed: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    await expect(ctx.agents.create({
+      sessionId,
+      seed,
+      setup: () => { throw new Error('setup refused') },
+    })).rejects.toThrow('setup refused')
+
+    // The seed is stored only at the publication commit point, so the failed
+    // attempt materialized nothing and released the identity completely.
+    await expect(ctx.sessionPersistence.stat(sessionId)).resolves.toBeUndefined()
+    const retry = await ctx.agents.create({ sessionId, seed })
+    await expect(ctx.sessionPersistence.stat(sessionId)).resolves.toBeDefined()
+    await retry.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('rollback swallows a rejecting handle close after a prepare failure (create and createAgent)', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([]))
+    const originalCreate = ctx.sessionPersistence.create.bind(ctx.sessionPersistence)
+    const closeSpies: Array<{ mockRestore: () => void }> = []
+    ctx.sessionPersistence.create = async (header, options) => {
+      const handle = await originalCreate(header, options)
+      closeSpies.push(vi.spyOn(handle, 'close').mockRejectedValue(new Error('close failed')))
+      return handle
+    }
+
+    // Config create path: prepare's option validation throws after the handle exists.
+    await expect(ctx.agentLoop.create(SessionId('close-reject-config'), { maxTokens: -1 }))
+      .rejects.toThrow('agent maxTokens must be a positive safe integer')
+    expect(ctx.agents.get(SessionId('close-reject-config'))).toBeUndefined()
+
+    // Owned createAgent path: the same validation failure after the handle exists.
+    await expect(ctx.agents.create({
+      sessionId: SessionId('close-reject-owned'),
+      agentOptions: { maxTokens: -1 },
+    })).rejects.toThrow('agent maxTokens must be a positive safe integer')
+    expect(ctx.agents.get(SessionId('close-reject-owned'))).toBeUndefined()
+
+    for (const spy of closeSpies.splice(0)) spy.mockRestore()
+    await ctx.fiber.dispose()
+  })
+
+  it('a reentrant abort during preparation swallows a rejecting handle close', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([]))
+    const sessionId = SessionId('prepare-abort-close-reject')
+    const originalCreate = ctx.sessionPersistence.create.bind(ctx.sessionPersistence)
+    const spies: Array<{ mockRestore: () => void }> = []
+    let closed: Promise<void> | undefined
+    ctx.sessionPersistence.create = async (header, options) => {
+      const handle = await originalCreate(header, options)
+      const realClose = handle.close.bind(handle)
+      spies.push(vi.spyOn(handle, 'close').mockImplementation(async () => {
+        closed = realClose()
+        await closed
+        throw new Error('close failed')
+      }))
+      return handle
+    }
+    const reason = new Error('cancelled while preparing')
+    const controller = new AbortController()
+    let aborted = false
+    ctx.on('internal/plugin', (fiber) => {
+      if (aborted || fiber.name !== 'scope') return
+      aborted = true
+      controller.abort(reason)
+    })
+
+    await expect(ctx.agents.create({ sessionId, signal: controller.signal })).rejects.toBe(reason)
+    // The rejecting close stays swallowed by the rollback; wait for the
+    // rollback's real close so factory teardown finds a quiescent lifecycle.
+    await vi.waitFor(() => { if (closed === undefined) throw new Error('close not reached') })
+    await closed
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    for (const spy of spies.splice(0)) spy.mockRestore()
+    await ctx.fiber.dispose()
+  })
+
+  it('config create rollback swallows a rejecting close after a publish failure', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([]))
+    const sessionId = SessionId('config-publish-close-reject')
+    const originalCreate = ctx.sessionPersistence.create.bind(ctx.sessionPersistence)
+    const spies: Array<{ mockRestore: () => void }> = []
+    let closed: Promise<void> | undefined
+    ctx.sessionPersistence.create = async (header, options) => {
+      const handle = await originalCreate(header, options)
+      const realClose = handle.close.bind(handle)
+      spies.push(vi.spyOn(handle, 'close').mockImplementation(async () => {
+        closed = realClose()
+        await closed
+        throw new Error('close failed')
+      }))
+      return handle
+    }
+    const announce = vi.spyOn(ctx.agents, 'announce').mockImplementation(() => {
+      throw new Error('announce failed')
+    })
+
+    await expect(ctx.agentLoop.create(sessionId)).rejects.toThrow('announce failed')
+    announce.mockRestore()
+    await vi.waitFor(() => { if (closed === undefined) throw new Error('close not reached') })
+    await closed
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    for (const spy of spies.splice(0)) spy.mockRestore()
+    await ctx.fiber.dispose()
+  })
+
+  it('a seed append failure swallows a rejecting handle close', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([]))
+    const sessionId = SessionId('seed-append-close-reject')
+    const seed: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    const originalCreate = ctx.sessionPersistence.create.bind(ctx.sessionPersistence)
+    const spies: Array<{ mockRestore: () => void }> = []
+    ctx.sessionPersistence.create = async (header, options) => {
+      const handle = await originalCreate(header, options)
+      spies.push(vi.spyOn(handle, 'append').mockRejectedValue(new Error('seed append failed')))
+      spies.push(vi.spyOn(handle, 'close').mockRejectedValue(new Error('close failed')))
+      return handle
+    }
+
+    await expect(ctx.agents.create({ sessionId, seed })).rejects.toThrow('seed append failed')
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+
+    for (const spy of spies.splice(0)) spy.mockRestore()
+    await ctx.fiber.dispose()
+  })
+
+  it('a resume read failure swallows a rejecting handle close during rollback', async () => {
+    const sessionId = SessionId('resume-read-close-reject')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([]))
+    const originalOpen = ctx.sessionPersistence.open.bind(ctx.sessionPersistence)
+    const spies: Array<{ mockRestore: () => void }> = []
+    ctx.sessionPersistence.open = async (id, access, options) => {
+      const handle = await originalOpen(id, access, options)
+      spies.push(vi.spyOn(handle, 'read').mockRejectedValue(new Error('stored read failed')))
+      spies.push(vi.spyOn(handle, 'close').mockRejectedValue(new Error('close failed')))
+      return handle
+    }
+
+    await expect(ctx.agents.resume({ resumeSessionId: sessionId }))
+      .rejects.toThrow('stored read failed')
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+
+    for (const spy of spies.splice(0)) spy.mockRestore()
+    await ctx.fiber.dispose()
+  })
+
   it('resume cannot crash-repair a turn owned by a live agent', async () => {
     const { ctx } = await persistentHarness(new MockAdapter([textResponse('unused')]))
     const sessionId = SessionId('live-resume-race')
@@ -216,19 +447,111 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     await ctx.sessions.flush(first.session)
 
     await expect(ctx.agents.resume({ resumeSessionId: sessionId }))
-      .rejects.toThrow(/while it is live/)
+      .rejects.toThrow(/already owned by an active write handle/)
 
     first.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     await ctx.sessions.flush(first.session)
-    const loaded = await ctx.sessionPersistence.load(sessionId)
-    expect(loaded.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
-    expect(loaded.events.at(-1)).toMatchObject({
+    const stored = await readStoredEvents(ctx, sessionId)
+    expect(stored.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
+    expect(stored.at(-1)).toMatchObject({
       type: 'turn/end',
       data: { reason: { kind: 'completed' } },
     })
     await ctx.fiber.dispose()
   })
 
+  it('resume appends interrupted-turn closers durably through the handle', async () => {
+    // Lifecycle 1: store an interrupted log — an open turn with no turn/end.
+    const sessionId = SessionId('interrupted-resume')
+    const { ctx: ctx1, root } = await persistentHarness(new MockAdapter([]))
+    await seedStoredSession(ctx1, sessionId, [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+    ])
+    // A read returns the PHYSICAL validated log: no synthetic closers.
+    const raw = await readStoredEvents(ctx1, sessionId)
+    expect(raw.map(event => event.type)).toEqual(['turn/start'])
+    await ctx1.fiber.dispose()
+
+    // Lifecycle 2: resume repairs the tail and stores the repair durably.
+    const ctx2 = await mountPersistentHarness(root, new MockAdapter([]))
+    const handle = await ctx2.agents.resume({ resumeSessionId: sessionId })
+    expect(handle.agent.session.snapshotEvents().map(event => event.type))
+      .toEqual(['turn/start', 'turn/end', 'session/end-seed'])
+    await handle.dispose()
+
+    const stored = await readStoredEvents(ctx2, sessionId)
+    expect(stored.map(event => event.type)).toEqual(['turn/start', 'turn/end', 'session/end-seed'])
+    expect(stored[1]).toMatchObject({ data: { reason: { kind: 'interrupted' } } })
+    await ctx2.fiber.dispose()
+  })
+
+  it('resume closes an interrupted tool call durably: tool/result, step/end, turn/end', async () => {
+    const sessionId = SessionId('interrupted-tool-resume')
+    const { ctx: ctx1, root } = await persistentHarness(new MockAdapter([]))
+    await seedStoredSession(ctx1, sessionId, [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      { type: 'step/start', seq: SessionSeq(1), time: 1, data: { turn: 1, step: 1 } },
+      { type: 'assistant/message', seq: SessionSeq(2), time: 2, surfaceOp: 'append', data: {
+        turn: 1, step: 1,
+        message: createMessage({
+          role: 'assistant',
+          content: [{ type: 'tool-call', id: ToolCallId('call-1'), name: 'bash', arguments: '{}' }],
+          source: { kind: 'model', provider: 'mock', model: 'mock' },
+        }),
+      } },
+      { type: 'tool/call', seq: SessionSeq(3), time: 2, data: { turn: 1, step: 1, callId: ToolCallId('call-1'), name: 'bash', arguments: '{}' } },
+    ] as SessionEvent[])
+    await ctx1.fiber.dispose()
+
+    const ctx2 = await mountPersistentHarness(root, new MockAdapter([]))
+    const handle = await ctx2.agents.resume({ resumeSessionId: sessionId })
+    await handle.dispose()
+
+    // The multi-closer set lands durably in one contiguous batch, and the
+    // synthetic tool/result cites the recorded tool/call seq.
+    const stored = await readStoredEvents(ctx2, sessionId)
+    expect(stored.map(event => event.type)).toEqual([
+      'turn/start', 'step/start', 'assistant/message', 'tool/call',
+      'tool/result', 'step/end', 'turn/end', 'session/end-seed',
+    ])
+    expect(stored.map(event => event.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+    expect(stored[4]).toMatchObject({
+      sourceEventSeqs: [3],
+      data: { error: { code: TOOL_OUTCOME_UNKNOWN } },
+    })
+    expect(stored[6]).toMatchObject({ data: { reason: { kind: 'interrupted' } } })
+    await ctx2.fiber.dispose()
+  })
+
+  it('resume over a torn physical tail continues from the committed prefix', async () => {
+    const sessionId = SessionId('torn-tail-resume')
+    const root = await mkdtemp(join(tmpdir(), 'dsh-resume-torn-'))
+    dirs.push(root)
+    const ctx1 = await mountPersistentHarness(root, new MockAdapter([]), 'none')
+    await seedStoredSession(ctx1, sessionId, [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+    ])
+    await ctx1.fiber.dispose()
+
+    // Crash artifact: a half-written record with no trailing newline.
+    const logs = (await readdir(root, { recursive: true })).filter(name => name.endsWith('.jsonl'))
+    expect(logs).toHaveLength(1)
+    await appendFile(join(root, logs[0] as string), '{"type":"assistant/chunk","seq":1,"ti')
+
+    // Resume truncates the torn tail under its write open, then appends the
+    // closers immediately after the committed prefix — no gap, no fragment.
+    const ctx2 = await mountPersistentHarness(root, new MockAdapter([]), 'none')
+    const handle = await ctx2.agents.resume({ resumeSessionId: sessionId })
+    expect(handle.agent.session.snapshotEvents().map(event => event.type))
+      .toEqual(['turn/start', 'turn/end', 'session/end-seed'])
+    await handle.dispose()
+
+    const stored = await readStoredEvents(ctx2, sessionId)
+    expect(stored.map(event => `${event.type}@${event.seq}`))
+      .toEqual(['turn/start@0', 'turn/end@1', 'session/end-seed@2'])
+    await ctx2.fiber.dispose()
+  })
+
   it('createAgent works without meta (no cwd)', async () => {
     const adapter = new MockAdapter([textResponse('hi')])
     const { ctx } = await persistentHarness(adapter)
@@ -242,23 +565,15 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     // Lifecycle 1: create a no-cwd session and run a turn.
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = (await ctx1.agents.create({ sessionId: SessionId('nocwd-sess') })).agent
-    a1.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
-    await waitForIdle(ctx1, a1)
+    const h1 = await ctx1.agents.create({ sessionId: SessionId('nocwd-sess') })
+    h1.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx1, h1.agent)
+    // Agent disposal drains the writer through the still-open handle.
+    await h1.dispose()
     await ctx1.fiber.dispose()
 
     // Lifecycle 2: resume it; the header cwd stays undefined (no-cwd branch).
-    const adapter2 = new MockAdapter([textResponse('b')])
-    const ctx2 = new Context()
-    await ctx2.plugin(LlmRuntime)
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(SessionProjectionRegistry)
-    await ctx2.plugin(SystemPrompt)
-    await ctx2.plugin(ToolRuntime)
-    await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [] })
-    await ctx2.plugin(JsonlSessionPersistence, { root })
-    ctx2.llm.registerAdapter(['mock'], adapter2)
+    const ctx2 = await mountPersistentHarness(root, new MockAdapter([textResponse('b')]))
     const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('nocwd-sess') })).agent
     expect(a2.session.header.cwd).toBeUndefined()
     await ctx2.fiber.dispose()
@@ -270,24 +585,15 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const sources1: string[] = []
     ctx1.on('agent/session-start', ({ source }) => void sources1.push(source))
-    const a1 = (await ctx1.agents.create({ sessionId: SessionId('start-sess') })).agent
+    const h1 = await ctx1.agents.create({ sessionId: SessionId('start-sess') })
     expect(sources1).toEqual(['startup'])
-    a1.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
-    await waitForIdle(ctx1, a1)
+    h1.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx1, h1.agent)
+    await h1.dispose()
     await ctx1.fiber.dispose()
 
     // Lifecycle 2: resuming the persisted session emits session-start 'resume'.
-    const adapter2 = new MockAdapter([textResponse('b')])
-    const ctx2 = new Context()
-    await ctx2.plugin(LlmRuntime)
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(SessionProjectionRegistry)
-    await ctx2.plugin(SystemPrompt)
-    await ctx2.plugin(ToolRuntime)
-    await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [] })
-    await ctx2.plugin(JsonlSessionPersistence, { root })
-    ctx2.llm.registerAdapter(['mock'], adapter2)
+    const ctx2 = await mountPersistentHarness(root, new MockAdapter([textResponse('b')]))
     const sources2: string[] = []
     ctx2.on('agent/session-start', ({ source }) => void sources2.push(source))
     await ctx2.agents.resume({ resumeSessionId: SessionId('start-sess') })
@@ -361,6 +667,28 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     await ctx.fiber.dispose()
   })
 
+  it('a resumed session stores its repair suffix durably before publication', async () => {
+    // The stored fixture (two events, no end-seed) gains the end-seed marker
+    // through the resume handle: after one resume lifecycle the STORED log
+    // carries it, so the next resume reads it back without re-marking.
+    const sessionId = SessionId('resume-suffix-durable')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([]))
+    const first = await ctx.agents.resume({ resumeSessionId: sessionId })
+    await first.dispose()
+
+    const stored = await readStoredEvents(ctx, sessionId)
+    expect(stored.map(event => event.type)).toEqual(['turn/start', 'turn/end', 'session/end-seed'])
+
+    const second = await ctx.agents.resume({ resumeSessionId: sessionId })
+    expect(second.agent.session.snapshotEvents().map(event => event.type))
+      .toEqual(['turn/start', 'turn/end', 'session/end-seed'])
+    await second.dispose()
+    const restored = await readStoredEvents(ctx, sessionId)
+    expect(restored.map(event => event.type)).toEqual(['turn/start', 'turn/end', 'session/end-seed'])
+    await ctx.fiber.dispose()
+  })
+
   it('successful resume disposal retires its caller-owned transaction effects', async () => {
     const sessionId = SessionId('resume-retired-effects-s')
     const root = await persistSession(sessionId)
@@ -468,24 +796,22 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     await ctx.fiber.dispose()
   })
 
-  it('owner unload aborts a never-settling persistence preparation, releases the identity, and blocks late publication', async () => {
+  it('owner unload aborts a never-settling persistence open, releases the identity, and blocks late publication', async () => {
     const sessionId = SessionId('resume-load-owner-unload')
     const root = await persistSession(sessionId)
     const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
-    const snapshot = await ctx.sessionPersistence.load(sessionId)
-    const abandoned = preparationFromSnapshot(ctx, snapshot)
-    const latePreparation = Promise.withResolvers<SessionPreparation>()
-    const preparationStarted = Promise.withResolvers<undefined>()
-    const originalPrepare = ctx.sessionPersistence.prepare.bind(ctx.sessionPersistence)
-    let preparations = 0
-    ctx.sessionPersistence.prepare = (id, signal) => {
+    const lateOpen = Promise.withResolvers<SessionHandle>()
+    const openStarted = Promise.withResolvers<undefined>()
+    const originalOpen = ctx.sessionPersistence.open.bind(ctx.sessionPersistence)
+    let opens = 0
+    ctx.sessionPersistence.open = (id, access, options) => {
       expect(id).toBe(sessionId)
-      preparations += 1
-      if (preparations === 1) {
-        preparationStarted.resolve(undefined)
-        return latePreparation.promise
+      opens += 1
+      if (opens === 1) {
+        openStarted.resolve(undefined)
+        return lateOpen.promise
       }
-      return originalPrepare(id, signal)
+      return originalOpen(id, access, options)
     }
 
     const published: string[] = []
@@ -497,7 +823,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
       resuming = inner.agents.resume({ resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
     }, { inject: ['agents'] }))
-    await preparationStarted.promise
+    await openStarted.promise
 
     const rejection = expect(promptly(resuming)).rejects.toThrow(/owner disposed during setup/)
     await promptly(owner.dispose())
@@ -509,24 +835,24 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     // can be reused before awaiting the public rejection.
     const retry = await promptly(ctx.agents.resume({ resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } }))
     await rejection
-    expect(preparations).toBe(2)
+    expect(opens).toBe(2)
     expect(published).toEqual(['session/created', 'agent/created', 'agent/session-start'])
 
-    // Settlement of the abandoned backend promise cannot resume the old
-    // transaction or emit a second publication after the retry owns the ids.
-    latePreparation.resolve(abandoned)
-    await Promise.resolve()
-    await Promise.resolve()
+    // Settlement of the abandoned backend open cannot resume the old
+    // transaction: the late handle is closed, and no second publication lands
+    // after the retry owns the ids.
+    const abandoned = abandonedHandleStub()
+    lateOpen.resolve(abandoned.handle)
+    await expect.poll(() => abandoned.close.mock.calls.length).toBe(1)
     expect(ctx.agents.get(sessionId)).toBe(retry.agent)
     expect(ctx.sessions.get(sessionId)).toBe(retry.agent.session)
     expect(published).toEqual(['session/created', 'agent/created', 'agent/session-start'])
 
-    abandoned[Symbol.dispose]()
     await retry.dispose()
     await ctx.fiber.dispose()
   })
 
-  it('AgentLoop unload aborts persistence preparation and awaits wrapper settlement', async () => {
+  it('AgentLoop unload aborts a never-settling persistence open and awaits wrapper settlement', async () => {
     const sessionId = SessionId('resume-load-factory-unload')
     const root = await persistSession(sessionId)
     const ctx = new Context()
@@ -540,21 +866,19 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     await ctx.plugin(JsonlSessionPersistence, { root })
     ctx.llm.registerAdapter(['mock'], new MockAdapter([textResponse('next')]))
 
-    const snapshot = await ctx.sessionPersistence.load(sessionId)
-    const abandoned = preparationFromSnapshot(ctx, snapshot)
-    const latePreparation = Promise.withResolvers<SessionPreparation>()
-    const preparationStarted = Promise.withResolvers<undefined>()
-    ctx.sessionPersistence.prepare = (id) => {
+    const lateOpen = Promise.withResolvers<SessionHandle>()
+    const openStarted = Promise.withResolvers<undefined>()
+    ctx.sessionPersistence.open = (id) => {
       expect(id).toBe(sessionId)
-      preparationStarted.resolve(undefined)
-      return latePreparation.promise
+      openStarted.resolve(undefined)
+      return lateOpen.promise
     }
     const published: string[] = []
     ctx.on('session/created', () => void published.push('session/created'))
     ctx.on('agent/created', () => void published.push('agent/created'))
 
     const resuming = ctx.agents.resume({ resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
-    await preparationStarted.promise
+    await openStarted.promise
     const rejection = expect(promptly(resuming)).rejects.toThrow(/agent loop is not active/)
     await promptly(loopFiber.dispose())
     await rejection
@@ -562,46 +886,38 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     expect(published).toEqual([])
     expect(ctx.agents.get(sessionId)).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
-    latePreparation.resolve(abandoned)
-    await Promise.resolve()
-    await Promise.resolve()
+    // The abandoned handle is closed once the hung open finally settles.
+    const abandoned = abandonedHandleStub()
+    lateOpen.resolve(abandoned.handle)
+    await expect.poll(() => abandoned.close.mock.calls.length).toBe(1)
     expect(published).toEqual([])
-    abandoned[Symbol.dispose]()
     await ctx.fiber.dispose()
   })
 
   it('resume of a forked session preserves the lineage, seed boundary, and delegation depth in the header', async () => {
-    // Lifecycle 1: persist a FORKED session (carries parentSession + isSeeded
-    // in its header and an exact Session-owned cut) with a complete-turn seed — the write path
-    // materializes the fork (header + seed) on disk.
+    // Lifecycle 1: persist a FORKED session (carries parentSession + seedLength
+    // in its header) through createAgent with a complete-turn seed — the
+    // factory stores the header and seed through its write handle.
     const seed: SessionEvent[] = [
       { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
       { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
-    const adapter1 = new MockAdapter([textResponse('a')])
-    const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const forked = ctx1.sessions.create(SessionId('forked-sess'), {
+    const { ctx: ctx1, root } = await persistentHarness(new MockAdapter([]))
+    const forked = await ctx1.agents.create({
+      sessionId: SessionId('forked-sess'),
       seed,
-      inheritedEventCount: SessionLogOffset(seed.length),
       meta: { cwd: '/w', parentSession: SessionId('parent-sess'), isSeeded: true, delegationDepth: 1 },
+      inheritedEventCount: SessionLogOffset(seed.length),
     })
-    await ctx1.sessions.flush(forked)
+    await forked.dispose()
     await ctx1.fiber.dispose()
 
-    // Lifecycle 2: resume it; parentSession, isSeeded, and the exact cut survive
-    // the round-trip. The inherited count must come from persisted storage,
-    // not the resume seed length (the whole stored log).
-    const adapter2 = new MockAdapter([textResponse('b')])
-    const ctx2 = new Context()
-    await ctx2.plugin(LlmRuntime)
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(SessionProjectionRegistry)
-    await ctx2.plugin(SystemPrompt)
-    await ctx2.plugin(ToolRuntime)
-    await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [] })
-    await ctx2.plugin(JsonlSessionPersistence, { root })
-    ctx2.llm.registerAdapter(['mock'], adapter2)
+    // Lifecycle 2: resume it; the parentSession + seedLength header survives the
+    // round-trip (exercises resume's parentSession- and seedLength-present
+    // branches). seedLength must come from the PERSISTED header, not from the
+    // resume seed length (which is the whole stored log, not the original
+    // boundary).
+    const ctx2 = await mountPersistentHarness(root, new MockAdapter([textResponse('b')]))
     const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('forked-sess') })).agent
     expect(a2.session.header.parentSession).toBe('parent-sess')
     expect(a2.session.header.cwd).toBe('/w')
@@ -625,20 +941,10 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
 
     // Lifecycle 2: resume; the injected context is still pending and becomes
     // model-visible when the next turn admits it.
-    const adapter2 = new MockAdapter([textResponse('next')])
-    const ctx2 = new Context()
-    await ctx2.plugin(LlmRuntime)
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(SessionProjectionRegistry)
-    await ctx2.plugin(SystemPrompt)
-    await ctx2.plugin(ToolRuntime)
-    await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [] })
-    await ctx2.plugin(JsonlSessionPersistence, { root })
-    ctx2.llm.registerAdapter(['mock'], adapter2)
-    const loaded = await ctx2.sessionPersistence.load(SessionId('inject-sess'))
-    expect(loaded.events.some(event => event.type === 'agent/inbox/spliced')).toBe(true)
-    expect(JSON.stringify(loaded.events)).toContain('background job 42 finished')
+    const ctx2 = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
+    const stored = await readStoredEvents(ctx2, SessionId('inject-sess'))
+    expect(stored.some(event => event.type === 'agent/inbox/spliced')).toBe(true)
+    expect(JSON.stringify(stored)).toContain('background job 42 finished')
     const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('inject-sess') })).agent
     expect(JSON.stringify(a2.inbox.nextStep)).toContain('background job 42 finished')
     a2.followup(createUserMessage({ content: [{ type: 'text', text: 'continue' }], source: { kind: 'user' } }))
@@ -653,26 +959,18 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     // Lifecycle 1: run one full turn, persisting it.
     const adapter1 = new MockAdapter([textResponse('first answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = (await ctx1.agents.create({ sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } })).agent
+    const h1 = await ctx1.agents.create({ sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } })
+    const a1 = h1.agent
     a1.followup(createUserMessage({ content: [{ type: 'text', text: 'first question' }], source: { kind: 'user' } }))
     await waitForIdle(ctx1, a1)
     const events1 = a1.session.snapshotEvents()
     const seqs1 = events1.map(e => e.seq)
     expect(seqs1).toEqual([...seqs1].sort((x, y) => x - y)) // contiguous
+    await h1.dispose()
     await ctx1.fiber.dispose()
 
     // Lifecycle 2: a brand-new context over the SAME root; resume the session.
-    const adapter2 = new MockAdapter([textResponse('second answer')])
-    const ctx2 = new Context()
-    await ctx2.plugin(LlmRuntime)
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(SessionProjectionRegistry)
-    await ctx2.plugin(SystemPrompt)
-    await ctx2.plugin(ToolRuntime)
-    await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [] })
-    await ctx2.plugin(JsonlSessionPersistence, { root })
-    ctx2.llm.registerAdapter(['mock'], adapter2)
+    const ctx2 = await mountPersistentHarness(root, new MockAdapter([textResponse('second answer')]))
 
     const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('sess-resume') })).agent
     // The resumed session carries the prior history…
@@ -805,8 +1103,74 @@ describe('creation and resume cancellation edges', () => {
     await ctx.fiber.dispose()
   })
 
-  it('releases a restored preparation if the loop becomes inactive before setup', async () => {
-    const sessionId = SessionId('resume-loop-inactive-after-prepare')
+  it('an abort landing between crash repair and publication refuses resume, normalized', async () => {
+    // Cover the publication-time abort backstop: the signal fires AFTER the
+    // raced open settled (during the closer append), so only the final
+    // pre-publication check can refuse.
+    const run = async (suffix: string, reason: unknown): Promise<unknown> => {
+      const sessionId = SessionId(`late-abort-${suffix}`)
+      const { ctx: seedCtx, root } = await persistentHarness(new MockAdapter([]))
+      await seedStoredSession(seedCtx, sessionId, [
+        { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+      ])
+      await seedCtx.fiber.dispose()
+
+      const ctx = await mountPersistentHarness(root, new MockAdapter([]))
+      const controller = new AbortController()
+      const originalOpen = ctx.sessionPersistence.open.bind(ctx.sessionPersistence)
+      ctx.sessionPersistence.open = async (id, access, options) => {
+        const handle = await originalOpen(id, access, options)
+        const realAppend = handle.append.bind(handle)
+        Object.defineProperty(handle, 'append', {
+          value: (events: readonly SessionEvent[]) => {
+            controller.abort(reason)
+            return realAppend(events)
+          },
+        })
+        return handle
+      }
+      const rejection = await ctx.agents.resume({
+        resumeSessionId: sessionId,
+        agentOptions: { provider: 'mock', model: 'mock' },
+        signal: controller.signal,
+      }).then(() => undefined, (error: unknown) => error)
+      expect(ctx.agents.get(sessionId)).toBeUndefined()
+      await ctx.fiber.dispose()
+      return rejection
+    }
+
+    expect(await run('error', new Error('late abort error'))).toMatchObject({ message: 'late abort error' })
+    expect(await run('string', 'late abort string')).toMatchObject({ message: expect.stringMatching(/creation aborted/) as unknown })
+  })
+
+  it('an aborted create closes the write handle its abandoned backend create later resolves', async () => {
+    const sessionId = SessionId('create-abandoned-handle')
+    const { ctx } = await persistentHarness(new MockAdapter([]))
+    const lateCreate = Promise.withResolvers<SessionHandle>()
+    const createStarted = Promise.withResolvers<undefined>()
+    ctx.sessionPersistence.create = () => {
+      createStarted.resolve(undefined)
+      return lateCreate.promise
+    }
+
+    const controller = new AbortController()
+    const creating = ctx.agents.create({ sessionId, signal: controller.signal })
+    await createStarted.promise
+    controller.abort(new Error('caller aborted create'))
+    await expect(creating).rejects.toThrow('caller aborted create')
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+
+    // The abandoned backend create still resolves a real write handle later;
+    // the loop closes it so ownership is not leaked, and a rejecting close is
+    // swallowed — there is no owner left to observe it.
+    const close = vi.fn(async () => { throw new Error('abandoned close failed') })
+    lateCreate.resolve({ append: async () => {}, close } as unknown as SessionHandle)
+    await expect.poll(() => close.mock.calls.length).toBe(1)
+    await ctx.fiber.dispose()
+  })
+
+  it('closes the resume write handle when the loop becomes inactive before setup', async () => {
+    const sessionId = SessionId('resume-loop-inactive-after-open')
     const root = await persistSession(sessionId)
     const ctx = await mountPersistentHarness(root, new MockAdapter([]))
     const loop = ctx.agentLoop as unknown as {
@@ -819,19 +1183,25 @@ describe('creation and resume cancellation edges', () => {
       agentOptions: { provider: 'mock', model: 'mock' },
     })).rejects.toThrow('agent loop is not active')
     expect(ctx.agents.get(sessionId)).toBeUndefined()
+
+    // The already-open handle was closed on the inactive path: a retry can
+    // claim write ownership again.
+    const retry = await ctx.agents.resume({
+      resumeSessionId: sessionId,
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    await retry.dispose()
     await ctx.fiber.dispose()
   })
 
-  it('factory teardown during a hung resume preparation rejects with loop-inactive', async () => {
+  it('factory teardown during a hung resume open rejects promptly and closes the late handle', async () => {
     const sessionId = SessionId('resume-loop-teardown')
     const root = await persistSession(sessionId)
     const ctx = await mountPersistentHarness(root, new MockAdapter([]))
-    const snapshot = await ctx.sessionPersistence.load(sessionId)
-    const abandoned = preparationFromSnapshot(ctx, snapshot)
-    const gate = Promise.withResolvers<SessionPreparation>()
-    const preparationStarted = Promise.withResolvers<undefined>()
-    ctx.sessionPersistence.prepare = () => {
-      preparationStarted.resolve(undefined)
+    const gate = Promise.withResolvers<SessionHandle>()
+    const openStarted = Promise.withResolvers<undefined>()
+    ctx.sessionPersistence.open = () => {
+      openStarted.resolve(undefined)
       return gate.promise
     }
 
@@ -839,28 +1209,29 @@ describe('creation and resume cancellation edges', () => {
       resumeSessionId: sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
     })
-    await preparationStarted.promise
-    // Resolve the preparation only after teardown began: the post-prepare ownership
-    // check, not the abort race, must reject the wrapper.
+    await openStarted.promise
+    // Resolve the open only after teardown began: the abandoned handle must
+    // still be released even though the wrapper already rejected.
     const rejection = expect(promptly(resuming)).rejects.toThrow()
     const disposal = ctx.fiber.dispose()
-    gate.resolve(abandoned)
+    const abandoned = abandonedHandleStub()
+    gate.resolve(abandoned.handle)
     await rejection
     await disposal
-    abandoned[Symbol.dispose]()
+    await expect.poll(() => abandoned.close.mock.calls.length).toBe(1)
   })
 })
 
 describe('configured-start failure edges', () => {
-  it('a non-Error mid-prepare abort reason is wrapped for the resume caller', async () => {
+  it('a non-Error mid-open abort reason is wrapped for the resume caller', async () => {
     const sessionId = SessionId('resume-string-mid-abort')
     const root = await persistSession(sessionId)
     const ctx = await mountPersistentHarness(root, new MockAdapter([]))
     const gate = Promise.withResolvers<never>()
     gate.promise.catch(() => undefined)
-    const preparationStarted = Promise.withResolvers<undefined>()
-    ctx.sessionPersistence.prepare = () => {
-      preparationStarted.resolve(undefined)
+    const openStarted = Promise.withResolvers<undefined>()
+    ctx.sessionPersistence.open = () => {
+      openStarted.resolve(undefined)
       return gate.promise
     }
     const controller = new AbortController()
@@ -870,7 +1241,7 @@ describe('configured-start failure edges', () => {
       agentOptions: { provider: 'mock', model: 'mock' },
       signal: controller.signal,
     })
-    await preparationStarted.promise
+    await openStarted.promise
     controller.abort('operator string reason')
 
     await expect(promptly(resuming)).rejects.toThrow(/creation aborted/)
@@ -881,12 +1252,6 @@ describe('configured-start failure edges', () => {
   it('a failing exact-id restore over an existing artifact stays loud', async () => {
     const sessionId = SessionId('config-existing-corrupt')
     const root = await persistSession(sessionId)
-    const ctx = await mountPersistentHarness(root, new MockAdapter([]))
-    // The artifact exists (list reports it) but its load fails: this is
-    // corruption, not first creation — the failure must be reported, and no
-    // fresh same-id session may shadow the broken one.
-    ctx.sessionPersistence.prepare = () => Promise.reject(new Error('artifact corrupt'))
-
     const configured = new Context()
     await configured.plugin(LlmRuntime)
     await configured.plugin(SessionStore)
@@ -896,43 +1261,31 @@ describe('configured-start failure edges', () => {
     await configured.plugin(AgentRegistry)
     await configured.plugin(JsonlSessionPersistence, { root })
     configured.llm.registerAdapter(['mock'], new MockAdapter([]))
-    configured.sessionPersistence.prepare = (id, signal) => ctx.sessionPersistence.prepare(id, signal)
+    // The artifact exists but its open fails with a NON-NotFound error: this is
+    // corruption, not first creation — the failure must be reported, and no
+    // fresh same-id session may shadow the broken one.
+    configured.sessionPersistence.open = () => Promise.reject(new Error('artifact corrupt'))
     const configFailures: unknown[] = []
     configured.on('agent-loop/config-start-failed', ({ error }) => { configFailures.push(error) })
-    const configWarnings: string[] = []
-    const configWarn = configured.logger.warn.bind(configured.logger)
-    configured.logger.warn = ((...args: unknown[]) => {
-      if (typeof args[0] === 'string') configWarnings.push(args[0])
-      return (configWarn as (...a: unknown[]) => unknown)(...args)
-    }) as typeof configured.logger.warn
+    const warn = vi.spyOn(configured.logger, 'warn').mockImplementation(() => undefined)
+
     const loop = await configured.plugin(AgentLoop, {
       agents: [{ id: 'main', sessionId, provider: 'mock', model: 'mock' }],
     })
     await expect.poll(() => configFailures.length).toBe(1)
     expect(configFailures[0]).toBeInstanceOf(Error)
     expect((configFailures[0] as Error).message).toBe('artifact corrupt')
-    expect(configWarnings.some(w => w.includes('config-driven restore'))).toBe(true)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('config-driven restore'))
     expect(configured.agents.get(sessionId)).toBeUndefined()
+    warn.mockRestore()
 
     await loop.dispose()
     await configured.fiber.dispose()
-    await ctx.fiber.dispose()
   })
 
   it('suppresses a configured-resume failure that lands after teardown', async () => {
     const sessionId = SessionId('config-late-resume-failure')
     const root = await persistSession(sessionId)
-    const ctx = await mountPersistentHarness(root, new MockAdapter([]))
-    const gate = Promise.withResolvers<never>()
-    gate.promise.catch(() => undefined)
-    const preparationStarted = Promise.withResolvers<undefined>()
-    ctx.sessionPersistence.prepare = () => {
-      preparationStarted.resolve(undefined)
-      return gate.promise
-    }
-    const failures: unknown[] = []
-    ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
-
     const configured = new Context()
     await configured.plugin(LlmRuntime)
     await configured.plugin(SessionStore)
@@ -942,12 +1295,19 @@ describe('configured-start failure edges', () => {
     await configured.plugin(AgentRegistry)
     await configured.plugin(JsonlSessionPersistence, { root })
     configured.llm.registerAdapter(['mock'], new MockAdapter([]))
-    configured.sessionPersistence.prepare = (id, signal) => ctx.sessionPersistence.prepare(id, signal)
+    const gate = Promise.withResolvers<never>()
+    gate.promise.catch(() => undefined)
+    const openStarted = Promise.withResolvers<undefined>()
+    configured.sessionPersistence.open = () => {
+      openStarted.resolve(undefined)
+      return gate.promise
+    }
+    const failures: unknown[] = []
     configured.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
     const loop = await configured.plugin(AgentLoop, {
       agents: [{ id: 'main', resumeSessionId: sessionId, provider: 'mock', model: 'mock' }],
     })
-    await preparationStarted.promise
+    await openStarted.promise
     const disposal = loop.dispose()
     gate.reject(new Error('late backend failure'))
     await disposal
@@ -956,6 +1316,5 @@ describe('configured-start failure edges', () => {
     // Ownership deactivated before the failure landed: the report is dropped.
     expect(failures).toEqual([])
     await configured.fiber.dispose()
-    await ctx.fiber.dispose()
   })
 })
diff --git a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
index 6d9e7b33e9..d01049c46f 100644
--- a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
+++ b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
@@ -125,7 +125,7 @@ describe('agent scope lifecycle', () => {
     thrown = createFailure
     let createCaught: unknown
     try {
-      ctx.agentLoop.create(SessionId('unknown-create'))
+      await ctx.agentLoop.create(SessionId('unknown-create'))
     } catch (error: unknown) {
       createCaught = error
     }
@@ -144,7 +144,7 @@ describe('agent scope lifecycle', () => {
 
   it('wires agent.ctx: tagged with the agent, DX field set, ctx.agent safe elsewhere', async () => {
     const ctx = await harness()
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     expect(scopeOf(agent.ctx)).toBe(agent)
     expect(agent.ctx.agent).toBe(agent)
     // The root accessor default: a plain context answers undefined, not a throw.
@@ -197,8 +197,8 @@ describe('agent scope lifecycle', () => {
 
   it('agent.ctx listeners hear only their own agent (scoped dispatch end to end)', async () => {
     const ctx = await harness(new MockAdapter([textResponse('one'), textResponse('two')]))
-    const a = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
-    const b = ctx.agentLoop.create(SessionId('b'), { provider: 'mock', model: 'mock' })
+    const a = await ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
+    const b = await ctx.agentLoop.create(SessionId('b'), { provider: 'mock', model: 'mock' })
 
     const heard: string[] = []
     a.ctx.on('agent/status', ({ agent: subject, status }) => void heard.push(`a-sees:${subject.id}:${status}`))
@@ -516,7 +516,7 @@ describe('agent scope lifecycle', () => {
     await ctx.fiber.dispose()
   })
 
-  it('synchronous create rechecks provider liveness before its first publication edge', async () => {
+  it('create rechecks provider liveness before its first publication edge', async () => {
     const { ctx, loopFiber } = await harnessWithLoop()
     const sessionsBefore = ctx.sessions.list().length
     let unloaded = false
@@ -527,20 +527,23 @@ describe('agent scope lifecycle', () => {
       unloading = loopFiber.dispose()
     })
 
-    ctx.agentLoop.create(SessionId('config-scope-race'), { provider: 'mock', model: 'mock' })
+    // The mid-setup unload races publication: create either rejects or its
+    // published agent is torn straight back down — both leave no state.
+    await ctx.agentLoop.create(SessionId('config-scope-race'), { provider: 'mock', model: 'mock' })
+      .then(() => undefined, () => undefined)
     await unloading
     expect(ctx.agents.get(SessionId('config-scope-race')) === undefined).toBe(true)
     expect(ctx.sessions.list().length).toBe(sessionsBefore)
     await ctx.fiber.dispose()
   })
 
-  it('synchronous create leaves no lifecycle state when session preparation fails', async () => {
+  it('create leaves no lifecycle state when session preparation fails', async () => {
     const ctx = await harness()
     const id = SessionId('config-prepare-failure')
 
-    expect(() => ctx.agentLoop.create(id, { provider: 'mock', model: 'mock' }, { cwd: 'relative' }))
-      .toThrow(/absolute path/)
-    const replacement = ctx.agentLoop.create(id, { provider: 'mock', model: 'mock' }, { cwd: '/recovered' })
+    await expect(ctx.agentLoop.create(id, { provider: 'mock', model: 'mock' }, { cwd: 'relative' }))
+      .rejects.toThrow(/absolute path/)
+    const replacement = await ctx.agentLoop.create(id, { provider: 'mock', model: 'mock' }, { cwd: '/recovered' })
     expect(ctx.agents.get(id)).toBe(replacement)
     await replacement.whenIdle()
     await ctx.fiber.dispose()
@@ -884,7 +887,7 @@ describe('agent scope lifecycle', () => {
     expect(ctx.sessions.get(SessionId('partial-session'))).toBeUndefined()
   })
 
-  it('the synchronous config helper rolls back when publication throws', async () => {
+  it('the config create helper rolls back when publication throws', async () => {
     const ctx = await harness()
     const sessionsBefore = ctx.sessions.list().length
     let boom = true
@@ -895,8 +898,8 @@ describe('agent scope lifecycle', () => {
       }
     })
 
-    expect(() => ctx.agentLoop.create(SessionId('config-bad'), { provider: 'mock', model: 'mock' }))
-      .toThrow('config publish failed')
+    await expect(ctx.agentLoop.create(SessionId('config-bad'), { provider: 'mock', model: 'mock' }))
+      .rejects.toThrow('config publish failed')
     await expect.poll(() => ctx.agents.get(SessionId('config-bad')) === undefined).toBe(true)
     await expect.poll(() => ctx.sessions.list().length).toBe(sessionsBefore)
   })
@@ -910,8 +913,8 @@ describe('agent scope lifecycle', () => {
 
   it('agentEvents fuses carrier and subject for custom drivers', async () => {
     const ctx = await harness()
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    const other = ctx.agentLoop.create(SessionId('a2'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const other = await ctx.agentLoop.create(SessionId('a2'), { provider: 'mock', model: 'mock' })
     const heard: string[] = []
     agent.ctx.on('agent/error', ({ agent: subject, turn }) => void heard.push(`${subject.id}:${turn}`))
 
diff --git a/packages/core/agent-loop/tests/shutdown-drain.spec.ts b/packages/core/agent-loop/tests/shutdown-drain.spec.ts
new file mode 100644
index 0000000000..5ab7dc46c2
--- /dev/null
+++ b/packages/core/agent-loop/tests/shutdown-drain.spec.ts
@@ -0,0 +1,69 @@
+/** Root-fiber shutdown drains buffered session events durably (both mount orders). */
+
+import { describe, expect, it, afterEach } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import LlmRuntime from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRuntime from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter, textResponse } from './mock-adapter.ts'
+
+const dirs: string[] = []
+afterEach(async () => { for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true }) })
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
+      if (subject === agent && status === 'idle') { dispose(); resolve() }
+    })
+  })
+}
+
+async function mount(order: 'backend-first' | 'loop-first'): Promise<{ ctx: Context; root: string }> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-shutdown-drain-'))
+  dirs.push(root)
+  const ctx = new Context()
+  await ctx.plugin(LlmRuntime)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionProjectionRegistry)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRuntime)
+  await ctx.plugin(AgentRegistry)
+  if (order === 'backend-first') {
+    await ctx.plugin(JsonlSessionPersistence, { root })
+    await ctx.plugin(AgentLoop, { agents: [] })
+  } else {
+    await ctx.plugin(AgentLoop, { agents: [] })
+    await ctx.plugin(JsonlSessionPersistence, { root })
+  }
+  ctx.llm.registerAdapter(['mock'], new MockAdapter([textResponse('done')]))
+  return { ctx, root }
+}
+
+describe.each(['backend-first', 'loop-first'] as const)('root shutdown drain (%s)', (order) => {
+  it('persists buffered turn events without an explicit flush before dispose', async () => {
+    const { ctx, root } = await mount(order)
+    const sessionId = SessionId('shutdown-drain')
+    const handle = await ctx.agents.create({ sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
+    handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, handle.agent)
+    // No explicit flush and no agent dispose: root teardown must drain.
+    await ctx.fiber.dispose()
+
+    const verify = new Context()
+    await verify.plugin(JsonlSessionPersistence, { root })
+    const reader = await verify.sessionPersistence.open(sessionId, 'read')
+    const events = await reader.read()
+    await reader.close()
+    expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'completed' } } })
+    await verify.fiber.dispose()
+  })
+})
diff --git a/packages/core/agent-loop/tests/tool-calls.spec.ts b/packages/core/agent-loop/tests/tool-calls.spec.ts
index cc079ca291..0697224e70 100644
--- a/packages/core/agent-loop/tests/tool-calls.spec.ts
+++ b/packages/core/agent-loop/tests/tool-calls.spec.ts
@@ -107,7 +107,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
     const ctx = await harness(adapter)
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 3)
@@ -136,7 +136,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
       name: 'w', description: 'write', parameters: { id: { type: 'string', required: true } },
       async execute(args) { order.push(`w-${args.id}`); return [{ type: 'text', text: 'w' }] },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -171,7 +171,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
         return [{ type: 'text', text: 'replaced' }]
       },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => replacement.started.length === 1)
@@ -202,7 +202,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
       disposeInitial()
       ctx.tools.register(replacement.tool)
     })
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => initial.started.length === 2)
@@ -228,7 +228,7 @@ describe('tool-call scheduler: model-order results despite out-of-order settleme
     const ctx = await harness(adapter)
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 2)
@@ -251,7 +251,7 @@ describe('tool-call scheduler: model-order results despite out-of-order settleme
     const ctx = await harness(adapter)
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 2)
     gated.release('2'); gated.release('1')
@@ -300,7 +300,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     const ctx = await harness(adapter, 2)
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 2)
@@ -332,7 +332,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     const ctx = await harness(adapter, 1)
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 1)
     await new Promise(r => setTimeout(r, 5))
@@ -359,7 +359,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     ctx.llm.registerAdapter(['mock'], adapter)
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 1)
     await new Promise(r => setTimeout(r, 5))
@@ -385,7 +385,7 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
     const post: string[] = []
     ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => { pre.push(String(exec.callId)); return next() })
     ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => { post.push(String(exec.callId)); return next() })
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 3)
@@ -408,7 +408,7 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
       ({ kind: 'accept', additionalContexts: [createUserMessage({
         content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' },
       })] }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 2)
@@ -446,7 +446,7 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
       post.push(String(exec.callId))
       return next()
     })
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 1)
@@ -471,7 +471,7 @@ describe('tool-call scheduler: abort handling', () => {
     const ctx = await harness(adapter)
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('session/event', (session, event) => {
       if (session === agent.session && event.type === 'assistant/message') {
         agent.cancel({ kind: 'user' })
@@ -502,7 +502,7 @@ describe('tool-call scheduler: abort handling', () => {
     const ctx = await harness(adapter)
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
       if (exec.callId === ToolCallId('c1')) {
         agent.cancel({ kind: 'user' })
@@ -540,7 +540,7 @@ describe('tool-call scheduler: abort handling', () => {
         content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' },
       })],
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 2)
@@ -613,7 +613,7 @@ describe('tool-call scheduler: abort handling', () => {
       parameters: { id: { type: 'string', required: true } },
       async execute(args) { exclusive.push(args.id); return [{ type: 'text', text: 'x' }] },
     }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await until(() => gated.started.length === 2)
@@ -669,7 +669,7 @@ describe('tool-call scheduler: failure quiescence', () => {
     scheduler.dispatch = exec => exec.callId === ToolCallId('c1')
       ? new Promise((_resolve, reject) => { rejectFirst = reject })
       : dispatch(exec).then(() => { throw drainedError })
-    const agent = ctx.agentLoop.create(SessionId('scheduler-failure'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('scheduler-failure'), { provider: 'mock', model: 'mock' })
     let idle = false
     const idlePromise = waitForIdle(ctx, agent).then(() => { idle = true })
 
@@ -748,7 +748,7 @@ describe('PTC mode native-tool denial through the agent loop', () => {
     const ctx = await ptcModeHarness(adapter)
     ctx.tools.register(tool)
 
-    const agent = ctx.agentLoop.create(SessionId('code-native'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('code-native'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'write a file' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
diff --git a/packages/core/agent-loop/tests/tool-order.spec.ts b/packages/core/agent-loop/tests/tool-order.spec.ts
index e7ffe77a5c..15e1a8574d 100644
--- a/packages/core/agent-loop/tests/tool-order.spec.ts
+++ b/packages/core/agent-loop/tests/tool-order.spec.ts
@@ -60,7 +60,7 @@ async function runTurn(registrationOrder: string[], toolOrder?: SystemPromptConf
   const adapter = new MockAdapter([textResponse('done')])
   const ctx = await harness(adapter, toolOrder)
   for (const name of registrationOrder) registerNamed(ctx, name)
-  const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+  const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
   agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
   await waitForIdle(ctx, agent)
   return { ctx, agent, adapter }
@@ -99,7 +99,7 @@ describe('loop-level canonical tool order', () => {
     const adapter = new MockAdapter([textResponse('never sent')])
     const ctx = await harness(adapter, ['ghost', TOOL_ORDER_REST])
     registerNamed(ctx, 'alpha')
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(0)
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 6e3db1edb0..7df60db27c 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -194,11 +194,12 @@ export interface AgentFactory {
    */
   createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
   /**
-   * Prepare a persisted session and resume an agent on it. Async because it awaits
-   * both `ctx.sessionPersistence.prepare` and the optional unpublished setup
-   * transaction; must be called after that service exists (consumers inject
-   * `sessionPersistence`). Publication follows the same setup-commit and
-   * ordered boundary as {@link createAgent}.
+   * Resume an agent on a persisted session. Async because it opens the
+   * persisted session for write, reads and repairs the log, publishes it, and
+   * awaits the optional unpublished setup transaction; must be called after
+   * `ctx.sessionPersistence` exists (consumers inject `sessionPersistence`).
+   * Publication follows the same setup-commit and ordered boundary as
+   * {@link createAgent}.
    * @param ownerCtx - caller-bound context that owns load, setup, and the live handle.
    * @param options - persisted identity, configuration, and optional setup.
    * @returns the owned handle after setup, both announcements, and loop start complete.
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index c55cc5fb6a..59e198db44 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -850,8 +850,9 @@ export class SessionForkError extends Error {
 /**
  * In-memory session store (`ctx.sessions`).
  *
- * Persistence is intentionally not implemented here — persistence plugins
- * subscribe to `session/event` and flush on `session/flush` / dispose.
+ * Persistence is intentionally not implemented here — the agent lifecycle
+ * attaches a session-log writer to each published session's write handle;
+ * a session published outside that lifecycle persists nothing.
  */
 export class SessionStore extends Service {
   private store = new Map<SessionId, SessionEntry>()
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index 461c31ad36..c27cd4d98e 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -205,8 +205,10 @@ export interface TurnEndReasonMap {
   /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */
   'max-tokens': { kind: 'max-tokens' }
   /**
-   * A persistence backend closed a crash-orphaned turn on reload. The loop never
-   * emits this marker, and the events recorded before the crash remain intact.
+   * A crash-orphaned turn was closed after the fact: agent-loop resume appends
+   * this closer for a stored log whose last turn never ended, and session-query
+   * synthesizes it on cold reads. The loop never emits this marker live, and
+   * the events recorded before the crash remain intact.
    */
   interrupted: { kind: 'interrupted' }
 }
diff --git a/packages/experimental/agent-team/src/mailbox.ts b/packages/experimental/agent-team/src/mailbox.ts
index 0f71a4da37..0bb7a5a75a 100644
--- a/packages/experimental/agent-team/src/mailbox.ts
+++ b/packages/experimental/agent-team/src/mailbox.ts
@@ -12,6 +12,7 @@ import { queueHostSubagentPrompt } from '@deepseek-ai/dsh-subagent/internal'
 import { errorMessage, TeamError } from './error.ts'
 import type { TeamJournal } from './journal.ts'
 import type { TeamRuntimeLifecycle } from './lifecycle.ts'
+import { readPersistedSession } from './persisted.ts'
 import type { TeamRoster } from './roster.ts'
 import { resolveActiveMember } from './roster.ts'
 import { messageAccepted } from './session-message.ts'
@@ -308,7 +309,8 @@ export class TeamMailbox {
 
   /** Whether a target Session already contains the durable message identity. */
   private targetRecorded(session: Session, messageId: TeamMessageId): boolean {
-    return messageAccepted(session.ownEvents(), message => message.source.kind === 'team-message'
+    const suffix = session.snapshotEvents(session.inheritedEventCount)
+    return messageAccepted(suffix, message => message.source.kind === 'team-message'
       && message.source.messageId === messageId)
   }
 
@@ -320,19 +322,19 @@ export class TeamMailbox {
     ]
   }
 
-  /** Inspect an inactive target before cold resume; uncertainty keeps the mailbox queued. */
+  /** Read an inactive target's durable log before cold resume; uncertainty keeps the mailbox queued. */
   private async persistedTargetRecorded(
     targetId: SessionId,
     messageId: TeamMessageId,
     signal: AbortSignal,
   ): Promise<boolean | undefined> {
     try {
-      const stored = await this.ctx.sessionPersistence.inspect(targetId, signal)
+      const stored = await readPersistedSession(this.ctx.sessionPersistence, targetId, signal)
       const suffix = stored.events.slice(stored.inheritedEventCount)
       return messageAccepted(suffix, message => message.source.kind === 'team-message'
         && message.source.messageId === messageId)
     } catch (error: unknown) {
-      this.ctx.logger.warn(`cannot inspect Team message target "${targetId}": ${errorMessage(error)}`)
+      this.ctx.logger.warn(`cannot read Team message target "${targetId}": ${errorMessage(error)}`)
       return undefined
     }
   }
diff --git a/packages/experimental/agent-team/src/persisted.ts b/packages/experimental/agent-team/src/persisted.ts
new file mode 100644
index 0000000000..4d4da6d9a3
--- /dev/null
+++ b/packages/experimental/agent-team/src/persisted.ts
@@ -0,0 +1,33 @@
+/** Short-lived read-handle access to persisted Team member Sessions. */
+
+import type { SessionEvent, SessionHeader, SessionId , SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+
+/** One persisted Session's detached header and complete committed event log. */
+export interface PersistedSessionView {
+  /** Exact fork-inherited event count paired with `header`. */
+  readonly inheritedEventCount: SessionLogOffset
+  readonly header: SessionHeader
+  readonly events: readonly SessionEvent[]
+}
+
+/**
+ * Read one stored session's header and complete event log through a
+ * short-lived read handle, closing the handle before returning.
+ * @param persistence - the durable session store.
+ * @param id - the stored session to read.
+ * @param signal - cancellation observed by open and read.
+ * @returns the stored header and every committed event.
+ */
+export async function readPersistedSession(
+  persistence: SessionPersistence,
+  id: SessionId,
+  signal: AbortSignal,
+): Promise<PersistedSessionView> {
+  const handle = await persistence.open(id, 'read', { signal })
+  try {
+    return { header: handle.header, inheritedEventCount: handle.inheritedEventCount, events: await handle.read(0, undefined, { signal }) }
+  } finally {
+    await handle.close()
+  }
+}
diff --git a/packages/experimental/agent-team/src/roster.ts b/packages/experimental/agent-team/src/roster.ts
index 5035d2209a..7ff934b150 100644
--- a/packages/experimental/agent-team/src/roster.ts
+++ b/packages/experimental/agent-team/src/roster.ts
@@ -11,6 +11,7 @@ import type { ContinuableStart } from '@deepseek-ai/dsh-subagent'
 import { errorMessage, TeamError } from './error.ts'
 import type { TeamJournal } from './journal.ts'
 import type { TeamRuntimeLifecycle } from './lifecycle.ts'
+import { readPersistedSession } from './persisted.ts'
 import type { TeamState } from './projection.ts'
 import { messageAccepted } from './session-message.ts'
 import { TeamId } from './types.ts'
@@ -345,7 +346,7 @@ export class TeamRoster {
       signal.throwIfAborted()
       const session = this.ctx.sessions.get(childId)
       if (session === undefined) {
-        const stored = await this.ctx.sessionPersistence.inspect(childId, signal)
+        const stored = await readPersistedSession(this.ctx.sessionPersistence, childId, signal)
         const suffix = stored.events.slice(stored.inheritedEventCount)
         if (messageAccepted(suffix, message => message.id === messageId)) return
         throw new TeamError(
@@ -374,7 +375,7 @@ export class TeamRoster {
       try {
         signal.throwIfAborted()
         await this.ctx.sessions.flush(session)
-        const suffix = session.ownEvents()
+        const suffix = session.snapshotEvents(session.inheritedEventCount)
         if (messageAccepted(suffix, message => message.id === messageId)) return
         if (this.ctx.sessions.get(childId) !== session) continue
         await progress.promise
@@ -397,11 +398,11 @@ export class TeamRoster {
       let phase: 'active' | 'failed' = 'failed'
       let failure = 'provisioning did not leave a resumable child Session'
       try {
-        const loaded = await this.ctx.sessionPersistence.inspect(member.id, signal)
+        const loaded = await readPersistedSession(this.ctx.sessionPersistence, member.id, signal)
         const suffix = loaded.events.slice(loaded.inheritedEventCount)
         const descriptor = foldSubagentDescriptor(suffix)
         const acceptedInitialPrompt = messageAccepted(suffix, message => message.source.kind === 'user')
-        if (loaded.meta.parentSession === root.id
+        if (loaded.header.parentSession === root.id
           && descriptor?.mode === 'continuable'
           && descriptor.provider === member.provider
           && acceptedInitialPrompt) {
@@ -481,6 +482,6 @@ export class TeamRoster {
 
   /** Whether a Session's own suffix identifies a provider-owned subagent child. */
   private subagentDescriptor(agent: Agent): boolean {
-    return foldSubagentDescriptor(agent.session.ownEvents()) !== undefined
+    return foldSubagentDescriptor(agent.session.snapshotEvents(agent.session.inheritedEventCount)) !== undefined
   }
 }
diff --git a/packages/experimental/agent-team/tests/persistence.spec.ts b/packages/experimental/agent-team/tests/persistence.spec.ts
index fb115719aa..715d83c440 100644
--- a/packages/experimental/agent-team/tests/persistence.spec.ts
+++ b/packages/experimental/agent-team/tests/persistence.spec.ts
@@ -9,6 +9,7 @@ import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SubagentService, { seedDescriptorTurn, snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent'
@@ -41,6 +42,16 @@ function durable(agent: Agent): {
   }
 }
 
+/** Read one stored session's full event log through a short-lived read handle. */
+async function storedEvents(ctx: Context, id: SessionId): Promise<readonly SessionEvent[]> {
+  const handle = await ctx.sessionPersistence.open(id, 'read')
+  try {
+    return await handle.read()
+  } finally {
+    await handle.close()
+  }
+}
+
 async function disposeContext(ctx: Context): Promise<void> {
   try {
     await ctx.fiber.dispose()
@@ -118,7 +129,7 @@ function provisioning(childId: SessionId, name: string): TeamMemberSnapshot {
   }
 }
 
-function persistedChild(
+async function persistedChild(
   ctx: Context,
   rootId: SessionId,
   childId: SessionId,
@@ -140,6 +151,11 @@ function persistedChild(
     start: 0,
     inserted: [message],
   })
+  // Live sessions persist only through an attached agent-loop writer; this
+  // bare fixture session seeds its durable log directly for the cold restart.
+  const handle = await ctx.sessionPersistence.create(child.header)
+  await handle.append(child.snapshotEvents())
+  await handle.close()
   return child
 }
 
@@ -154,8 +170,8 @@ for (const backend of backends) {
       const activeRootId = SessionId(`${backend.name.toLowerCase()}-active-root`)
       const failedRootId = SessionId(`${backend.name.toLowerCase()}-failed-root`)
       const childId = SessionId(`${backend.name.toLowerCase()}-child`)
-      const activeRoot = first.ctx.agentLoop.create(activeRootId, { provider: 'mock', model: 'mock' })
-      const failedRoot = first.ctx.agentLoop.create(failedRootId, { provider: 'mock', model: 'mock' })
+      const activeRoot = await first.ctx.agentLoop.create(activeRootId, { provider: 'mock', model: 'mock' })
+      const failedRoot = await first.ctx.agentLoop.create(failedRootId, { provider: 'mock', model: 'mock' })
       // Let each root's startup recovery observe the empty initial log before
       // simulating the crash-only provisioning prefix.
       await Promise.resolve()
@@ -186,7 +202,7 @@ for (const backend of backends) {
         signal: SIGNAL,
       })
       await vi.waitFor(() => { expect(first.ctx.agents.get(childId)).toBeUndefined() }, { timeout: 5_000 })
-      expect((await first.ctx.sessionPersistence.inspect(childId)).events
+      expect((await storedEvents(first.ctx, childId))
         .some(event => event.type === 'user/message')).toBe(true)
       await first.dispose()
 
@@ -229,7 +245,7 @@ for (const backend of backends) {
       const rootId = SessionId(`${backend.name.toLowerCase()}-pending-root`)
       const childId = SessionId(`${backend.name.toLowerCase()}-pending-child`)
       const first = await stack(backend, storageRoot, [])
-      const root = first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
+      const root = await first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
       await Promise.resolve()
       await Promise.resolve()
       root.session.append('team/member', {
@@ -241,11 +257,8 @@ for (const backend of backends) {
         content: [{ type: 'text', text: 'durably pending initial task' }],
         source: { kind: 'user' },
       })
-      const child = persistedChild(first.ctx, rootId, childId, initial)
-      await Promise.all([
-        first.ctx.sessions.flush(root.session),
-        first.ctx.sessions.flush(child),
-      ])
+      await persistedChild(first.ctx, rootId, childId, initial)
+      await first.ctx.sessions.flush(root.session)
       await first.dispose()
 
       const second = await stack(backend, storageRoot, [])
@@ -257,8 +270,8 @@ for (const backend of backends) {
         expect(durable(rootHandle.agent).members[0]?.phase).toBe('active')
       })
       expect(second.adapter.requests).toEqual([])
-      const stored = await second.ctx.sessionPersistence.inspect(childId)
-      expect(stored.events.some(event => event.type === 'agent/inbox/spliced'
+      const stored = await storedEvents(second.ctx, childId)
+      expect(stored.some(event => event.type === 'agent/inbox/spliced'
         && event.data.inserted.some(message => message.id === initial.id))).toBe(true)
 
       await rootHandle.dispose()
@@ -273,7 +286,7 @@ for (const backend of backends) {
       const rootId = SessionId(`${backend.name.toLowerCase()}-mail-root`)
 
       const first = await stack(backend, storageRoot, [textResponse('initial teammate answer')])
-      const firstLead = first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
+      const firstLead = await first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
       const started = await first.ctx.agentTeams.spawnTeammate(firstLead, {
         name: 'mail-worker',
         description: 'mail recovery worker',
@@ -314,8 +327,8 @@ for (const backend of backends) {
       await vi.waitFor(() => { expect(second.ctx.agents.get(started.member.id)).toBeUndefined() }, { timeout: 5_000 })
       await vi.waitFor(() => { expect(durable(rootHandle.agent).pendingMessages).toEqual([]) })
 
-      const child = await second.ctx.sessionPersistence.inspect(started.member.id)
-      const peerIds = child.events.flatMap(event => event.type === 'user/message'
+      const child = await storedEvents(second.ctx, started.member.id)
+      const peerIds = child.flatMap(event => event.type === 'user/message'
         && event.data.source.kind === 'team-message'
         ? [event.data.source.messageId]
         : [])
@@ -334,7 +347,7 @@ for (const backend of backends) {
       const messageId = TeamMessageId(`${backend.name.toLowerCase()}-recorded-message`)
 
       const first = await stack(backend, storageRoot, [textResponse('initial teammate answer')])
-      const firstLead = first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
+      const firstLead = await first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
       const started = await first.ctx.agentTeams.spawnTeammate(firstLead, {
         name: 'dedup-worker',
         description: 'mail deduplication worker',
@@ -394,8 +407,8 @@ for (const backend of backends) {
       expect(second.ctx.agents.get(started.member.id)).toBeUndefined()
       expect(second.adapter.requests).toEqual([])
 
-      const child = await second.ctx.sessionPersistence.inspect(started.member.id)
-      const occurrences = child.events.filter(event => event.type === 'user/message'
+      const child = await storedEvents(second.ctx, started.member.id)
+      const occurrences = child.filter(event => event.type === 'user/message'
         && event.data.source.kind === 'team-message'
         && event.data.source.messageId === messageId)
       expect(occurrences).toHaveLength(1)
@@ -413,7 +426,7 @@ for (const backend of backends) {
       const childId = SessionId(`${backend.name.toLowerCase()}-inbox-child`)
       const messageId = TeamMessageId(`${backend.name.toLowerCase()}-pending-team-message`)
       const first = await stack(backend, storageRoot, [])
-      const root = first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
+      const root = await first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
       await Promise.resolve()
       await Promise.resolve()
       const provisioned = provisioning(childId, 'pending-mail-worker')
@@ -454,11 +467,8 @@ for (const backend of backends) {
           senderName: 'lead',
         },
       })
-      const child = persistedChild(first.ctx, rootId, childId, pending)
-      await Promise.all([
-        first.ctx.sessions.flush(root.session),
-        first.ctx.sessions.flush(child),
-      ])
+      await persistedChild(first.ctx, rootId, childId, pending)
+      await first.ctx.sessions.flush(root.session)
       await first.dispose()
 
       const second = await stack(backend, storageRoot, [])
@@ -471,8 +481,8 @@ for (const backend of backends) {
       })
       expect(second.adapter.requests).toEqual([])
       expect(second.ctx.agents.get(childId)).toBeUndefined()
-      const stored = await second.ctx.sessionPersistence.inspect(childId)
-      const pendingCopies = stored.events.flatMap(event => event.type === 'agent/inbox/spliced'
+      const stored = await storedEvents(second.ctx, childId)
+      const pendingCopies = stored.flatMap(event => event.type === 'agent/inbox/spliced'
         ? event.data.inserted.filter(message => message.source.kind === 'team-message'
           && message.source.messageId === messageId)
         : [])
diff --git a/packages/experimental/agent-team/tests/team.spec.ts b/packages/experimental/agent-team/tests/team.spec.ts
index 013d6f4cce..33a0426772 100644
--- a/packages/experimental/agent-team/tests/team.spec.ts
+++ b/packages/experimental/agent-team/tests/team.spec.ts
@@ -7,7 +7,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { SessionId, type Session } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset, SessionId, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SubagentService from '@deepseek-ai/dsh-subagent'
@@ -46,6 +46,16 @@ function durable(agent: Agent): {
   }
 }
 
+/** Read one stored session's full event log through a short-lived read handle. */
+async function storedEvents(ctx: Context, id: SessionId): Promise<readonly SessionEvent[]> {
+  const handle = await ctx.sessionPersistence.open(id, 'read')
+  try {
+    return await handle.read()
+  } finally {
+    await handle.close()
+  }
+}
+
 async function setup(
   script: ConstructorParameters<typeof MockAdapter>[0],
   config: ConstructorParameters<typeof TeamService>[1] = {},
@@ -64,7 +74,7 @@ async function setup(
   const teamFiber = await ctx.plugin(TeamService, config)
   const adapter = new MockAdapter(script)
   ctx.llm.registerAdapter(['mock'], adapter)
-  const lead = ctx.agentLoop.create(SessionId('lead'), { provider: 'mock', model: 'mock' })
+  const lead = await ctx.agentLoop.create(SessionId('lead'), { provider: 'mock', model: 'mock' })
   return { ctx, lead, adapter, storageRoot, teamFiber }
 }
 
@@ -166,7 +176,7 @@ describe('Team identity and provisioning', () => {
     await ctx.plugin(JsonlSessionPersistence, { root: storageRoot })
     await ctx.plugin(AgentLoop, { agents: [] })
     await ctx.plugin(SubagentService)
-    const lead = ctx.agentLoop.create(SessionId('preexisting-lead'), {})
+    const lead = await ctx.agentLoop.create(SessionId('preexisting-lead'), {})
     const service = new TeamService(ctx)
 
     expect(service.listMembers(lead)).toEqual([expect.objectContaining({
@@ -210,12 +220,8 @@ describe('Team identity and provisioning', () => {
     const fresh = await spawn(ctx, lead, 'fresh-worker')
     await waitNoAgent(ctx, fresh.member.id)
 
-    const forkedInspection = await ctx.sessionPersistence.inspect(forked.member.id)
-    const freshInspection = await ctx.sessionPersistence.inspect(fresh.member.id)
-    expect(forkedInspection.meta.isSeeded).toBe(true)
-    expect(forkedInspection.inheritedEventCount).toBeGreaterThan(0)
-    expect(freshInspection.meta.isSeeded).toBe(false)
-    expect(freshInspection.inheritedEventCount).toBe(0)
+    expect((await ctx.sessionPersistence.stat(forked.member.id))?.header.isSeeded).toBe(true)
+    expect((await ctx.sessionPersistence.stat(fresh.member.id))?.header.isSeeded).toBe(false)
     expect(ctx.agentTeams.listMembers(lead).map(row => [row.name, row.context, row.status])).toEqual([
       ['lead', undefined, 'idle'],
       ['fork-worker', 'fork', 'inactive'],
@@ -264,6 +270,11 @@ describe('Team identity and provisioning', () => {
       target: 'next-turn', start: 0, inserted: [initial],
     })
     await checkpoint
+    // Live sessions persist only through an attached agent-loop writer; this
+    // bare fixture session seeds its durable log directly for the cold reread.
+    const persisted = await ctx.sessionPersistence.create(liveSession.header)
+    await persisted.append(liveSession.snapshotEvents())
+    await persisted.close()
     await liveFiber.dispose()
 
     await expect(internal.checkpointInitialPrompt(liveSession.id, initial.id, SIGNAL)).resolves.toBeUndefined()
@@ -462,8 +473,8 @@ describe('Team identity and provisioning', () => {
     const handle = await ctx.agents.create({
       sessionId: SessionId('ordinary-fork'),
       seed: lead.session.snapshotEvents(),
-      inheritedEventCount: lead.session.seq,
       meta: { parentSession: lead.id, isSeeded: true },
+      inheritedEventCount: SessionLogOffset(lead.session.seq),
       agentOptions: { provider: 'mock', model: 'mock' },
     })
 
@@ -967,8 +978,8 @@ describe('Team mailbox and waiting', () => {
     expect(durable(lead).pendingMessages).toEqual([])
 
     const messageIds = new Set([first.messageId, second.messageId])
-    const persisted = await ctx.sessionPersistence.inspect(lead.id)
-    const receiptOrder = persisted.events.flatMap((event) => {
+    const persisted = await storedEvents(ctx, lead.id)
+    const receiptOrder = persisted.flatMap((event) => {
       if (event.type === 'agent/inbox/spliced' && event.data.inserted.some(message =>
         message.source.kind === 'team-message' && messageIds.has(message.source.messageId))) {
         return ['agent/inbox/spliced']
@@ -1248,12 +1259,12 @@ describe('Team mailbox and waiting', () => {
 
     const inactiveStarted = await spawn(ctx, lead, 'inactive-target')
     await waitNoAgent(ctx, inactiveStarted.member.id)
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect').mockRejectedValueOnce(new Error('inspect unavailable'))
+    const openRead = vi.spyOn(ctx.sessionPersistence, 'open').mockRejectedValueOnce(new Error('read unavailable'))
     const uncertain = await ctx.agentTeams.sendMessage(lead, {
       target: 'inactive-target', content: content('inspection failure'), delivery: 'wakeup', signal: SIGNAL,
     })
     expect(uncertain.status).toBe('queued')
-    inspect.mockRestore()
+    openRead.mockRestore()
 
     vi.spyOn(ctx.subagents as unknown as HostPromptQueue, queueSubagentPrompt)
       .mockRejectedValueOnce(new Error('delivery unavailable'))
@@ -1261,7 +1272,7 @@ describe('Team mailbox and waiting', () => {
       target: 'inactive-target', content: content('delivery failure'), delivery: 'wakeup', signal: SIGNAL,
     })
     expect(failed.status).toBe('queued')
-    expect(warnings.some(warning => warning.includes('inspect unavailable'))).toBe(true)
+    expect(warnings.some(warning => warning.includes('read unavailable'))).toBe(true)
     expect(warnings.some(warning => warning.includes('delivery unavailable'))).toBe(true)
 
     ctx.agentTeams.interrupt(lead, 'live-target')
@@ -1287,8 +1298,8 @@ describe('Team mailbox and waiting', () => {
     await waitNoAgent(ctx, betaStarted.member.id)
     await vi.waitFor(() => { expect(durable(lead).pendingMessages).toEqual([]) })
 
-    const stored = await ctx.sessionPersistence.inspect(betaStarted.member.id)
-    const peerMessages = stored.events.filter(event => event.type === 'user/message'
+    const stored = await storedEvents(ctx, betaStarted.member.id)
+    const peerMessages = stored.filter(event => event.type === 'user/message'
       && event.data.source.kind === 'team-message')
     expect(peerMessages.map((event) => {
       if (event.type !== 'user/message') return undefined
@@ -1369,7 +1380,7 @@ describe('Team mailbox and waiting', () => {
     await ctx.plugin(SubagentService)
     const fiber = await ctx.plugin(TeamService)
     const service = ctx.agentTeams
-    const lead = ctx.agentLoop.create(SessionId('wait-lead'), {})
+    const lead = await ctx.agentLoop.create(SessionId('wait-lead'), {})
 
     await expect(service.waitForChange(lead, 9_999, SIGNAL))
       .rejects.toMatchObject({ code: 'TEAM_INVALID_TIMEOUT' })
@@ -1787,7 +1798,7 @@ describe('Team mailbox and waiting', () => {
     })
     const entered = Promise.withResolvers<undefined>()
     const release = Promise.withResolvers<undefined>()
-    vi.spyOn(second.ctx.sessionPersistence, 'inspect').mockImplementationOnce(async () => {
+    vi.spyOn(second.ctx.sessionPersistence, 'open').mockImplementationOnce(async () => {
       entered.resolve(undefined)
       await release.promise
       throw new Error('late inspection failure')
diff --git a/packages/experimental/agent-team/tests/test-session-query.ts b/packages/experimental/agent-team/tests/test-session-query.ts
index 903626c082..a2315452cd 100644
--- a/packages/experimental/agent-team/tests/test-session-query.ts
+++ b/packages/experimental/agent-team/tests/test-session-query.ts
@@ -1,9 +1,55 @@
 /** Minimal concrete Session query for Agent Team continuation tests. */
 
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import SessionQueryEngine from '@deepseek-ai/dsh-session-query'
+import type { SessionObservation, SessionObservationOptions } from '@deepseek-ai/dsh-session-query'
+
+/** Undisposable immutable cut over one session's header and events. */
+function cut(
+  source: 'live' | 'prepared',
+  header: SessionHeader,
+  events: readonly SessionEvent[],
+): SessionObservation {
+  const lease = (): SessionObservation => ({
+    source,
+    header,
+    inheritedEventCount: SessionLogOffset(0),
+    events,
+    cursor: events.at(-1)?.seq ?? -1,
+    retain: lease,
+    [Symbol.dispose]: () => {},
+  })
+  return lease()
+}
 
 /** Session query implementation whose search faces are outside these tests. */
 export class TestSessionQuery extends SessionQueryEngine {
+  static override inject = ['sessions', 'sessionPersistence']
+
+  /** Live-preferred observation backed directly by a short-lived persistence read handle. */
+  override async observeSession(
+    sessionId: SessionId,
+    options: SessionObservationOptions = {},
+  ): Promise<SessionObservation> {
+    const live = this.ctx.sessions.get(sessionId)
+    if (live !== undefined) return cut('live', live.header, live.snapshotEvents())
+    const handle = await this.ctx.sessionPersistence.open(
+      sessionId,
+      'read',
+      options.signal === undefined ? {} : { signal: options.signal },
+    )
+    try {
+      return cut(
+        'prepared',
+        handle.header,
+        await handle.read(0, undefined, options.signal === undefined ? {} : { signal: options.signal }),
+      )
+    } finally {
+      await handle.close()
+    }
+  }
+
   override searchSessions(): Promise<never> {
     return Promise.reject(new Error('session search is not configured in this test'))
   }
diff --git a/packages/experimental/tool-agent-team/tests/tool-team.spec.ts b/packages/experimental/tool-agent-team/tests/tool-team.spec.ts
index 353586a37f..4fa659efcc 100644
--- a/packages/experimental/tool-agent-team/tests/tool-team.spec.ts
+++ b/packages/experimental/tool-agent-team/tests/tool-team.spec.ts
@@ -71,7 +71,7 @@ async function setup(script: ConstructorParameters<typeof MockAdapter>[0], legac
   const fiber = await ctx.plugin(toolTeam)
   const adapter = new MockAdapter(script)
   ctx.llm.registerAdapter(['mock'], adapter)
-  const lead = ctx.agentLoop.create(SessionId('tool-team-lead'), { provider: 'mock', model: 'mock' })
+  const lead = await ctx.agentLoop.create(SessionId('tool-team-lead'), { provider: 'mock', model: 'mock' })
   return { ctx, lead, fiber }
 }
 
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index 55761bf933..22f7b5be65 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -111,8 +111,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         parameters: [],
       },
       {
-        signature: 'create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, \'cwd\'> = {}): Agent',
-        description: 'Create an agent and session under one caller-supplied identity, owned by the accessing fiber. Constructor-driven config calls mint a fresh combined id before entering this boundary.',
+        signature: 'async create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, \'cwd\'> = {}): Promise<Agent>',
+        description: 'Create an agent and session under one caller-supplied identity, owned by the accessing fiber. Constructor-driven config calls mint a fresh combined id before entering this boundary. When a persistence backend is mounted, the session\'s durable identity and any seed are stored before publication.',
         parameters: [{ name: 'id', description: 'shared agent/session identity.' }, { name: 'options', description: 'concrete loop options.' }, { name: 'meta', description: 'optional fresh-session workspace metadata.' }],
         returns: 'the published running agent.',
       },
@@ -1460,83 +1460,41 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'sessionPersistence',
-    summary: 'Durable append-only session storage.',
-    description: 'Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.',
+    summary: 'Durable append-only session storage addressed through per-session handles.',
+    description: 'Durable append-only session storage addressed through per-session handles.\n\nStorage semantics shared by every backend: events are contiguous from seq 0 and never rewritten; a torn physical tail is never returned to a reader and is truncated by the write path before its first append; reads validate current-format records only and refuse unknown vocabulary fail-closed. `append` persists best-effort; `flush` — per handle or service-wide — is the durability barrier.\n\nVisibility: a created session is observable through `stat`/`list`/`open` in this process from the moment `create` resolves, even while a backend defers physical materialization (a pure optimization); other processes see the session only once it materializes, and a session that never materialized before a crash never existed. `SessionHandle.flush` forces materialization.\n\nFreshness: once an `append` or `flush` resolves, reads started afterwards on this backend instance observe at least that prefix.',
     methods: [
       {
-        signature: 'abstract locate(meta: SessionHeader): SessionLocation | undefined',
-        description: 'Resolve this backend\'s independent local artifact for a session without reading, creating, flushing, or otherwise materializing it. A backend that does not own one artifact per Session returns `undefined`.',
-        parameters: [{ name: 'meta', description: 'the immutable session header whose artifact is requested.' }],
-        returns: 'the backend-specific absolute location, when one exists.',
+        signature: 'abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>',
+        description: 'Create a new stored session and take its write ownership.',
+        parameters: [{ name: 'header', description: 'the immutable header (id, version, cwd, lineage) to store.' }, { name: 'options', description: 'optional cancellation.' }],
+        returns: 'a `write` handle owned by the caller; close it to release ownership.',
+        throws: ['{SessionAlreadyExistsError} when the id already exists.'],
       },
       {
-        signature: 'abstract readonly supportsRawArtifacts: boolean',
-        description: 'Whether this backend exposes one verbatim raw artifact per session. A backend that declares `true` must override readRaw.',
+        signature: 'abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>',
+        description: 'Open an existing stored session.\n\n`read` never takes ownership and works while another handle (or process) holds write ownership. `write` atomically claims single-writer ownership; an existing active owner rejects.',
+        parameters: [{ name: 'id', description: 'the stored session to open.' }, { name: 'access', description: '`read` or `write`.' }, { name: 'options', description: 'optional cancellation.' }],
+        returns: 'the open handle.',
+        throws: ['{SessionPersistenceNotFoundError} when the session does not exist.', '{SessionAlreadyOwnedError} for `write` when ownership is taken.'],
+      },
+      {
+        signature: 'abstract flush(): Promise<void>',
+        description: 'Flush every active write handle owned by this service instance in one durability barrier: each handle\'s routed live events drain durably and its session materializes, exactly as that handle\'s own `SessionHandle.flush` would. Read handles buffer nothing and are untouched. A handle closed concurrently counts as flushed — close itself drains durably.',
         parameters: [],
+        returns: 'resolution once every write handle active at the call has flushed.',
+        throws: ['{AggregateError} naming each session whose flush failed; the remaining handles still flush.'],
       },
       {
-        signature: 'readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>',
-        description: 'Read a session\'s backend-owned artifact text verbatim — the exact durable bytes the backend wrote (decoded from its physical encoding, e.g. a decompressed JSONL). The returned `content` is the raw text, not a reconstruction from parsed events, so it preserves backend-specific serialization (chunk packing, key order, line breaks). Callers first test supportsRawArtifacts; `undefined` then means only that the requested session has no materialized artifact.',
-        parameters: [{ name: '_id', description: 'the persisted session to read (unused by the default: no per-session artifact).' }, { name: 'signal', description: 'optional cancellation for backend read work.' }],
-        returns: 'the raw artifact plus its parsed header, or `undefined` when the session is absent.',
-        throws: ['when this backend does not expose per-session raw artifacts.'],
+        signature: 'abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>',
+        description: 'Observe one stored session without reading its event log or taking ownership.\n\nThe snapshot\'s `revision` is an opaque change token comparable only against revisions from the same service instance and session id: equal revisions may be treated as an unchanged log; unequal revisions promise nothing. Write-ownership churn does not change a revision. It exists for derived read-model caches keyed off `stat`/`list`; it plays no part in open, read, or resume.',
+        parameters: [{ name: 'id', description: 'the stored session to observe.' }, { name: 'options', description: 'optional cancellation.' }],
+        returns: 'the snapshot, or `undefined` when the session does not exist.',
       },
       {
-        signature: 'abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>',
-        description: 'Register a new session\'s metadata. A backend MAY defer the physical write until the first append (lazy materialization), in which case a created-but-never-appended session is absent from list — abandoned sessions leave nothing behind.',
-        parameters: [{ name: 'meta', description: 'the immutable header (id, version, cwd, lineage) to record.' }, { name: 'inheritedEventCount', description: 'exact fork-inherited prefix length. Required for a seeded header and omitted only for an unseeded header.' }],
-      },
-      {
-        signature: 'ensureMaterialized(_session: Session): Promise<void>',
-        description: 'Ensure a live session has a durable header even when it has no events. Ordinary sessions remain lazily materialized; lifecycle frontends call this only when an empty session itself is a durable resumable resource.',
-        parameters: [{ name: '_session', description: 'exact live session whose registered header is materialized.' }],
-      },
-      {
-        signature: 'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
-        description: 'Durably persist a batch of events. Honors the append-only and contiguous- seq contracts: the first event\'s `seq` MUST equal the stored next-seq (after `load` has durably closed any interrupted turn). Rejects non-JSON- serializable `event.data` with an error naming the offending event type. A seeded session\'s first materializing batch must reach its complete inherited prefix.',
-        parameters: [{ name: 'id', description: 'the session the batch belongs to.' }, { name: 'events', description: 'the contiguous batch to persist, in seq order.' }],
-      },
-      {
-        signature: 'async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>',
-        description: 'Prepare the exact unpublished Session used by resume. Implementations may reuse object graphs retained by an earlier inspect after confirming their durable revision is still current; disposal releases an unpublished reservation. Revision retries require the durable log to remain unchanged for one read/check round trip; continuous external writers may delay completion.',
-        parameters: [{ name: 'id', description: 'persisted session to prepare.' }, { name: 'signal', description: 'optional cancellation for preparation work.' }],
-        returns: 'one owned unpublished Session preparation.',
-      },
-      {
-        signature: 'abstract load(id: SessionId): Promise<SessionInspection>',
-        description: 'Load an immutable balanced logical view and commit any required cold recovery. A complete interrupted final turn is preserved and durably closed with missing tool errors plus any open step and turn boundaries; only a torn final record is discarded. Unknown versions and corruption in the committed prefix reject. Implementations MUST NOT crash-repair an identity still bound to a live Session: a balanced live log may return as a durable snapshot, while an open live turn rejects. Returned values may be shared with immutable live or prepared state and must not be mutated. Revision-based implementations may wait for one stable read/check round trip.',
-        parameters: [{ name: 'id', description: 'the persisted session to reload.' }],
-        returns: 'the header and a log ending on a balanced `turn/end`.',
-      },
-      {
-        signature: 'abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>',
-        description: 'Inspect an immutable logical session without committing recovery or publishing it. A cold complete interrupted turn receives synthetic closers in memory and a torn physical tail remains untouched. An already-live Session instead yields its current immutable snapshot, which may contain an open turn and its `session/end-seed` boundary. Coordinator-backed implementations retain the exact cold unpublished Session for bounded reuse by a later prepare. A stale ready source is reloaded; a source already committing or reserved for resume remains exclusive, and inspection may borrow its immutable view. Callers borrow only the immutable header and log. Continuous external writers may delay revision convergence.',
-        parameters: [{ name: 'id', description: 'the persisted session to inspect.' }, { name: 'signal', description: 'optional cancellation for queued and backend read work.' }],
-        returns: 'the validated header and current logical event log.',
-      },
-      {
-        signature: 'abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>',
-        description: 'Borrow one exact inspection while retaining any reusable prepared source. A cold observation must pin the exact prepared Session that a later prepare reserves. Implementations must not degrade this operation to a detached inspect result.',
-        parameters: [{ name: 'id', description: 'persisted session to observe.' }, { name: 'signal', description: 'optional cancellation for preparation work.' }],
-        returns: 'a disposable immutable observation.',
-      },
-      {
-        signature: 'abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>',
-        description: 'Read the stored events from `fromSeq` onward — the read-from-seq primitive for read models that resume from a watermark (e.g. a persisted projection cache folding only the tail past its checkpoint). Unlike inspect, it is a detached physical suffix read: no preparation cache, torn-tail truncation, synthetic closers, or coordinator-state publication. Only events from the valid contiguous stored prefix are returned, so a torn fragment never reaches the caller. `fromSeq` at or beyond the stored prefix returns an empty event list (never an error). A backend whose medium can seek by seq may read only the suffix; sequential media such as JSONL still parse the whole artifact and skip forward. The primitive bounds what is returned and refolded, not every backend\'s physical read.',
-        parameters: [{ name: 'id', description: 'the persisted session to read.' }, { name: 'fromSeq', description: 'first event offset to include.' }, { name: 'signal', description: 'optional cancellation for queued and backend read work.' }],
-        returns: 'storage metadata, the requested offset, and stored events with `seq >= fromSeq`.',
-      },
-      {
-        signature: 'abstract list(signal?: AbortSignal): Promise<SessionHeader[]>',
-        description: 'Lightweight listing from metadata, without a full-log parse.',
-        parameters: [{ name: 'signal', description: 'optional cancellation for backend listing work.' }],
-        returns: 'one header per materialized session.',
-      },
-      {
-        signature: 'abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>',
-        description: 'List materialized sessions with cheap per-log change tokens.\n\nRepeated observations of an unchanged log return the same revision. A successful mutating load repair changes the next listed revision. Revisions also distinguish independently backed stores so backend-local counters cannot compare equal across different persistence sources.',
-        parameters: [{ name: 'signal', description: 'optional cancellation for backend snapshot-listing work.' }],
-        returns: 'one header and opaque revision per materialized session without loading full logs.',
+        signature: 'abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>',
+        description: 'List every stored session visible to this process, in no promised order.',
+        parameters: [{ name: 'options', description: 'optional cancellation.' }],
+        returns: 'one snapshot per stored session.',
       },
     ],
   },
@@ -1622,7 +1580,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined',
         description: 'The stored seq a restore tail read over `checkpoint` must start at: one event BELOW the lowest usable watermark (a row is usable when its `ver` matches the live unit\'s `stateVersion`; an absent or mismatched row pulls the floor to `0` — that key must refold the full log). The one-below anchor is load-bearing: the tail then proves how far the stored log still extends, so restore can detect a log that shrank below a row\'s watermark (crash-repair truncation) instead of serving the stale row as current — an empty tail read from the anchor yields an end below every watermark and the restore rejects for a full re-read.',
         parameters: [{ name: 'checkpoint', description: 'persisted rows for one session (possibly stale or empty).' }],
-        returns: 'the seq to hand the persistence `readFrom`, or `undefined` when no unit is registered (no read needed — {@link restore} would serve empty values regardless).',
+        returns: 'the offset for the stored-log suffix read (`SessionHandle.read`), or `undefined` when no unit is registered (no read needed — {@link restore} would serve empty values regardless).',
       },
       {
         signature: 'viewCheckpoint( checkpoint: ProjectionCheckpoint, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): Partial<SessionProjectionMap>',
@@ -1632,7 +1590,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, header: SessionHeader, inheritedEventCount: SessionLogOffset, ): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }',
-        description: 'Cold read: fold every persisted unit over a stored log suffix, seeding each from its checkpoint row when usable — the one read recipe (cached state + forward tail replay + `view`) applied without a live `Session`. Call with the events returned by a persistence `readFrom(id, restoreFloor(checkpoint))` and that same floor as `baseSeq`; the floor\'s one-below anchor makes the supplied end honest, so a shrunk log is detected here. A row is usable iff its `ver` matches the live unit\'s `stateVersion`, it does not predate `baseSeq` (`seq >= baseSeq - 1`), and it does not claim events past the supplied end (`seq <= endSeq`); an unusable row is discarded and its key refolds from `init` — which is only sound over the full log, so a discarded row with `baseSeq > 0` throws (the caller re-reads from seq 0, e.g. after a crash-repair truncation shrank the log below a row\'s watermark).',
+        description: 'Cold read: fold every persisted unit over a stored log suffix, seeding each from its checkpoint row when usable — the one read recipe (cached state + forward tail replay + `view`) applied without a live `Session`. Call with the stored events at or past `restoreFloor(checkpoint)` (a `SessionHandle.read` slice) and that same floor as `baseSeq`; the floor\'s one-below anchor makes the supplied end honest, so a shrunk log is detected here. A row is usable iff its `ver` matches the live unit\'s `stateVersion`, it does not predate `baseSeq` (`seq >= baseSeq - 1`), and it does not claim events past the supplied end (`seq <= endSeq`); an unusable row is discarded and its key refolds from `init` — which is only sound over the full log, so a discarded row with `baseSeq > 0` throws (the caller re-reads from seq 0, e.g. after a crash-repair truncation shrank the log below a row\'s watermark).',
         parameters: [{ name: 'checkpoint', description: 'persisted rows for one session (possibly stale or empty).' }, { name: 'events', description: 'the stored events with `seq >= baseSeq`, in seq order.' }, { name: 'baseSeq', description: 'the seq `events` starts at (its first event\'s seq when non-empty).' }, { name: 'header', description: 'immutable metadata for the Session being restored.' }, { name: 'inheritedEventCount', description: 'exact fork-inherited prefix length supplied to unit initialization.' }],
         returns: 'the snapshot cut at the supplied log end (`asOfSeq` is the last supplied event\'s seq, `baseSeq - 1` for an empty tail) plus the refreshed checkpoint rows at that cut, ready for a durable write-back.',
       },
@@ -1773,7 +1731,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   {
     key: 'sessions',
     summary: 'In-memory session store (`ctx.sessions`).',
-    description: 'In-memory session store (`ctx.sessions`).\n\nPersistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.',
+    description: 'In-memory session store (`ctx.sessions`).\n\nPersistence is intentionally not implemented here — the agent lifecycle attaches a session-log writer to each published session\'s write handle; a session published outside that lifecycle persists nothing.',
     methods: [
       {
         signature: 'create(id?: SessionId, options?: CreateSessionOptions): Session',
@@ -3606,10 +3564,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'BashEnvVariableInfo',
     declaration: 'export interface BashEnvVariableInfo extends BashEnvVariable {\n    contributor: string;\n    key: DshEnvironmentKey;\n}',
   },
-  {
-    name: 'BorrowedSessionSource',
-    declaration: 'export type BorrowedSessionSource = Disposable & ({\n    readonly source: \'prepared\';\n    readonly inspection: SessionInspection;\n    readonly revision: SessionPersistenceRevision;\n    readonly preparedSession: Session;\n} | {\n    readonly source: \'live\';\n    readonly inspection: SessionInspection;\n});',
-  },
   {
     name: 'Branded',
     declaration: 'export type Branded<B extends string> = string & {\n    readonly [BRAND]: B;\n};',
@@ -4798,6 +4752,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'Session',
     declaration: 'export class Session {\n    get surface(): SessionSurface;\n    readonly header: SessionHeader;\n    readonly inheritedEventCount: SessionLogOffset;\n    get id(): SessionId;\n    readonly firstLiveSeq: SessionLogOffset;\n    static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader, inheritedEventCount?: SessionLogOffset): Session;\n    static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader, inheritedEventCount: SessionLogOffset): Session;\n    eventAt(seq: SessionSeq): SessionEvent | undefined;\n    snapshotEvents(fromSeq: SessionLogOffset = SessionLogOffset(0), toSeqExclusive: SessionLogOffset = this.seq): readonly SessionEvent[];\n    ownEvents(): readonly SessionEvent[];\n    isOwnSeq(seq: SessionSeq): boolean;\n    get seq(): SessionLogOffset;\n    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n        opts: SurfaceIntent\n    ] : [\n    ]): SessionEvent<T>;\n    requestHeader(): EpochHeader | undefined;\n    requestContext(): RequestContext | undefined;\n    deriveMessages(): Message[];\n    deriveEventMessage(event: SessionEvent): Message | null;\n}',
   },
+  {
+    name: 'SessionAccess',
+    declaration: 'export type SessionAccess = \'read\' | \'write\';',
+  },
   {
     name: 'SessionAddress',
     declaration: 'export type SessionAddress = {\n    readonly kind: \'session\';\n    readonly sessionId: SessionId;\n} | {\n    readonly kind: \'subagent\';\n    readonly parentSessionId: SessionId;\n    readonly childSessionId: SessionId;\n    readonly mode: \'one-shot\' | \'continuable\';\n};',
@@ -4886,10 +4844,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionEventSearchRequest',
     declaration: 'export interface SessionEventSearchRequest {\n    sessionId: SessionId;\n    query: string;\n    filters?: readonly SessionEventMetadataFilter[];\n    limit?: number;\n    cursor?: SessionSearchCursor;\n}',
   },
-  {
-    name: 'SessionEventSuffix',
-    declaration: 'export interface SessionEventSuffix extends SessionStorageMetadata {\n    readonly fromSeq: SessionLogOffset;\n    readonly events: readonly SessionEvent[];\n}',
-  },
   {
     name: 'SessionEventSurface',
     declaration: 'export type SessionEventSurface = \'current\' | \'shadowed\' | \'log-only\';',
@@ -4934,6 +4888,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionForkValue',
     declaration: 'export interface SessionForkValue {\n    readonly sessionId: SessionId;\n}',
   },
+  {
+    name: 'SessionHandle',
+    declaration: 'export interface SessionHandle extends AsyncDisposable {\n    readonly id: SessionId;\n    readonly header: SessionHeader;\n    readonly inheritedEventCount: SessionLogOffset;\n    readonly access: SessionAccess;\n    read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<readonly SessionEvent[]>;\n    append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>;\n    flush(options?: SessionHandleFlushOptions): Promise<void>;\n    close(): Promise<void>;\n}',
+  },
+  {
+    name: 'SessionHandleAppendOptions',
+    declaration: 'export interface SessionHandleAppendOptions {\n    readonly signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'SessionHandleFlushOptions',
+    declaration: 'export interface SessionHandleFlushOptions {\n    readonly signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'SessionHandleReadOptions',
+    declaration: 'export interface SessionHandleReadOptions {\n    readonly signal?: AbortSignal;\n}',
+  },
   {
     name: 'SessionHeader',
     declaration: 'export interface SessionHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly isSeeded: boolean;\n    readonly origin?: \'subagent\';\n    readonly delegationDepth?: number;\n    readonly agentPreset?: string;\n}',
@@ -4970,10 +4940,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionListValue',
     declaration: 'export interface SessionListValue {\n    readonly items: readonly SessionSummary[];\n}',
   },
-  {
-    name: 'SessionLocation',
-    declaration: 'export interface SessionLocation {\n    readonly kind: string;\n    readonly path: string;\n}',
-  },
   {
     name: 'SessionLogOffset',
     declaration: 'export type SessionLogOffset = BrandedNumber<\'SessionLogOffset\'>;',
@@ -4984,7 +4950,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionObservation',
-    declaration: 'export interface SessionObservation extends Disposable {\n    readonly source: \'live\' | \'prepared\';\n    readonly header: SessionHeader;\n    readonly events: readonly SessionEvent[];\n    readonly inheritedEventCount: SessionLogOffsetType;\n    readonly cursor: SessionSeqCursor;\n    readonly revision?: SessionPersistenceRevision;\n    readonly projections?: ProjectionSnapshot;\n    retain(): SessionObservation;\n}',
+    declaration: 'export interface SessionObservation extends Disposable {\n    readonly source: \'live\' | \'prepared\';\n    readonly header: SessionHeader;\n    readonly inheritedEventCount: SessionLogOffsetType;\n    readonly events: readonly SessionEvent[];\n    readonly cursor: SessionSeqCursor;\n    readonly revision?: SessionPersistenceRevision;\n    readonly projections?: ProjectionSnapshot;\n    retain(): SessionObservation;\n}',
   },
   {
     name: 'SessionObservationOptions',
@@ -5006,21 +4972,29 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionPageRequest',
     declaration: 'export interface SessionPageRequest {\n    readonly address: SessionAddress;\n    readonly throughSeq: number;\n    readonly beforeSeq?: number;\n    readonly maxMessages?: number;\n}',
   },
+  {
+    name: 'SessionPersistenceCreateOptions',
+    declaration: 'export interface SessionPersistenceCreateOptions {\n    readonly signal?: AbortSignal;\n    readonly inheritedEventCount?: SessionLogOffset;\n}',
+  },
+  {
+    name: 'SessionPersistenceListOptions',
+    declaration: 'export interface SessionPersistenceListOptions {\n    readonly signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'SessionPersistenceOpenOptions',
+    declaration: 'export interface SessionPersistenceOpenOptions {\n    readonly signal?: AbortSignal;\n}',
+  },
   {
     name: 'SessionPersistenceRevision',
     declaration: 'export type SessionPersistenceRevision = Branded<\'SessionPersistenceRevision\'>;',
   },
   {
     name: 'SessionPersistenceSnapshot',
-    declaration: 'export interface SessionPersistenceSnapshot {\n    header: SessionHeader;\n    revision: SessionPersistenceRevision;\n}',
+    declaration: 'export interface SessionPersistenceSnapshot {\n    readonly header: SessionHeader;\n    readonly revision: SessionPersistenceRevision;\n    readonly eventCount?: number;\n    readonly sizeBytes?: number;\n}',
   },
   {
-    name: 'SessionPreparation',
-    declaration: 'export class SessionPreparation implements Disposable {\n    readonly session: Session;\n    static create(session: Session, options?: SessionPreparationOptions): SessionPreparation;\n    [Symbol.dispose](): void;\n}',
-  },
-  {
-    name: 'SessionPreparationOptions',
-    declaration: 'export interface SessionPreparationOptions {\n    readonly release?: () => void;\n}',
+    name: 'SessionPersistenceStatOptions',
+    declaration: 'export interface SessionPersistenceStatOptions {\n    readonly signal?: AbortSignal;\n}',
   },
   {
     name: 'SessionProjectionBaseline',
@@ -5062,10 +5036,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionQueuedItem',
     declaration: 'export interface SessionQueuedItem {\n    readonly id: MessageId;\n    readonly placement: \'queued\' | \'steering\' | \'context\';\n    readonly rpcId?: SessionRequestId;\n    readonly message: {\n        readonly id: MessageId;\n        readonly content: readonly JsonValue[];\n    };\n}',
   },
-  {
-    name: 'SessionRawArtifact',
-    declaration: 'export interface SessionRawArtifact extends SessionStorageMetadata {\n    readonly filename: string;\n    readonly content: string;\n}',
-  },
   {
     name: 'SessionRecord',
     declaration: 'export interface SessionRecord {\n    header: SessionHeader;\n    live: boolean;\n    persisted: boolean;\n}',
diff --git a/packages/feedback/message-feedback/README.i18n.yaml b/packages/feedback/message-feedback/README.i18n.yaml
index 836a82fcf3..5bcf038fd8 100644
--- a/packages/feedback/message-feedback/README.i18n.yaml
+++ b/packages/feedback/message-feedback/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/feedback/message-feedback/README.md
-README.md: d8d2746293f516a5fca1729d574646dbd59698b7
-README.zh.md: f6396fe7a20355e17281e47515ebb92a8f880e06
+README.md: f323ee44e3196a519ab05b8195950b18d939d9ce
+README.zh.md: 48944a5834e65d48bc5b3f1162981ae500e31917
diff --git a/packages/feedback/message-feedback/README.md b/packages/feedback/message-feedback/README.md
index d8d2746293..f323ee44e3 100644
--- a/packages/feedback/message-feedback/README.md
+++ b/packages/feedback/message-feedback/README.md
@@ -84,7 +84,7 @@ Mutations are optimistic and per message: a caller sends the version it last obs
 
 ### Durability and target validation
 
-A write is staged, verified, then committed: the target message is flushed through the canonical checkpoint, the physical log prefix is re-read, and only then is the sidecar row written — feedback can never reference a message that is not durable. Cold sessions are inspected without resuming an agent, absence is decided from the persistence catalog rather than guessed, and only a real, sent assistant message is a valid target. The flush and inspect path lives in [`src/index.ts`](src/index.ts).
+A write is staged, verified, then committed: the target message is flushed through the canonical checkpoint, the physical log prefix is re-read, and only then is the sidecar row written — feedback can never reference a message that is not durable. Cold sessions are read without resuming an agent, absence is decided by the persistence store's `stat` rather than guessed, and only a real, sent assistant message is a valid target. The flush and read path lives in [`src/index.ts`](src/index.ts).
 
 ### Failure modes
 
@@ -110,7 +110,7 @@ Read these pages when the package-level contract is not enough. They move from t
 
 - [Feedback subsystem](../../../docs/subsystems/feedback.md) — the public types, Remote contract, and Web consumer details.
 - [Message-feedback sidecar decision](../../../.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md) — the design boundary that keeps this sidecar out of Session-log content.
-- [Session persistence subsystem](../../../docs/subsystems/persistence.md) — `inspect`, `readFrom`, and `flush` semantics behind the durability barrier.
+- [Session persistence subsystem](../../../docs/subsystems/persistence.md) — the handle `read`, `stat`, and `flush` semantics behind the durability barrier.
 - [dsh-client-ui-message-feedback](../../client/ui-message-feedback/README.md) — the browser consumer that drives the Host Remote contract.
 - [Feedback package map](../README.md) — where per-message feedback sits next to the log-only capture command.
 
@@ -142,10 +142,9 @@ These limits define when the service is a poor fit or needs special operational
 
 - **Compare-and-set is single-process** — the per-Session queue serializes one service instance only; storage-domain has no cross-process conditional write, so multiple Host processes writing one storage root can still lose updates.
 - **No durable Session deletion cascade** — Session persistence has no deletion API, and `session/disposed`/`api-session/removed` mean detach rather than durable deletion. The service therefore retains empty rows and may leave orphan rows after out-of-band log removal instead of deleting valid feedback on detach.
-- **Detach/catalog retirement window** — a request in the narrow interval after live detach but before the persistence catalog materializes the header can receive `session-not-found`; callers retry after retirement materialization.
 - **Header identity is not a content fingerprint** — `{createdAt, cwd}` detects reuse only when those fields differ; a cloned log retaining the same header identity is indistinguishable.
 - **Trusted caller boundary** — `list`/`put`/`delete` carry no authenticated actor or audit identity. A deployment must expose the Host gateway only through its trusted or separately authenticated boundary until authorization and attribution are added.
-- **Catalog and row bounds** — a cold request scans the complete Session snapshot catalog because persistence has no lookup-by-id metadata operation. `maxNoteBytes` bounds one note, but the item count and aggregate retained bytes of one Session row are not capped; an indexed metadata read and deployment-owned row bound remain deferred until a concrete consumer defines their policy.
+- **Row bounds** — `maxNoteBytes` bounds one note, but the item count and aggregate retained bytes of one Session row are not capped; a deployment-owned row bound remains deferred until a concrete consumer defines its policy.
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/feedback/message-feedback/README.zh.md b/packages/feedback/message-feedback/README.zh.md
index f6396fe7a2..48944a5834 100644
--- a/packages/feedback/message-feedback/README.zh.md
+++ b/packages/feedback/message-feedback/README.zh.md
@@ -84,7 +84,7 @@ kind: "package-reference"
 
 ### 持久性与目标校验
 
-写入按「暂存—校验—提交」进行：目标消息先通过权威 checkpoint flush，再物理重读日志前缀，之后才写入伴随记录行——反馈绝不会引用尚未持久的消息。冷会话在不恢复 agent 的情况下被检查，缺失依据持久化目录判定而非猜测，只有真实发送过的 assistant 消息才是有效目标。flush 与检查路径见 [`src/index.ts`](src/index.ts)。
+写入按「暂存—校验—提交」进行：目标消息先通过权威 checkpoint flush，再物理重读日志前缀，之后才写入伴随记录行——反馈绝不会引用尚未持久的消息。冷会话在不恢复 agent 的情况下被读取，缺失由持久化存储的 `stat` 判定而非猜测，只有真实发送过的 assistant 消息才是有效目标。flush 与读取路径见 [`src/index.ts`](src/index.ts)。
 
 ### 故障模式
 
@@ -110,7 +110,7 @@ kind: "package-reference"
 
 - [反馈子系统](../../../docs/subsystems/feedback.zh.md)——公开类型、Remote 契约与 Web 消费方细节。
 - [消息反馈伴随记录决策](../../../.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md)——让此伴随记录不进入会话日志内容的设计边界。
-- [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——持久性屏障背后的 `inspect`、`readFrom` 与 `flush` 语义。
+- [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——持久性屏障背后的 handle `read`、`stat` 与 `flush` 语义。
 - [dsh-client-ui-message-feedback](../../client/ui-message-feedback/README.zh.md)——驱动 Host Remote 契约的浏览器消费方。
 - [反馈包映射](../README.zh.md)——逐消息反馈与仅写入日志的采集命令并存的组。
 
@@ -142,10 +142,9 @@ kind: "package-reference"
 
 - **Compare-and-set 仅限单进程**——按 Session 划分的队列只串行化一个服务实例；storage-domain 不提供跨进程条件写，因此多个 Host 进程写入同一存储根目录时仍可能丢失更新。
 - **没有持久 Session 删除级联**——Session persistence 没有删除接口，且 `session/disposed`/`api-session/removed` 表示 detach 而非持久删除。因此服务会保留空行，并可能在带外移除日志后留下遗留行，而不会在 detach 时删除仍有效的反馈。
-- **Detach/catalog retirement 窗口**——请求若恰好落在 live detach 之后、persistence catalog 物化 header 之前的极短窗口，可能收到 `session-not-found`；调用方应在 retirement materialization 后重试。
 - **Header 身份不是内容指纹**——只有 `{createdAt, cwd}` 不同时才能识别复用；本契约无法区分保留相同 header 身份的克隆日志。
 - **调用方边界受信任**——`list`/`put`/`delete` 不携带已认证的 actor 或审计身份。在加入授权与归属信息前，部署方必须只通过受信任或另行认证的边界暴露 Host gateway。
-- **目录与行边界**——由于 persistence 没有按 id 读取元数据的操作，cold 请求会扫描完整的 Session snapshot 目录。`maxNoteBytes` 只限制单条备注，单个 Session 行的条目数和聚合保留字节尚无上限；按索引读取元数据和由部署决定的行边界，延后到具体消费方明确策略时处理。
+- **行边界**——`maxNoteBytes` 只限制单条备注，单个 Session 行的条目数和聚合保留字节尚无上限；由部署决定的行边界，延后到具体消费方明确策略时处理。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/feedback/message-feedback/src/index.ts b/packages/feedback/message-feedback/src/index.ts
index e07a8b809c..8808b199bb 100644
--- a/packages/feedback/message-feedback/src/index.ts
+++ b/packages/feedback/message-feedback/src/index.ts
@@ -7,10 +7,10 @@ import { Buffer } from 'node:buffer'
 import { randomUUID } from 'node:crypto'
 import { Context, Service } from '@deepseek-ai/cordis'
 import s from '@deepseek-ai/schemastery'
-import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import { deriveEventMessage, isAppendSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
-import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session/types'
-import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-persistence'
 import type { KvTable } from '@deepseek-ai/dsh-storage-domain'
 import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol'
 import { messageFeedbackDomainSpec } from './spec.ts'
@@ -134,9 +134,15 @@ function nextVersion(): MessageFeedbackVersion {
   return randomUUID() as MessageFeedbackVersion
 }
 
-/** Session inspection result that keeps absence inside the business union. */
+/** Observed session view: header identity plus the logged events. */
+interface SessionObservation {
+  readonly meta: SessionHeader
+  readonly events: readonly SessionEvent[]
+}
+
+/** Session observation result that keeps absence inside the business union. */
 type KnownSession =
-  | MessageFeedbackSuccess<SessionInspection>
+  | MessageFeedbackSuccess<SessionObservation>
   | MessageFeedbackRejected<MessageFeedbackSessionNotFound>
 
 /** Validated note or one explicit request failure. */
@@ -296,25 +302,41 @@ export class MessageFeedbackService extends TypertRemoteService {
   }
 
   /**
-   * Resolve a live owner directly; otherwise use the storage catalog as the
-   * existence authority before inspecting the log. Inspection failures for a
-   * catalogued Session remain infrastructure failures rather than being
-   * guessed into the business `session-not-found` branch.
+   * Resolve a live owner directly; otherwise use `stat` as the existence
+   * authority before reading the log. Read failures for a Session that `stat`
+   * confirmed remain infrastructure failures rather than being guessed into
+   * the business `session-not-found` branch.
    */
   private async inspectSession(sessionId: SessionId): Promise<KnownSession> {
     if (this.ctx.sessions.get(sessionId) === undefined) {
-      const snapshots = await this.ctx.sessionPersistence.listSnapshots()
-      if (!snapshots.some(snapshot => snapshot.header.id === sessionId)
+      if (await this.ctx.sessionPersistence.stat(sessionId) === undefined
         && this.ctx.sessions.get(sessionId) === undefined) {
         return rejected({ code: 'session-not-found', sessionId })
       }
     }
-    return success(await this.ctx.sessionPersistence.inspect(sessionId))
+    return success(await this.observeSession(sessionId))
+  }
+
+  /** Observe a live owner's in-memory log when one exists, else the durable log. */
+  private async observeSession(sessionId: SessionId): Promise<SessionObservation> {
+    const live = this.ctx.sessions.get(sessionId)
+    if (live !== undefined) return { meta: live.header, events: live.snapshotEvents() }
+    return await this.readDurable(sessionId)
+  }
+
+  /** Read the complete durable log prefix through a fresh read handle. */
+  private async readDurable(sessionId: SessionId): Promise<SessionObservation> {
+    const handle = await this.ctx.sessionPersistence.open(sessionId, 'read')
+    try {
+      return { meta: handle.header, events: await handle.read() }
+    } finally {
+      await handle.close()
+    }
   }
 
   /** Require the exact finalized append-origin assistant message projection. */
-  private hasFeedbackTarget(inspection: SessionInspection, messageId: MessageFeedbackItem['messageId']): boolean {
-    return inspection.events.some((event) => {
+  private hasFeedbackTarget(observation: SessionObservation, messageId: MessageFeedbackItem['messageId']): boolean {
+    return observation.events.some((event) => {
       if (event.type !== 'assistant/message' || !isAppendSurfaceEvent(event)) return false
       const message = deriveEventMessage(event)
       return message?.role === 'assistant' && message.id === messageId
@@ -323,26 +345,20 @@ export class MessageFeedbackService extends TypertRemoteService {
 
   /**
    * Put the target log prefix behind a durability barrier before its sidecar.
-   * A live owner flushes through the SessionStore's canonical checkpoint; a
-   * cold owner is re-read from the physical durable prefix.
+   * A live owner flushes through the SessionStore's canonical checkpoint; the
+   * physical durable prefix is then re-read, which observes at least the
+   * flushed prefix by the `SessionPersistence` freshness guarantee.
    */
-  private async ensureTargetDurable(inspection: SessionInspection): Promise<SessionInspection> {
-    const live = this.ctx.sessions.get(inspection.meta.id)
-    if (live !== undefined && sameHeaderIdentity(live.header, inspection.meta)) {
+  private async ensureTargetDurable(observation: SessionObservation): Promise<SessionObservation> {
+    const live = this.ctx.sessions.get(observation.meta.id)
+    if (live !== undefined && sameHeaderIdentity(live.header, observation.meta)) {
       if (!(await this.ctx.sessions.flush(live))) {
         throw new Error(
-          `message-feedback: no durability listener participated for live session '${inspection.meta.id}'`,
+          `message-feedback: no durability listener participated for live session '${observation.meta.id}'`,
         )
       }
-      return await this.ctx.sessionPersistence.readFrom(
-        inspection.meta.id,
-        SessionLogOffset(0),
-      )
     }
-    return await this.ctx.sessionPersistence.readFrom(
-      inspection.meta.id,
-      SessionLogOffset(0),
-    )
+    return await this.readDurable(observation.meta.id)
   }
 
   /** Validate optional-note semantics and the configured complete UTF-8 byte bound. */
diff --git a/packages/feedback/message-feedback/tests/helpers.ts b/packages/feedback/message-feedback/tests/helpers.ts
index 3ae1363506..caf81258f3 100644
--- a/packages/feedback/message-feedback/tests/helpers.ts
+++ b/packages/feedback/message-feedback/tests/helpers.ts
@@ -4,20 +4,21 @@ import { join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
 import { createAssistantMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
-import SessionStore, {
+import SessionStore, { SessionLogOffset,
   SESSION_FORMAT_VERSION,
   Session,
   SessionId,
-  SessionLogOffset,
   type SessionEvent,
   type SessionHeader,
-  type SessionLogOffset as SessionLogOffsetType,
 } from '@deepseek-ai/dsh-session'
 import SessionPersistence, {
+  SessionAlreadyExistsError,
+  SessionHandleClosedError,
+  SessionPersistenceNotFoundError,
   SessionPersistenceRevision,
-  type SessionEventSuffix,
-  type SessionInspection,
-  type SessionLocation,
+  SessionReadOnlyError,
+  type SessionAccess,
+  type SessionHandle,
   type SessionPersistenceSnapshot,
 } from '@deepseek-ai/dsh-session-persistence'
 import Storage from '@deepseek-ai/dsh-storage'
@@ -111,90 +112,88 @@ export function messageFixture(
   return { session, ...appendMessageFixture(session) }
 }
 
+/** One stored session in the in-memory test backend. */
+interface StoredSession {
+  readonly meta: SessionHeader
+  events: readonly SessionEvent[]
+}
+
 /** Minimal controllable persistence provider for service-level tests. */
 class TestPersistence extends SessionPersistence {
-  override readonly supportsRawArtifacts = false
+  readonly durable = new Map<SessionId, StoredSession>()
+  readFailure: Error | undefined
+  statCalls = 0
+  readCalls = 0
+  onRead: (() => void | Promise<void>) | undefined
+  onStat: (() => void | Promise<void>) | undefined
 
-  static inject = ['sessions']
-
-  readonly durable = new Map<SessionId, SessionInspection>()
-  readonly logical = new Map<SessionId, SessionInspection>()
-  inspectFailure: Error | undefined
-  inspectCalls = 0
-  readFromCalls = 0
-  onReadFrom: (() => void | Promise<void>) | undefined
-  onListSnapshots: (() => void | Promise<void>) | undefined
-
-  locate(_meta: SessionHeader): SessionLocation | undefined { return undefined }
-  create(_meta: SessionHeader): Promise<void> { return Promise.resolve() }
-  append(_id: SessionId, _events: readonly SessionEvent[]): Promise<void> { return Promise.resolve() }
-
-  load(id: SessionId): Promise<SessionInspection> {
-    return this.readFrom(id, SessionLogOffset(0))
+  async create(header: SessionHeader): Promise<SessionHandle> {
+    if (this.durable.has(header.id)) throw new SessionAlreadyExistsError(header.id)
+    const stored: StoredSession = { meta: header, events: [] }
+    this.durable.set(header.id, stored)
+    return this.handle(stored, 'write')
   }
 
-  inspect(id: SessionId): Promise<SessionInspection> {
-    this.inspectCalls += 1
-    if (this.inspectFailure !== undefined) return Promise.reject(this.inspectFailure)
-    const explicit = this.logical.get(id)
-    if (explicit !== undefined) return Promise.resolve(explicit)
-    const live = this.ctx.sessions.get(id)
-    if (live !== undefined) {
-      return Promise.resolve({
-        meta: live.header,
-        inheritedEventCount: live.inheritedEventCount,
-        events: live.snapshotEvents(),
-      })
-    }
+  // Appends are durable on resolution here; nothing buffers, so the service-wide flush is a no-op.
+  async flush(): Promise<void> {}
+
+  async open(id: SessionId, access: SessionAccess): Promise<SessionHandle> {
     const stored = this.durable.get(id)
-    return stored === undefined
-      ? Promise.reject(new Error(`test persistence: session '${id}' not found`))
-      : Promise.resolve(stored)
+    if (stored === undefined) throw new SessionPersistenceNotFoundError(id)
+    return this.handle(stored, access)
   }
 
-  borrowSession(_id: SessionId, _signal?: AbortSignal): ReturnType<SessionPersistence['borrowSession']> {
-    return Promise.reject(new Error('not used'))
-  }
-
-  async readFrom(
-    id: SessionId,
-    fromSeq: SessionLogOffsetType,
-  ): Promise<SessionEventSuffix> {
-    this.readFromCalls += 1
-    await this.onReadFrom?.()
+  async stat(id: SessionId): Promise<SessionPersistenceSnapshot | undefined> {
+    this.statCalls += 1
+    await this.onStat?.()
     const stored = this.durable.get(id)
-    return stored === undefined
-      ? Promise.reject(new Error(`test persistence: session '${id}' not found`))
-      : {
-        meta: stored.meta,
-        inheritedEventCount: stored.inheritedEventCount,
-        fromSeq,
-        events: stored.events.filter(event => event.seq >= fromSeq),
-      }
+    if (stored === undefined) return undefined
+    return { header: stored.meta, revision: SessionPersistenceRevision(`test:${id}:${stored.events.length}`) }
   }
 
-  list(): Promise<SessionHeader[]> {
-    return Promise.resolve([...this.durable.values()].map(value => value.meta))
-  }
-
-  async listSnapshots(): Promise<SessionPersistenceSnapshot[]> {
-    await this.onListSnapshots?.()
-    return [...this.durable.values()].map((value, index) => ({
-      header: value.meta,
-      revision: SessionPersistenceRevision(`test:${index}:${value.events.length}`),
+  async list(): Promise<SessionPersistenceSnapshot[]> {
+    return [...this.durable.entries()].map(([id, stored]) => ({
+      header: stored.meta,
+      revision: SessionPersistenceRevision(`test:${id}:${stored.events.length}`),
     }))
   }
 
-  persist(session: Session): void {
-    this.durable.set(session.id, {
-      meta: session.header,
-      inheritedEventCount: session.inheritedEventCount,
-      events: session.snapshotEvents(),
-    })
+  private handle(stored: StoredSession, access: SessionAccess): SessionHandle {
+    let closed = false
+    const handle: SessionHandle = {
+      id: stored.meta.id,
+      header: stored.meta,
+      inheritedEventCount: SessionLogOffset(0),
+      access,
+      read: async (offset = 0, length?: number) => {
+        if (closed) throw new SessionHandleClosedError(stored.meta.id, 'read')
+        this.readCalls += 1
+        if (this.readFailure !== undefined) throw this.readFailure
+        await this.onRead?.()
+        const events = stored.events.filter(event => event.seq >= offset)
+        return length === undefined ? events : events.slice(0, length)
+      },
+      append: async (events) => {
+        if (closed) throw new SessionHandleClosedError(stored.meta.id, 'append')
+        if (access !== 'write') throw new SessionReadOnlyError(stored.meta.id, 'append')
+        stored.events = [...stored.events, ...events]
+      },
+      flush: async () => {
+        if (closed) throw new SessionHandleClosedError(stored.meta.id, 'flush')
+        if (access !== 'write') throw new SessionReadOnlyError(stored.meta.id, 'flush')
+      },
+      close: async () => { closed = true },
+      [Symbol.asyncDispose]() { return handle.close() },
+    }
+    return handle
   }
 
-  setDurable(inspection: SessionInspection): void {
-    this.durable.set(inspection.meta.id, inspection)
+  persist(session: Session): void {
+    this.durable.set(session.id, { meta: session.header, events: [...session.snapshotEvents()] })
+  }
+
+  setDurable(stored: StoredSession): void {
+    this.durable.set(stored.meta.id, stored)
   }
 }
 
diff --git a/packages/feedback/message-feedback/tests/loader-composition.spec.ts b/packages/feedback/message-feedback/tests/loader-composition.spec.ts
index a682dfd3d9..5fc528360b 100644
--- a/packages/feedback/message-feedback/tests/loader-composition.spec.ts
+++ b/packages/feedback/message-feedback/tests/loader-composition.spec.ts
@@ -6,7 +6,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import Include from '@deepseek-ai/cordis-plugin-include'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
-import SessionStore, { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import Storage from '@deepseek-ai/dsh-storage'
 import * as StorageDomain from '@deepseek-ai/dsh-storage-domain'
@@ -66,7 +66,6 @@ describe('message feedback through a real Loader composition', () => {
       '  config:',
       `    root: ${JSON.stringify(join(root, 'sessions'))}`,
       '    compression: none',
-      '    writeBatchMaxDelayMs: 1',
       "- name: '@deepseek-ai/dsh-storage'",
       "- name: '@deepseek-ai/dsh-storage-json'",
       '  config:',
@@ -88,6 +87,9 @@ describe('message feedback through a real Loader composition', () => {
     const session = first.sessions.create(SessionId('loader-feedback'), {
       meta: { cwd: root },
     })
+    // The mounted backend routes this published session's `session/event`
+    // batches and `session/flush` barriers into its active write handle.
+    const writeHandle = await first.sessionPersistence.create(session.header)
     const fixture = appendMessageFixture(session)
     const put = await first.messageFeedback.put({
       sessionId: session.id,
@@ -97,11 +99,14 @@ describe('message feedback through a real Loader composition', () => {
       ifVersion: null,
     })
     if (!put.ok) throw new Error(`expected put success, got ${put.error.code}`)
-    const durable = await first.sessionPersistence.readFrom(session.id, SessionLogOffset(0))
-    expect(durable.events.some(event =>
+    const readHandle = await first.sessionPersistence.open(session.id, 'read')
+    const durableEvents = await readHandle.read()
+    await readHandle.close()
+    expect(durableEvents.some(event =>
       event.type === 'assistant/message'
       && event.data.message.id === fixture.assistantMessageIds[0])).toBe(true)
 
+    await writeHandle.close()
     await first.fiber.dispose()
     contexts.splice(contexts.indexOf(first), 1)
 
diff --git a/packages/feedback/message-feedback/tests/message-feedback.spec.ts b/packages/feedback/message-feedback/tests/message-feedback.spec.ts
index 92b65ce2d4..82eb07e818 100644
--- a/packages/feedback/message-feedback/tests/message-feedback.spec.ts
+++ b/packages/feedback/message-feedback/tests/message-feedback.spec.ts
@@ -62,13 +62,9 @@ describe('MessageFeedbackService public contract', () => {
     })
 
     const fixture = messageFixture('corrupt-session')
-    persistence.setDurable({
-      meta: fixture.session.header,
-      inheritedEventCount: fixture.session.inheritedEventCount,
-      events: fixture.session.snapshotEvents(),
-    })
+    persistence.setDurable({ meta: fixture.session.header, events: fixture.session.snapshotEvents() })
     const corruption = new Error('stored log checksum mismatch')
-    persistence.inspectFailure = corruption
+    persistence.readFailure = corruption
     await expect(ctx.messageFeedback.list({ sessionId: fixture.session.id })).rejects.toBe(corruption)
   })
 
@@ -77,7 +73,7 @@ describe('MessageFeedbackService public contract', () => {
     const sessionId = SessionId('catalog-live-race')
     const listed = Promise.withResolvers<undefined>()
     const release = Promise.withResolvers<undefined>()
-    persistence.onListSnapshots = async () => {
+    persistence.onStat = async () => {
       listed.resolve(undefined)
       await release.promise
     }
@@ -88,7 +84,8 @@ describe('MessageFeedbackService public contract', () => {
     release.resolve(undefined)
 
     await expect(pending).resolves.toEqual({ ok: true, value: { items: [] } })
-    expect(persistence.inspectCalls).toBe(1)
+    expect(persistence.statCalls).toBe(1)
+    expect(persistence.readCalls).toBe(0)
   })
 
   it('returns session-not-found from mutations and conflicts on an observed version for an absent item', async () => {
@@ -189,7 +186,7 @@ describe('MessageFeedbackService public contract', () => {
     const fixture = messageFixture('note-limits')
     persistence.persist(fixture.session)
     const messageId = fixture.assistantMessageIds[0]
-    const before = persistence.inspectCalls
+    const before = persistence.statCalls + persistence.readCalls
 
     await expect(ctx.messageFeedback.put({
       sessionId: fixture.session.id,
@@ -208,7 +205,7 @@ describe('MessageFeedbackService public contract', () => {
       ok: false,
       error: { code: 'note-too-large', maxBytes: 4, actualBytes: 6 },
     })
-    expect(persistence.inspectCalls).toBe(before)
+    expect(persistence.statCalls + persistence.readCalls).toBe(before)
 
     expectItem(await ctx.messageFeedback.put({
       sessionId: fixture.session.id,
@@ -261,8 +258,12 @@ describe('MessageFeedbackService public contract', () => {
     const rawCtx = new Context()
     rawCtx.provide('sessions', { get: () => undefined } as never)
     rawCtx.provide('sessionPersistence', {
-      listSnapshots: () => Promise.resolve([{ header: fixture.session.header, revision: 'test' }]),
-      inspect: () => Promise.resolve({ meta: fixture.session.header, events: fixture.session.snapshotEvents() }),
+      stat: () => Promise.resolve({ header: fixture.session.header, revision: 'test' }),
+      open: () => Promise.resolve({
+        header: fixture.session.header,
+        read: () => Promise.resolve(fixture.session.snapshotEvents()),
+        close: () => Promise.resolve(),
+      }),
     } as never)
     const raw = new MessageFeedbackService(rawCtx, { maxNoteBytes: 1 })
     await expect(raw.list({ sessionId: fixture.session.id }))
@@ -475,7 +476,7 @@ describe('MessageFeedbackService item concurrency', () => {
     const release = Promise.withResolvers<undefined>()
     let physicalReads = 0
     let committed = 0
-    persistence.onReadFrom = async () => {
+    persistence.onRead = async () => {
       physicalReads += 1
       if (physicalReads !== 1) return
       started.resolve(undefined)
@@ -511,28 +512,24 @@ describe('MessageFeedbackService item concurrency', () => {
     expectItem(await first)
     expectItem(await second)
     await disposal
-    expect(physicalReads).toBe(2)
+    expect(physicalReads).toBe(4)
     expect(committed).toBe(2)
   })
 })
 
 describe('MessageFeedbackService durability ordering', () => {
-  it('rejects a logical target missing from the cold physical durable prefix', async () => {
+  it('rejects a live target missing from the re-read physical durable prefix', async () => {
     const { ctx, persistence } = await harness()
-    const fixture = messageFixture('cold-prefix')
-    persistence.logical.set(fixture.session.id, {
-      meta: fixture.session.header,
-      inheritedEventCount: fixture.session.inheritedEventCount,
-      events: fixture.session.snapshotEvents(),
+    const session = ctx.sessions.create(SessionId('live-prefix'), {
+      meta: { createdAt: 50, cwd: '/prefix' },
     })
-    persistence.setDurable({
-      meta: fixture.session.header,
-      inheritedEventCount: fixture.session.inheritedEventCount,
-      events: [],
+    const fixture = appendMessageFixture(session)
+    ctx.on('session/flush', () => {
+      persistence.setDurable({ meta: session.header, events: [] })
     })
 
     await expect(ctx.messageFeedback.put({
-      sessionId: fixture.session.id,
+      sessionId: session.id,
       messageId: fixture.assistantMessageIds[0],
       rating: 'positive',
       ifVersion: null,
@@ -540,12 +537,12 @@ describe('MessageFeedbackService durability ordering', () => {
       ok: false,
       error: {
         code: 'target-not-found',
-        sessionId: fixture.session.id,
+        sessionId: session.id,
         messageId: fixture.assistantMessageIds[0],
       },
     })
-    expect(persistence.readFromCalls).toBe(1)
-    await expect(ctx.messageFeedback.list({ sessionId: fixture.session.id })).resolves.toEqual({
+    expect(persistence.readCalls).toBe(1)
+    await expect(ctx.messageFeedback.list({ sessionId: session.id })).resolves.toEqual({
       ok: true,
       value: { items: [] },
     })
@@ -565,7 +562,7 @@ describe('MessageFeedbackService durability ordering', () => {
     ctx.on('domain/changed', (change) => {
       if (change.domain === 'message_feedback') order.push('sidecar:durable')
     })
-    persistence.onReadFrom = () => { order.push('session:verified') }
+    persistence.onRead = () => { order.push('session:verified') }
 
     expectItem(await ctx.messageFeedback.put({
       sessionId: session.id,
@@ -574,7 +571,7 @@ describe('MessageFeedbackService durability ordering', () => {
       ifVersion: null,
     }))
     expect(order).toEqual(['session:durable', 'session:verified', 'sidecar:durable'])
-    expect(persistence.readFromCalls).toBe(1)
+    expect(persistence.readCalls).toBe(1)
     expect(persistence.durable.get(session.id)?.events).toContainEqual(
       expect.objectContaining({ type: 'assistant/message' }),
     )
@@ -655,7 +652,7 @@ describe('MessageFeedbackService durability ordering', () => {
     expect(ctx.sessions.get(session.id)).toBeUndefined()
     release.resolve(undefined)
     expectItem(await pending)
-    expect(persistence.readFromCalls).toBe(1)
+    expect(persistence.readCalls).toBe(1)
     await expect(ctx.messageFeedback.list({ sessionId: session.id })).resolves.toMatchObject({
       ok: true,
       value: { items: [{ messageId: fixture.assistantMessageIds[0] }] },
diff --git a/packages/fs/tool-fs/tests/fs-tools.e2e.ts b/packages/fs/tool-fs/tests/fs-tools.e2e.ts
index 774d04674c..9e15589025 100644
--- a/packages/fs/tool-fs/tests/fs-tools.e2e.ts
+++ b/packages/fs/tool-fs/tests/fs-tools.e2e.ts
@@ -28,7 +28,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('fs tools with-key smoke', () =>
     ctx = await fsHarness(workdir, SYSTEM)
     // agentLoop.create prepares a session with no cwd, so the provider default
     // (config.cwd = workdir) is the workspace.
-    const agent = ctx.agentLoop.create(SessionId('fs-e2e'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    const agent = await ctx.agentLoop.create(SessionId('fs-e2e'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
 
     agent.followup(createUserMessage({
       content: [{ type: 'text', text:
diff --git a/packages/goal/goal-round-driver/tests/goal-round-driver.spec.ts b/packages/goal/goal-round-driver/tests/goal-round-driver.spec.ts
index d2749378bf..9e5ea7e87e 100644
--- a/packages/goal/goal-round-driver/tests/goal-round-driver.spec.ts
+++ b/packages/goal/goal-round-driver/tests/goal-round-driver.spec.ts
@@ -96,7 +96,7 @@ async function harness(script: ScriptEntry[]): Promise<Harness> {
   await ctx.plugin(AgentLoop, { agents: [] })
   const adapter = new ScriptedAdapter(script)
   ctx.llm.registerAdapter(['mock'], adapter)
-  const agent = ctx.agentLoop.create(SessionId(`goal-session-${Math.random()}`), {
+  const agent = await ctx.agentLoop.create(SessionId(`goal-session-${Math.random()}`), {
     provider: 'mock',
     model: 'mock',
   })
@@ -222,7 +222,7 @@ describe('same-session goal driving', () => {
     await ctx.plugin(AgentLoop, { agents: [] })
     const adapter = new ScriptedAdapter([textResponse('after resume')])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('goal-session-hot-load'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('goal-session-hot-load'), { provider: 'mock', model: 'mock' })
     const created = ctx.goals.create(agent, { objective: 'wait for a human', maxGoalRounds: 1 })
 
     await ctx.plugin(goalSession)
diff --git a/packages/guard/repeat-tool-reminder/tests/repeat-tool-reminder.spec.ts b/packages/guard/repeat-tool-reminder/tests/repeat-tool-reminder.spec.ts
index 0ac97a7a0b..b8a32f2370 100644
--- a/packages/guard/repeat-tool-reminder/tests/repeat-tool-reminder.spec.ts
+++ b/packages/guard/repeat-tool-reminder/tests/repeat-tool-reminder.spec.ts
@@ -65,7 +65,7 @@ describe('threshold escalation', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -86,7 +86,7 @@ describe('threshold escalation', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -108,7 +108,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -132,7 +132,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -150,7 +150,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -171,7 +171,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -187,7 +187,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -203,7 +203,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -223,8 +223,8 @@ describe('chain semantics', () => {
       toolCallResponse('b3', 'probe', { q: 1 }),
       textResponse('done'),
     ]))
-    const agentA = ctx.agentLoop.create(SessionId('a'), { provider: 'mock-a', model: 'model-a' })
-    const agentB = ctx.agentLoop.create(SessionId('b'), { provider: 'mock-b', model: 'model-b' })
+    const agentA = await ctx.agentLoop.create(SessionId('a'), { provider: 'mock-a', model: 'model-a' })
+    const agentB = await ctx.agentLoop.create(SessionId('b'), { provider: 'mock-b', model: 'model-b' })
     agentA.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     agentB.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await Promise.all([waitForIdle(ctx, agentA), waitForIdle(ctx, agentB)])
@@ -243,7 +243,7 @@ describe('chain semantics', () => {
       textResponse('turn two done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'again' }], source: { kind: 'user' } }))
@@ -263,15 +263,15 @@ describe('chain semantics', () => {
     // Loop agents are torn down by disposing the scope that created them
     // (the loop.spec pattern): a child plugin fiber owns `first`.
     let first!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      first = inner.agentLoop.create(SessionId('reused'), { provider: 'mock', model: 'mock' })
+    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
+      first = await inner.agentLoop.create(SessionId('reused'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     first.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, first)
     await fiber.dispose()
     await first.whenIdle()
 
-    const second = ctx.agentLoop.create(SessionId('reused'), { provider: 'mock', model: 'mock' })
+    const second = await ctx.agentLoop.create(SessionId('reused'), { provider: 'mock', model: 'mock' })
     second.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, second)
 
@@ -287,7 +287,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -303,7 +303,7 @@ describe('chain semantics', () => {
       toolCallResponse('c1', 'probe', { q: 1 }), // if the direct call had counted, this would be #2
       textResponse('done'),
     ]))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -327,7 +327,7 @@ describe('fold onto the downstream decision', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -357,7 +357,7 @@ describe('fold onto the downstream decision', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
diff --git a/packages/hooks/hooks-claude-code/README.i18n.yaml b/packages/hooks/hooks-claude-code/README.i18n.yaml
index 28a6b22cd9..ac4f5023a5 100644
--- a/packages/hooks/hooks-claude-code/README.i18n.yaml
+++ b/packages/hooks/hooks-claude-code/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/hooks/hooks-claude-code/README.md
-README.md: b90e33a840370215aeb9a0d0f60bd0a0def9adbc
-README.zh.md: a9c183b293b388129e0663bac6c1031312dcb327
+README.md: 6d6d789ec0adc765825adaf49969d281b46b73d9
+README.zh.md: 40ae81924b836dbd4bc28cf61465829cfd25ddde
diff --git a/packages/hooks/hooks-claude-code/README.md b/packages/hooks/hooks-claude-code/README.md
index b90e33a840..6d6d789ec0 100644
--- a/packages/hooks/hooks-claude-code/README.md
+++ b/packages/hooks/hooks-claude-code/README.md
@@ -88,7 +88,7 @@ Each supported event programs against one harness extension point: `SessionStart
 
 ### Payloads and environment
 
-The bridge builds each event's stdin payload from a base of `session_id`, string-shaped `transcript_path`, `cwd`, and `hook_event_name` plus per-event fields. `transcript_path` resolves through `ctx.sessionPersistence.locate(session.header)` when available and otherwise is `''`; lookup never creates or flushes the artifact. `CLAUDE_PROJECT_DIR` defaults per-run to the session workspace when `projectDir` is omitted, matching the directory the hook runs in; `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PROJECT_DIR}` substitution happens at config parse time.
+The bridge builds each event's stdin payload from a base of `session_id`, string-shaped `transcript_path`, `cwd`, and `hook_event_name` plus per-event fields. `transcript_path` stays in the payload for compatibility but is always `''`: the persistence seam exposes no artifact paths, and the default-zstd session log is not readable by hook scripts. `CLAUDE_PROJECT_DIR` defaults per-run to the session workspace when `projectDir` is omitted, matching the directory the hook runs in; `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PROJECT_DIR}` substitution happens at config parse time.
 
 ### Matcher subjects and serial execution
 
@@ -176,9 +176,9 @@ These limits describe what your Claude Code hooks cannot do through this bridge
 - **`UserPromptSubmit` is partial** — blocking and JSON `additionalContext` work, but plain stdout context, `sessionTitle`, and `suppressOriginalPrompt` are unsupported. Unless overridden, the bridge also uses its 600-second default instead of Claude Code's event-specific 30-second command timeout.
 - **`PreToolUse` is partial** — `deny` and `ask` decisions work; `allow` does not pre-approve, `defer` is unsupported, `additionalContext` is ignored, and `updatedInput` is logged + warned but not honored ([the pre-tool-input-rewrite Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md)).
 - **`PostToolUse` is partial** — blocking feedback and JSON `additionalContext` work, but `updatedToolOutput` and `updatedMCPToolOutput` are unsupported and `tool_response` is flattened to text.
-- **`SubagentStart` and `SubagentStop` are partial** — both report a constant `agent_type` of `general-purpose` and use the child session id where Claude Code reports the parent session. Start context is best-effort and can only reach a live in-process child; stop is observe-only and cannot block the subagent or feed it context. Start omits `transcript_path`; stop also omits `agent_transcript_path`, `last_assistant_message`, `background_tasks`, and `session_crons` and always reports `stop_hook_active: false`.
+- **`SubagentStart` and `SubagentStop` are partial** — both report a constant `agent_type` of `general-purpose` and use the child session id where Claude Code reports the parent session. Start context is best-effort and can only reach a live in-process child; stop is observe-only and cannot block the subagent or feed it context. Stop omits `agent_transcript_path`, `last_assistant_message`, `background_tasks`, and `session_crons` and always reports `stop_hook_active: false`.
 - **`Stop` is partial** — blocking forces another model turn, but `stop_hook_active` is always `false`, `last_assistant_message`, `background_tasks`, and `session_crons` are omitted, and the consecutive-block cap is not implemented. An unconditionally blocking hook therefore force-continues every step unless it self-limits.
-- **Common payload and output fields are partial** — mapped event payloads omit `prompt_id`, `transcript_path`, `permission_mode`, and `effort` where Claude Code would provide them. `systemMessage` is logged + warned but not surfaced; `{"continue": false}` is recorded but does not halt the run; `suppressOutput`, `stopReason`, and `terminalSequence` are not applied.
+- **Common payload and output fields are partial** — mapped event payloads omit `prompt_id`, `permission_mode`, and `effort` where Claude Code would provide them, and `transcript_path` is never populated: it is always the empty string, because the persistence seam exposes no artifact paths and the default-zstd session log is not readable by hook scripts. `systemMessage` is logged + warned but not surfaced; `{"continue": false}` is recorded but does not halt the run; `suppressOutput`, `stopReason`, and `terminalSequence` are not applied.
 - **Handler and config support is partial** — only shell-form command handlers run. `http`, `mcp_tool`, `prompt`, and `agent` handlers are skipped; command-handler options such as `args`, `async`, `asyncRewake`, `shell`, `if`, `once`, and `statusMessage` are not honored. Matching handlers run serially and are not deduplicated, whereas Claude Code runs them in parallel and deduplicates identical handlers. One process-level `configPath` is parsed once at load; Claude Code's layered project, user, plugin, and policy discovery and live reload are not implemented.
 
 <a id="dev-note"></a>
diff --git a/packages/hooks/hooks-claude-code/README.zh.md b/packages/hooks/hooks-claude-code/README.zh.md
index a9c183b293..40ae81924b 100644
--- a/packages/hooks/hooks-claude-code/README.zh.md
+++ b/packages/hooks/hooks-claude-code/README.zh.md
@@ -88,7 +88,7 @@ kind: "package-reference"
 
 ### 载荷与环境
 
-桥接从 `session_id`、字符串形态的 `transcript_path`、`cwd` 与 `hook_event_name` 的基础字段加逐事件字段构建每个事件的 stdin payload。可用时 `transcript_path` 通过 `ctx.sessionPersistence.locate(session.header)` 解析，否则为 `''`；查找从不创建或 flush 产物。省略 `projectDir` 时，`CLAUDE_PROJECT_DIR` 按次默认到会话工作区，与钩子运行的目录一致；`${CLAUDE_PLUGIN_ROOT}` 与 `${CLAUDE_PROJECT_DIR}` 替换在配置解析时进行。
+桥接从 `session_id`、字符串形态的 `transcript_path`、`cwd` 与 `hook_event_name` 的基础字段加逐事件字段构建每个事件的 stdin payload。`transcript_path` 出于兼容性保留在 payload 中，但始终为 `''`：持久化 seam 不暴露产物路径，且默认 zstd 压缩的会话日志无法被 hook 脚本读取。省略 `projectDir` 时，`CLAUDE_PROJECT_DIR` 按次默认到会话工作区，与钩子运行的目录一致；`${CLAUDE_PLUGIN_ROOT}` 与 `${CLAUDE_PROJECT_DIR}` 替换在配置解析时进行。
 
 ### Matcher subject 与串行执行
 
@@ -176,9 +176,9 @@ hook 不返回上下文时没有成本。Hook 文本取决于数据，会被记
 - **`UserPromptSubmit` 只支持部分功能**——支持阻塞与 JSON `additionalContext`，但不支持纯 stdout 上下文、`sessionTitle` 与 `suppressOriginalPrompt`。除非被覆盖，否则桥接还会使用自身 600 秒默认值，而非 Claude Code 的事件特定 30 秒 command 超时。
 - **`PreToolUse` 只支持部分功能**——`deny` 与 `ask` 决策可用；`allow` 不会预审批，`defer` 不受支持，`additionalContext` 会被忽略，`updatedInput` 会被记录 + 警告但不应用（见 [pre-tool-input-rewrite Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md)）。
 - **`PostToolUse` 只支持部分功能**——支持阻塞反馈与 JSON `additionalContext`，但不支持 `updatedToolOutput` 与 `updatedMCPToolOutput`，`tool_response` 会展平为文本。
-- **`SubagentStart` 与 `SubagentStop` 只支持部分功能**——两者均报告常量 `agent_type` `general-purpose`，并在 Claude Code 报告父会话的位置使用 child 会话 id。Start 上下文是尽力而为，且只能到达仍在运行的同进程 child；stop 只观测，无法阻塞 subagent 或向其提供上下文。Start 省略 `transcript_path`；stop 还省略 `agent_transcript_path`、`last_assistant_message`、`background_tasks` 与 `session_crons`，并始终报告 `stop_hook_active: false`。
+- **`SubagentStart` 与 `SubagentStop` 只支持部分功能**——两者均报告常量 `agent_type` `general-purpose`，并在 Claude Code 报告父会话的位置使用 child 会话 id。Start 上下文是尽力而为，且只能到达仍在运行的同进程 child；stop 只观测，无法阻塞 subagent 或向其提供上下文。Stop 省略 `agent_transcript_path`、`last_assistant_message`、`background_tasks` 与 `session_crons`，并始终报告 `stop_hook_active: false`。
 - **`Stop` 只支持部分功能**——阻塞会强制另一个模型轮次，但 `stop_hook_active` 始终为 `false`，会省略 `last_assistant_message`、`background_tasks` 与 `session_crons`，且未实现连续阻塞上限。因此，无条件阻塞 hook 会在每个步骤中强制 continuation，除非它自我限制。
-- **通用 payload 与输出字段只支持部分功能**——已映射事件会省略 Claude Code 原本会提供的 `prompt_id`、`transcript_path`、`permission_mode` 与 `effort`。`systemMessage` 会被记录 + 警告但不呈现；`{"continue": false}` 会被记录但不会停止运行；`suppressOutput`、`stopReason` 与 `terminalSequence` 不会被应用。
+- **通用 payload 与输出字段只支持部分功能**——已映射事件会省略 Claude Code 原本会提供的 `prompt_id`、`permission_mode` 与 `effort`，且 `transcript_path` 永不填充：它始终为空字符串，因为持久化 seam 不暴露产物路径，且默认 zstd 压缩的会话日志无法被 hook 脚本读取。`systemMessage` 会被记录 + 警告但不呈现；`{"continue": false}` 会被记录但不会停止运行；`suppressOutput`、`stopReason` 与 `terminalSequence` 不会被应用。
 - **Handler 与配置只支持部分功能**——只运行 shell 形态 command handler。会跳过 `http`、`mcp_tool`、`prompt` 与 `agent` handler；`args`、`async`、`asyncRewake`、`shell`、`if`、`once` 与 `statusMessage` 等 command handler 选项不会被遵循。匹配 handler 串行运行且不去重，而 Claude Code 会并行运行并对相同 handler 去重。一个进程级 `configPath` 会在加载时解析一次；尚未实现 Claude Code 的分层项目、用户、插件与策略发现以及实时重新加载。
 
 <a id="dev-note"></a>
diff --git a/packages/hooks/hooks-claude-code/package.json b/packages/hooks/hooks-claude-code/package.json
index 1514cb9da6..1e40a29e66 100644
--- a/packages/hooks/hooks-claude-code/package.json
+++ b/packages/hooks/hooks-claude-code/package.json
@@ -34,7 +34,6 @@
     "@deepseek-ai/dsh-hook-protocol": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^",
@@ -50,7 +49,6 @@
     "@deepseek-ai/dsh-hook-protocol": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
diff --git a/packages/hooks/hooks-claude-code/src/index.ts b/packages/hooks/hooks-claude-code/src/index.ts
index e82b728a8e..688d1a065b 100644
--- a/packages/hooks/hooks-claude-code/src/index.ts
+++ b/packages/hooks/hooks-claude-code/src/index.ts
@@ -17,7 +17,6 @@ import type {} from '@deepseek-ai/dsh-session-projection'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { UserMessage } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-session-persistence'
 import type { PostToolDecision, PreToolDecision, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import {
   appendHookInvoked,
@@ -205,7 +204,7 @@ export function apply(ctx: Context, config: Config): void {
   // may miss the first request.
   // TODO(session-start-gating): add a startup gate before promising first-turn delivery.
   ctx.on('agent/session-start', ({ agent, source }) => {
-    detached.track(runPoint('SessionStart', source, sessionStartPayload(ctx, agent, source), { agent, signal: detached.signal })
+    detached.track(runPoint('SessionStart', source, sessionStartPayload(agent, source), { agent, signal: detached.signal })
       .then((merged) => {
         const context = contextFrom(merged)
         if (context) agent.inject(context)
@@ -220,7 +219,7 @@ export function apply(ctx: Context, config: Config): void {
   ctx.on('agent/pre-step', async ({ agent, messages, turn, signal }, next): Promise<PreStepDecision> => {
     if (messages.length === 0) return next()
     const content = messages.flatMap(message => message.content)
-    const merged = await runPoint('UserPromptSubmit', '', promptPayload(ctx, agent, content), { agent, turn, signal })
+    const merged = await runPoint('UserPromptSubmit', '', promptPayload(agent, content), { agent, turn, signal })
     if (merged.decision === 'deny') {
       return { kind: 'reject' }
     }
@@ -238,7 +237,7 @@ export function apply(ctx: Context, config: Config): void {
   // --- PreToolUse → PreToolDecision. Matcher subject is the tool name. ---
   ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
     const turn = lastTurn(ctx, exec.agent)
-    const merged = await runPoint('PreToolUse', exec.name, preToolPayload(ctx, exec), { ...exec.agent ? { agent: exec.agent } : {}, turn, signal: exec.signal })
+    const merged = await runPoint('PreToolUse', exec.name, preToolPayload(exec), { ...exec.agent ? { agent: exec.agent } : {}, turn, signal: exec.signal })
     if (merged.decision === 'deny') return { kind: 'deny', reason: merged.reason ?? 'blocked by PreToolUse hook' }
     if (merged.decision === 'ask') return { kind: 'ask', ...merged.reason !== undefined ? { reason: merged.reason } : {} }
     return next()
@@ -247,7 +246,7 @@ export function apply(ctx: Context, config: Config): void {
   // --- PostToolUse → PostToolDecision. Matcher subject is the tool name. ---
   ctx.on('tools/post-execute', async (exec, result, next): Promise<PostToolDecision> => {
     const turn = lastTurn(ctx, exec.agent)
-    const merged = await runPoint('PostToolUse', exec.name, postToolPayload(ctx, exec, result), { ...exec.agent ? { agent: exec.agent } : {}, turn, signal: exec.signal })
+    const merged = await runPoint('PostToolUse', exec.name, postToolPayload(exec, result), { ...exec.agent ? { agent: exec.agent } : {}, turn, signal: exec.signal })
     const context = contextFrom(merged)
     if (merged.decision === 'deny') {
       return { kind: 'block', feedback: [{ type: 'text', text: merged.reason ?? 'blocked by PostToolUse hook' }], ...context ? { additionalContexts: [context] } : {} }
@@ -269,7 +268,7 @@ export function apply(ctx: Context, config: Config): void {
   // machine observe pending input and run another step.
   // TODO(stop-loop-guard): cap consecutive forced continuations; hooks must self-limit meanwhile.
   ctx.on('agent/turn-stopping', async ({ agent, turn, signal }): Promise<void> => {
-    const merged = await runPoint('Stop', '', stopPayload(ctx, agent), { agent, turn, signal })
+    const merged = await runPoint('Stop', '', stopPayload(agent), { agent, turn, signal })
     if (merged.decision === 'deny') {
       // A blocking Stop hook forces continuation.
       const text = merged.reason ?? 'continue: blocked by Stop hook'
@@ -282,7 +281,7 @@ export function apply(ctx: Context, config: Config): void {
   ctx.on('subagent/start', (info) => {
     const child = ctx.get('agents')?.get(info.id)
     if (child !== undefined) subagentChildren.set(info.runId, child)
-    detached.track(runPoint('SubagentStart', SUBAGENT_TYPE, subagentPayload(ctx, 'SubagentStart', info, child), { ...child ? { agent: child } : {}, signal: detached.signal })
+    detached.track(runPoint('SubagentStart', SUBAGENT_TYPE, subagentPayload('SubagentStart', info, child), { ...child ? { agent: child } : {}, signal: detached.signal })
       .then((merged) => {
         const context = contextFrom(merged)
         if (context && child) child.inject(context)
@@ -292,7 +291,7 @@ export function apply(ctx: Context, config: Config): void {
   ctx.on('subagent/end', (info) => {
     const child = subagentChildren.get(info.runId) ?? ctx.get('agents')?.get(info.id)
     subagentChildren.delete(info.runId)
-    detached.track(runPoint('SubagentStop', SUBAGENT_TYPE, subagentPayload(ctx, 'SubagentStop', info, child), { ...child ? { agent: child } : {}, signal: detached.signal }))
+    detached.track(runPoint('SubagentStop', SUBAGENT_TYPE, subagentPayload('SubagentStop', info, child), { ...child ? { agent: child } : {}, signal: detached.signal }))
   })
 }
 
@@ -319,31 +318,31 @@ function blocksToText(content: ContentBlock[]): string {
   return content.filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text').map(b => b.text).join('')
 }
 
-function base(ctx: Context, agent: Agent | undefined, event: string): Record<string, unknown> {
+function base(agent: Agent | undefined, event: string): Record<string, unknown> {
   return {
     session_id: agent?.session.header.id ?? '',
-    transcript_path: agent === undefined
-      ? ''
-      : ctx.get('sessionPersistence')?.locate(agent.session.header)?.path ?? '',
+    // The persistence seam exposes no artifact path; the field stays empty
+    // (a durable consumer gap recorded in this package's README).
+    transcript_path: '',
     cwd: agent?.session.header.cwd ?? process.cwd(),
     hook_event_name: event,
   }
 }
 
-function sessionStartPayload(ctx: Context, agent: Agent, source: string): Record<string, unknown> {
-  return { ...base(ctx, agent, 'SessionStart'), source }
+function sessionStartPayload(agent: Agent, source: string): Record<string, unknown> {
+  return { ...base(agent, 'SessionStart'), source }
 }
-function promptPayload(ctx: Context, agent: Agent, content: ContentBlock[]): Record<string, unknown> {
-  return { ...base(ctx, agent, 'UserPromptSubmit'), prompt: blocksToText(content) }
+function promptPayload(agent: Agent, content: ContentBlock[]): Record<string, unknown> {
+  return { ...base(agent, 'UserPromptSubmit'), prompt: blocksToText(content) }
 }
-function preToolPayload(ctx: Context, exec: ToolExecution): Record<string, unknown> {
-  return { ...base(ctx, exec.agent, 'PreToolUse'), tool_name: exec.name, tool_input: exec.arguments, tool_use_id: exec.callId }
+function preToolPayload(exec: ToolExecution): Record<string, unknown> {
+  return { ...base(exec.agent, 'PreToolUse'), tool_name: exec.name, tool_input: exec.arguments, tool_use_id: exec.callId }
 }
-function postToolPayload(ctx: Context, exec: ToolExecution, result: ToolExecutionResult): Record<string, unknown> {
-  return { ...base(ctx, exec.agent, 'PostToolUse'), tool_name: exec.name, tool_input: exec.arguments, tool_use_id: exec.callId, tool_response: blocksToText(result.content) }
+function postToolPayload(exec: ToolExecution, result: ToolExecutionResult): Record<string, unknown> {
+  return { ...base(exec.agent, 'PostToolUse'), tool_name: exec.name, tool_input: exec.arguments, tool_use_id: exec.callId, tool_response: blocksToText(result.content) }
 }
-function stopPayload(ctx: Context, agent: Agent): Record<string, unknown> {
-  return { ...base(ctx, agent, 'Stop'), stop_hook_active: false }
+function stopPayload(agent: Agent): Record<string, unknown> {
+  return { ...base(agent, 'Stop'), stop_hook_active: false }
 }
 /**
  * Build a SubagentStart/SubagentStop payload from the CC base (the child's
@@ -351,9 +350,9 @@ function stopPayload(ctx: Context, agent: Agent): Record<string, unknown> {
  * fields. `agent_type` is the CC-default {@link SUBAGENT_TYPE}; `stop_hook_active`
  * is present on SubagentStop only (the loop-guard flag, always false).
  */
-function subagentPayload(ctx: Context, event: 'SubagentStart' | 'SubagentStop', info: { id: string }, child: Agent | undefined): Record<string, unknown> {
+function subagentPayload(event: 'SubagentStart' | 'SubagentStop', info: { id: string }, child: Agent | undefined): Record<string, unknown> {
   return {
-    ...base(ctx, child, event),
+    ...base(child, event),
     agent_id: info.id,
     agent_type: SUBAGENT_TYPE,
     ...event === 'SubagentStop' ? { stop_hook_active: false } : {},
diff --git a/packages/hooks/hooks-claude-code/tests/bridge.spec.ts b/packages/hooks/hooks-claude-code/tests/bridge.spec.ts
index fb24106d0e..7f5facfa65 100644
--- a/packages/hooks/hooks-claude-code/tests/bridge.spec.ts
+++ b/packages/hooks/hooks-claude-code/tests/bridge.spec.ts
@@ -103,7 +103,7 @@ describe('hooks-claude-code bridge — UserPromptSubmit', () => {
 
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'do something' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -124,7 +124,7 @@ describe('hooks-claude-code bridge — UserPromptSubmit', () => {
 
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -149,7 +149,7 @@ describe('hooks-claude-code bridge — PreToolUse', () => {
     const ctx = await harness(dir, adapter)
     let ran = false
     ctx.tools.register(defineContentToolFixture({ name: 'danger', description: 'd', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] } }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'use danger' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -172,7 +172,7 @@ describe('hooks-claude-code bridge — PreToolUse', () => {
     const ctx = await harness(dir, adapter)
     let ran = false
     ctx.tools.register(defineContentToolFixture({ name: 'safe', description: 's', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ran ok' }] } }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'use safe' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -194,7 +194,7 @@ describe('hooks-claude-code bridge — PostToolUse', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
     ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'raw output' }] } }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -215,7 +215,7 @@ describe('hooks-claude-code bridge — PostToolUse', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
     ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -239,7 +239,7 @@ describe('hooks-claude-code bridge — PostToolUse', () => {
     const ctx = await harness(dir, adapter)
     let ran = false
     ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -263,7 +263,7 @@ describe('hooks-claude-code bridge — SessionStart', () => {
 
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     // session-start fires async (detached .then → agent.inject); injection now
     // enters the next-step inbox directly and becomes a user/message only after
     // step entry, so synchronize on the pending inbox item before sending.
@@ -362,7 +362,7 @@ describe('hooks-claude-code bridge — load resilience', () => {
     await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
     await ctx.plugin(HooksClaude, { configPath: '/nonexistent/hooks.json' })
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     // The turn ran normally — no hooks, no crash.
@@ -377,7 +377,7 @@ describe('hooks-claude-code bridge — load resilience', () => {
     const adapter = new MockAdapter([textResponse('fine')])
     const warn = vi.fn()
     const ctx = await harness(dir, adapter, (ctx) => { ctx.logger.warn = warn as never })
-    const agent = ctx.agentLoop.create(SessionId('invalid-claude-matcher'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('invalid-claude-matcher'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1)
@@ -396,7 +396,7 @@ describe('hooks-claude-code bridge — load resilience', () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const warn = vi.fn()
     const ctx = await harness(dir, adapter, (ctx) => { ctx.logger.warn = warn as never })
-    const agent = ctx.agentLoop.create(SessionId('unsupported-claude-matcher'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('unsupported-claude-matcher'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -424,7 +424,7 @@ describe('hooks-claude-code bridge — load resilience', () => {
     const fiber = await ctx.plugin(HooksClaude, { configPath: join(dir, 'hooks.json') })
     await fiber.dispose()
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1) // not blocked → the listener is gone
diff --git a/packages/hooks/hooks-claude-code/tests/coverage-cases.ts b/packages/hooks/hooks-claude-code/tests/coverage-cases.ts
index af39599dd2..0f90281364 100644
--- a/packages/hooks/hooks-claude-code/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-claude-code/tests/coverage-cases.ts
@@ -70,27 +70,20 @@ export type CoverageGroup = 'config' | 'stop' | 'context' | 'edge-paths'
 /** Register independently schedulable slices of the hooks-claude-code coverage matrix. */
 export function defineCoverageCases(group: CoverageGroup): void {
   if (group === 'config') describe('hooks-claude-code coverage — config option arms + substitution + skip warning', () => {
-    it('uses the persistence locator for transcript_path and an empty string without one', async () => {
-      async function capture(sessionRoot?: string): Promise<{ payload: { transcript_path: string }; expected: string | undefined }> {
-        const d = dir()
-        const cap = join(d, 'payload')
-        const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'capture.sh', `#!/usr/bin/env bash\ncat > "${cap}"\n`) }] }] })
-        const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
-        const ctx = await harness(path, adapter, { ...sessionRoot !== undefined ? { sessionRoot } : {} })
-        ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-        const agent = ctx.agentLoop.create(SessionId('transcript'), { provider: 'mock', model: 'mock' })
-        agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
-        await waitForIdle(ctx, agent)
-        return {
-          payload: JSON.parse(readFileSync(cap, 'utf8')) as { transcript_path: string },
-          expected: ctx.get('sessionPersistence')?.locate(agent.session.header)?.path,
-        }
-      }
-
-      const located = await capture(dir())
-      expect(located.payload.transcript_path).toBe(located.expected)
-      expect((await capture()).payload.transcript_path).toBe('')
-    }, 15_000) // Two real agent/hook subprocess loops need process startup and teardown headroom.
+    it('degrades transcript_path to the empty string even with persistence mounted', async () => {
+      const d = dir()
+      const cap = join(d, 'payload')
+      const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'capture.sh', `#!/usr/bin/env bash\ncat > "${cap}"\n`) }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter, { sessionRoot: dir() })
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = await ctx.agentLoop.create(SessionId('transcript'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      // The persistence seam exposes no artifact paths, so the field stays ''
+      // even with a persistence backend mounted.
+      expect((JSON.parse(readFileSync(cap, 'utf8')) as { transcript_path: string }).transcript_path).toBe('')
+    }, 15_000) // The real agent/hook subprocess loop needs process startup and teardown headroom.
 
     it('honors pluginRoot + projectDir substitution and warns on a skipped non-command hook', async () => {
       const d = dir()
@@ -108,7 +101,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter, { pluginRoot: d, projectDir: d })
       ctx.logger.warn = warn as never
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true) // substituted command ran
@@ -124,7 +117,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       ctx.logger.warn = warn as never
       let sawArgs: unknown
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: { command: { type: 'string' } }, async execute(args) { sawArgs = args; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       // updatedInput is NOT honored — the tool ran with the ORIGINAL args.
@@ -140,7 +133,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('ran')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       // The prompt proceeded unchanged; no injected context.
@@ -168,7 +161,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -193,7 +186,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter, { stderrSummaryMaxChars: 40 })
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -209,7 +202,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { Stop: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(2)
@@ -225,7 +218,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { Stop: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       // A second model request ran → the empty-reason block forced continuation.
@@ -278,7 +271,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'x' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -292,7 +285,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -321,7 +314,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('no')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       expect(events(agent).filter(e => e.type === 'turn/start' || e.type === 'hook/invoked'
@@ -337,7 +330,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       // ask (no reason) → degrades to deny with the registry's generic message.
@@ -352,7 +345,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -379,7 +372,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       // the protocol lib's reference default, not a config knob).
       HooksClaude.apply(ctx, { configPath: join(d, 'hooks.json') })
       ctx.llm.registerAdapter(['mock'], adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true)
@@ -394,7 +387,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
@@ -409,7 +402,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -428,7 +421,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -445,7 +438,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -465,7 +458,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // the mismatched deny was discarded → the tool ran
@@ -503,7 +496,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       ctx.on('agent/pre-step', async () => ({
         kind: 'reject' as const,
       }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       // the downstream block won: the model was never called, no user/message was
@@ -533,7 +526,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
           source: { kind: 'plugin' as const, plugin: 'policy' },
         })],
       }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const req = JSON.stringify(adapter.requests[0]!.messages)
@@ -560,7 +553,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, value: [{ type: 'text' as const, text: 'rewritten-result' }] }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -582,7 +575,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
           source: { kind: 'plugin' as const, plugin: 'policy' },
         })],
       }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
 
@@ -604,7 +597,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'block' as const, feedback: [{ type: 'text' as const, text: 'downstream-block' }] }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -628,7 +621,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const bash = ctx.shell
       bash.run = (() => Promise.reject(new Error('executor down')))
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -644,7 +637,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       // Make inject throw, forcing the SessionStart .catch path.
       const original = agent.inject.bind(agent)
       let threw = false
@@ -737,7 +730,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(path, adapter)
       const warn = vi.fn(); ctx.logger.warn = warn as never
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('systemMessage'))
@@ -755,7 +748,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       // Send immediately — do NOT wait for the session-start inject.
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
       await waitForIdle(ctx, agent)
diff --git a/packages/hooks/hooks-claude-code/tsconfig.json b/packages/hooks/hooks-claude-code/tsconfig.json
index 23a293d40e..64e0fa1ad4 100644
--- a/packages/hooks/hooks-claude-code/tsconfig.json
+++ b/packages/hooks/hooks-claude-code/tsconfig.json
@@ -29,9 +29,6 @@
     {
       "path": "../../core/session"
     },
-    {
-      "path": "../../session/session-persistence"
-    },
     {
       "path": "../../subagent/subagent"
     },
diff --git a/packages/hooks/hooks-codex/README.i18n.yaml b/packages/hooks/hooks-codex/README.i18n.yaml
index 1c241537fb..b03504ee30 100644
--- a/packages/hooks/hooks-codex/README.i18n.yaml
+++ b/packages/hooks/hooks-codex/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/hooks/hooks-codex/README.md
-README.md: 9d2a2d5aff7d97521178725e5ef7ec44fce20330
-README.zh.md: 4e672e37caa42a2dcabbefe4c71549820cee9bc2
+README.md: 8ab22336f5558ab3ab7ce0fe83621994fa7b8092
+README.zh.md: ad7c2790cba3d87262f2c3b2949eb0c74d823c72
diff --git a/packages/hooks/hooks-codex/README.md b/packages/hooks/hooks-codex/README.md
index 9d2a2d5aff..8ab22336f5 100644
--- a/packages/hooks/hooks-codex/README.md
+++ b/packages/hooks/hooks-codex/README.md
@@ -84,7 +84,7 @@ Each supported event programs against one harness extension point: `SessionStart
 
 ### Payloads and environment
 
-Payloads are Codex-shaped: snake_case with `turn_id` on turn-scoped events, `model` and `permission_mode: "default"` on every event, and stdin written without a trailing newline. A tool call's payload carries the real `tool_name` and the `tool_input: { command }` shape (the `command` argument when present, else `''`), so non-shell tool arguments are not faithfully exposed. The base payload carries `session_id` and `transcript_path`; the latter resolves through `ctx.sessionPersistence.locate(session.header)` when available and otherwise is `null`, preserving the Codex `string | null` shape — lookup never creates or flushes the artifact. Codex performs no command substitution and injects no plugin environment.
+Payloads are Codex-shaped: snake_case with `turn_id` on turn-scoped events, `model` and `permission_mode: "default"` on every event, and stdin written without a trailing newline. A tool call's payload carries the real `tool_name` and the `tool_input: { command }` shape (the `command` argument when present, else `''`), so non-shell tool arguments are not faithfully exposed. The base payload carries `session_id` and `transcript_path`; the latter keeps the Codex `string | null` shape but is always `null` — the persistence seam exposes no artifact paths, and the default-zstd session log is not readable by hook scripts. Codex performs no command substitution and injects no plugin environment.
 
 ### Matcher subjects and serial execution
 
@@ -173,7 +173,7 @@ These limits describe what your Codex hooks cannot do through this bridge yet, a
 - **`PreToolUse` is partial** — blocking works, but `additionalContext`, `permissionDecision: "allow"`, and `updatedInput` are ignored. Every tool is represented as `tool_input: { command }`, so non-shell tool arguments are not faithfully exposed to the hook.
 - **`PostToolUse` is partial** — blocking feedback and JSON `additionalContext` work, but `{"continue": false}` is not enforced, non-shell tool arguments are reduced to `{ command }`, and structured tool output is flattened to text in `tool_response`.
 - **`Stop` is partial** — blocking forces another model turn, but `stop_hook_active` is always `false`, `last_assistant_message` is always `null`, and `{"continue": false}` is not enforced. An unconditionally blocking hook therefore force-continues every step unless it self-limits.
-- **Common payload and output fields are partial** — every mapped event reports the statically configured `model` and `permission_mode: "default"` instead of current Codex runtime values. `systemMessage` is logged + warned but not surfaced, and `{"continue": false}` is recorded but does not apply Codex's event-specific stop behavior.
+- **Common payload and output fields are partial** — every mapped event reports the statically configured `model` and `permission_mode: "default"` instead of current Codex runtime values, and `transcript_path` is never populated: it is always `null`, because the persistence seam exposes no artifact paths and the default-zstd session log is not readable by hook scripts. `systemMessage` is logged + warned but not surfaced, and `{"continue": false}` is recorded but does not apply Codex's event-specific stop behavior.
 - **Config loading and execution are partial** — one process-level `configPath` is parsed at load; Codex's active user, project, session, system/managed, and plugin layers, trust controls, and inline `config.toml` hook form are not implemented. Only synchronous `command` handlers run, current metadata such as `statusMessage` and `commandWindows` is ignored, and matching handlers run serially rather than with Codex's concurrent launch semantics.
 
 <a id="dev-note"></a>
diff --git a/packages/hooks/hooks-codex/README.zh.md b/packages/hooks/hooks-codex/README.zh.md
index 4e672e37ca..ad7c2790cb 100644
--- a/packages/hooks/hooks-codex/README.zh.md
+++ b/packages/hooks/hooks-codex/README.zh.md
@@ -84,7 +84,7 @@ kind: "package-reference"
 
 ### 载荷与环境
 
-payload 采用 Codex 形状：snake_case，轮次事件带 `turn_id`，每个事件都带 `model` 与 `permission_mode: "default"`，stdin 写入时不带尾随换行符。工具调用的 payload 携带真实 `tool_name` 与 `tool_input: { command }` 形状（存在 `command` 参数时使用该值，否则使用 `''`），因此非 shell 工具参数不会被如实公开。基础 payload 携带 `session_id` 与 `transcript_path`；可用时后者通过 `ctx.sessionPersistence.locate(session.header)` 解析，否则为 `null`，保留 Codex `string | null` 形状——查找从不创建或 flush 产物。Codex 不进行命令替换，也不注入插件环境。
+payload 采用 Codex 形状：snake_case，轮次事件带 `turn_id`，每个事件都带 `model` 与 `permission_mode: "default"`，stdin 写入时不带尾随换行符。工具调用的 payload 携带真实 `tool_name` 与 `tool_input: { command }` 形状（存在 `command` 参数时使用该值，否则使用 `''`），因此非 shell 工具参数不会被如实公开。基础 payload 携带 `session_id` 与 `transcript_path`；后者保留 Codex `string | null` 形状但始终为 `null`——持久化 seam 不暴露产物路径，且默认 zstd 压缩的会话日志无法被 hook 脚本读取。Codex 不进行命令替换，也不注入插件环境。
 
 ### Matcher subject 与串行执行
 
@@ -173,7 +173,7 @@ hook 不返回上下文时没有成本。Hook 文本取决于数据，会被记
 - **`PreToolUse` 只支持部分功能**——支持阻塞，但会忽略 `additionalContext`、`permissionDecision: "allow"` 与 `updatedInput`。每个工具都表示为 `tool_input: { command }`，因此非 shell 工具参数不会被如实公开给 hook。
 - **`PostToolUse` 只支持部分功能**——支持阻塞反馈与 JSON `additionalContext`，但不会强制执行 `{"continue": false}`，非 shell 工具参数会缩减为 `{ command }`，结构化工具输出会在 `tool_response` 中展平为文本。
 - **`Stop` 只支持部分功能**——阻塞会强制另一个模型轮次，但 `stop_hook_active` 始终为 `false`，`last_assistant_message` 始终为 `null`，且不会强制执行 `{"continue": false}`。因此，无条件阻塞 hook 会在每个步骤中强制 continuation，除非它自我限制。
-- **通用 payload 与输出字段只支持部分功能**——每个已映射事件都报告静态配置的 `model` 与 `permission_mode: "default"`，而非当前 Codex 运行时值。`systemMessage` 会被记录 + 警告但不呈现，`{"continue": false}` 会被记录但不会应用 Codex 的事件特定停止行为。
+- **通用 payload 与输出字段只支持部分功能**——每个已映射事件都报告静态配置的 `model` 与 `permission_mode: "default"`，而非当前 Codex 运行时值，且 `transcript_path` 永不填充：它始终为 `null`，因为持久化 seam 不暴露产物路径，且默认 zstd 压缩的会话日志无法被 hook 脚本读取。`systemMessage` 会被记录 + 警告但不呈现，`{"continue": false}` 会被记录但不会应用 Codex 的事件特定停止行为。
 - **配置加载与执行只支持部分功能**——一个进程级 `configPath` 会在加载时解析；尚未实现 Codex 的活动用户层、项目层、会话层、系统／托管层与插件层、信任控制以及内联 `config.toml` hook 形态。只运行同步 `command` handler，`statusMessage` 与 `commandWindows` 等当前元数据会被忽略，匹配 handler 串行运行，而非使用 Codex 的并发启动语义。
 
 <a id="dev-note"></a>
diff --git a/packages/hooks/hooks-codex/package.json b/packages/hooks/hooks-codex/package.json
index affd0cce6d..fd00a9c787 100644
--- a/packages/hooks/hooks-codex/package.json
+++ b/packages/hooks/hooks-codex/package.json
@@ -34,7 +34,6 @@
     "@deepseek-ai/dsh-hook-protocol": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^"
@@ -49,7 +48,6 @@
     "@deepseek-ai/dsh-hook-protocol": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^",
diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts
index b8f8027c88..c3c408fb7d 100644
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -20,7 +20,6 @@ import type {} from '@deepseek-ai/dsh-session-projection'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { UserMessage } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-session-persistence'
 import type { PostToolDecision, PreToolDecision, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import {
   appendHookInvoked,
@@ -187,7 +186,7 @@ export function apply(ctx: Context, config: Config): void {
   // hook may miss the first request.
   // TODO(session-start-gating): add a startup gate before promising first-turn delivery.
   ctx.on('agent/session-start', ({ agent, source }) => {
-    detached.track(runPoint('SessionStart', source, { ...base(ctx, agent, 'SessionStart', model), source }, { agent, plainStdoutAsContext: true, signal: detached.signal })
+    detached.track(runPoint('SessionStart', source, { ...base(agent, 'SessionStart', model), source }, { agent, plainStdoutAsContext: true, signal: detached.signal })
       .then((merged) => {
         const context = contextFrom(merged)
         if (context) agent.inject(context)
@@ -200,7 +199,7 @@ export function apply(ctx: Context, config: Config): void {
   ctx.on('agent/pre-step', async ({ agent, messages, turn, signal }, next): Promise<PreStepDecision> => {
     if (messages.length === 0) return next()
     const payload = {
-      ...base(ctx, agent, 'UserPromptSubmit', model),
+      ...base(agent, 'UserPromptSubmit', model),
       turn_id: String(turn),
       prompt: blocksToText(messages.flatMap(message => message.content)),
     }
@@ -289,12 +288,12 @@ function blocksToText(content: ContentBlock[]): string {
 /* jscpd:ignore-end */
 
 /** Base fields on every Codex payload (no turn_id). */
-function base(ctx: Context, agent: Agent | undefined, event: string, model: string): Record<string, unknown> {
+function base(agent: Agent | undefined, event: string, model: string): Record<string, unknown> {
   return {
     session_id: agent?.session.header.id ?? '',
-    transcript_path: agent === undefined
-      ? null
-      : ctx.get('sessionPersistence')?.locate(agent.session.header)?.path ?? null,
+    // The persistence seam exposes no artifact path; the field stays null
+    // (a durable consumer gap recorded in this package's README).
+    transcript_path: null,
     cwd: agent?.session.header.cwd ?? process.cwd(),
     hook_event_name: event,
     model,
@@ -304,7 +303,7 @@ function base(ctx: Context, agent: Agent | undefined, event: string, model: stri
 
 /** Base + turn_id, for the turn-scoped events (PreToolUse/PostToolUse/UserPromptSubmit/Stop). */
 function turnBase(ctx: Context, agent: Agent | undefined, event: string, model: string): Record<string, unknown> {
-  return { ...base(ctx, agent, event, model), turn_id: String(lastTurn(ctx, agent)) }
+  return { ...base(agent, event, model), turn_id: String(lastTurn(ctx, agent)) }
 }
 
 /** Extract a `command` string from a tool call's parsed arguments, else ''. */
diff --git a/packages/hooks/hooks-codex/tests/bridge.spec.ts b/packages/hooks/hooks-codex/tests/bridge.spec.ts
index bdf476e0fe..511ec5e12a 100644
--- a/packages/hooks/hooks-codex/tests/bridge.spec.ts
+++ b/packages/hooks/hooks-codex/tests/bridge.spec.ts
@@ -78,7 +78,7 @@ describe('hooks-codex bridge', () => {
     const ctx = await harness(dir, adapter)
     let ran = false
     ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'no' }] } }))
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'run ls' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -99,7 +99,7 @@ describe('hooks-codex bridge', () => {
 
     const adapter = new MockAdapter([textResponse('first answer'), textResponse('second answer after goal')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
@@ -116,7 +116,7 @@ describe('hooks-codex bridge', () => {
 
     const adapter = new MockAdapter([textResponse('must not run')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(SessionId('cancel-prompt-hook'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('cancel-prompt-hook'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'cancel the hook' }], source: { kind: 'user' } }))
     await waitFor(() => existsSync(marker))
     const pid = Number(readFileSync(pidFile, 'utf8').trim())
@@ -139,7 +139,7 @@ describe('hooks-codex bridge', () => {
 
     const adapter = new MockAdapter([textResponse('fine')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1)
@@ -149,7 +149,7 @@ describe('hooks-codex bridge', () => {
     const dir = configDir() // no hooks.json written
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1)
@@ -164,7 +164,7 @@ describe('hooks-codex bridge', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const warn = vi.fn()
     const ctx = await harness(dir, adapter, (ctx) => { ctx.logger.warn = warn as never })
-    const agent = ctx.agentLoop.create(SessionId('invalid-codex-matcher'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('invalid-codex-matcher'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1)
@@ -191,7 +191,7 @@ describe('hooks-codex bridge', () => {
     const fiber = await ctx.plugin(HooksCodex, { configPath: join(dir, 'hooks.json'), model: 'm' })
     await fiber.dispose()
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1) // not blocked → the listener is gone
@@ -216,7 +216,7 @@ describe('hooks-codex bridge', () => {
     ctx.llm.registerAdapter(['mock'], new MockAdapter([]))
     const warn = vi.fn()
     ctx.logger.warn = warn as never
-    ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) // fires agent/session-start
+    await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) // fires agent/session-start
     await waitFor(() => existsSync(marker))
     const pid = Number(readFileSync(pidFile, 'utf8').trim())
     await fiber.dispose()
diff --git a/packages/hooks/hooks-codex/tests/coverage-cases.ts b/packages/hooks/hooks-codex/tests/coverage-cases.ts
index 04217b1ee3..85ab765f7e 100644
--- a/packages/hooks/hooks-codex/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-codex/tests/coverage-cases.ts
@@ -61,34 +61,27 @@ export type CoverageGroup = 'prompt' | 'post-tool' | 'result-shape' | 'edge-path
 export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGroup[]): void {
   const selected = new Set(typeof groups === 'string' ? [groups] : groups)
   if (selected.has('prompt')) describe('hooks-codex coverage — prompt decision mapping', () => {
-    it('uses the persistence locator for transcript_path and null without one', async () => {
-      async function capture(sessionRoot?: string): Promise<{ payload: { transcript_path: string | null }; expected: string | undefined }> {
-        const d = dir()
-        const cap = join(d, 'payload')
-        const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'capture.sh', `#!/usr/bin/env bash\ncat > "${cap}"\n`) }] }] })
-        const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
-        const ctx = await harness(path, adapter, { ...sessionRoot !== undefined ? { sessionRoot } : {} })
-        ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-        const agent = ctx.agentLoop.create(SessionId('transcript'), { provider: 'mock', model: 'mock' })
-        agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
-        await waitForIdle(ctx, agent)
-        return {
-          payload: JSON.parse(readFileSync(cap, 'utf8')) as { transcript_path: string | null },
-          expected: ctx.get('sessionPersistence')?.locate(agent.session.header)?.path,
-        }
-      }
-
-      const located = await capture(dir())
-      expect(located.payload.transcript_path).toBe(located.expected)
-      expect((await capture()).payload.transcript_path).toBeNull()
-    }, 15_000) // Two real agent/hook subprocess loops need process startup and teardown headroom.
+    it('degrades transcript_path to null even with persistence mounted', async () => {
+      const d = dir()
+      const cap = join(d, 'payload')
+      const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'capture.sh', `#!/usr/bin/env bash\ncat > "${cap}"\n`) }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter, { sessionRoot: dir() })
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = await ctx.agentLoop.create(SessionId('transcript'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      // The persistence seam exposes no artifact paths, so the field stays null
+      // even with a persistence backend mounted.
+      expect((JSON.parse(readFileSync(cap, 'utf8')) as { transcript_path: string | null }).transcript_path).toBeNull()
+    }, 15_000) // The real agent/hook subprocess loop needs process startup and teardown headroom.
 
     it('UserPromptSubmit block (exit 2) closes a blocked turn without a step', async () => {
       const d = dir()
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'b.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
       const adapter = new MockAdapter([textResponse('no')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(0)
       expect(events(agent).filter(e => e.type === 'turn/start' || e.type === 'hook/invoked'
@@ -101,7 +94,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'c.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"ctx-x"}}\'\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('ctx-x')
     })
@@ -116,7 +109,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       ctx.on('agent/pre-step', async () => ({
         kind: 'reject' as const,
       }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(0)
       expect(events(agent).some(e => e.type === 'user/message')).toBe(false)
@@ -140,7 +133,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
           source: { kind: 'plugin' as const, plugin: 'policy' },
         })],
       }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const req = JSON.stringify(adapter.requests[0]!.messages)
       expect(req).toContain('from-bridge')
@@ -162,7 +155,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, value: [{ type: 'text' as const, text: 'rewritten-result' }] }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text === 'rewritten-result')).toBe(true)
@@ -182,7 +175,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
           source: { kind: 'plugin' as const, plugin: 'policy' },
         })],
       }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
 
       const contexts = events(agent).filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
@@ -199,7 +192,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'block' as const, feedback: [{ type: 'text' as const, text: 'downstream-block' }] }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(true)
@@ -212,7 +205,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"start-ctx"}}\'\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => agent.inbox.nextStep.some(message =>
         message.content.some(block => block.type === 'text' && block.text.includes('start-ctx'))))
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
@@ -225,7 +218,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.message.content[0].isError).toBe(true)
@@ -238,7 +231,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('post-ctx')))).toBe(true)
     })
@@ -252,7 +245,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // clean-exit hook allows; commandOf returned ''
     })
@@ -263,7 +256,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.exitCode).toBe(0)
@@ -276,7 +269,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.stderrSummary?.endsWith('…')).toBe(true)
@@ -299,7 +292,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter, { stderrSummaryMaxChars: 40 })
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.stderrSummary).toBe('x'.repeat(40) + '…')
@@ -324,7 +317,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       // Direct apply (schema bypass) → the `model ?? ''` fallback is exercised.
       HooksCodex.apply(ctx, { configPath: join(d, 'hooks.json') })
       ctx.llm.registerAdapter(['mock'], adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('async hook'))
@@ -337,7 +330,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
     })
@@ -351,7 +344,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', `#!/usr/bin/env bash\ntouch "${marker}"\nexit 0\n`) }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => existsSync(marker)) // the clean no-output hook has finished
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user')).toBe(false)
@@ -363,7 +356,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const warn = vi.fn(); ctx.logger.warn = warn as never
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.inject = (() => { throw new Error('inject boom') })
       await waitFor(() => warn.mock.calls.some(c => String(c[0]).includes('SessionStart hook failed')))
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('SessionStart hook failed'))
@@ -378,7 +371,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
     })
@@ -391,7 +384,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // matcher didn't match → no hook ran → tool proceeded
       expect(events(agent).some(e => e.type === 'hook/invoked')).toBe(false)
@@ -407,7 +400,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.decision).toBe('stop') // recorded
@@ -420,7 +413,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.message.content[0].content.some(b => b.type === 'text' && b.text.includes('blocked by PreToolUse hook'))).toBe(true)
@@ -432,7 +425,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.message.content[0].isError).toBe(true)
@@ -449,7 +442,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 7 }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'number' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const payload = JSON.parse(readFileSync(cap, 'utf8')) as { tool_input: { command: string } }
       expect(payload.tool_input.command).toBe('')
@@ -485,7 +478,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.shell.run = (() => Promise.reject(new Error('executor down')))
       ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && 'exitCode' in res.data).toBe(false)
@@ -501,7 +494,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { Stop: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', `#!/usr/bin/env bash\nif [ -e "${marker}" ]; then exit 0; fi\ntouch "${marker}"\nexit 2\n`) }] }] })
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(2) // empty-reason block forced continuation
       expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('blocked by Stop hook')
@@ -514,7 +507,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho "extra guidance from a plain hook"\nexit 0\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('extra guidance from a plain hook')
     })
@@ -528,7 +521,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 'b.sh', `#!/usr/bin/env bash\ntouch "${marker}"\necho "stale"\nexit 2\n`) }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => existsSync(marker)) // the exit-2 hook has finished
       expect(events(agent).some(e => e.type === 'user/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('stale')))).toBe(false)
@@ -542,7 +535,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'e.sh', '#!/usr/bin/env bash\necho "stale"\nexit 1\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(1) // exit 1 is non-blocking → the turn ran
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('stale')
@@ -553,7 +546,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 'ss.sh', '#!/usr/bin/env bash\necho "session preamble"\nexit 0\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => agent.inbox.nextStep.some(message =>
         message.content.some(block => block.type === 'text' && block.text.includes('session preamble'))))
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
@@ -567,7 +560,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'j.sh', '#!/usr/bin/env bash\necho \'{"unrelated":"json"}\'\nexit 0\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('unrelated')
     })
@@ -582,7 +575,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'shell', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineContentToolFixture({ name: 'shell', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       const payload = JSON.parse(readFileSync(cap, 'utf8')) as { tool_name: string; tool_input: { command: string } }
       expect(payload.tool_name).toBe('shell')
@@ -598,7 +591,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineContentToolFixture({ name: 'shell', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(ran).toBe(false) // the matcher fired → the hook denied the tool
       expect(events(agent).some(e => e.type === 'hook/invoked' && e.data.point === 'PreToolUse')).toBe(true)
@@ -610,7 +603,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const warn = vi.fn(); ctx.logger.warn = warn as never
-      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      const agent = await ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('systemMessage'))
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('heads up')
diff --git a/packages/hooks/hooks-codex/tsconfig.json b/packages/hooks/hooks-codex/tsconfig.json
index 7b87f4d871..8d2002823d 100644
--- a/packages/hooks/hooks-codex/tsconfig.json
+++ b/packages/hooks/hooks-codex/tsconfig.json
@@ -29,9 +29,6 @@
     {
       "path": "../../core/session"
     },
-    {
-      "path": "../../session/session-persistence"
-    },
     {
       "path": "../../llm/llm"
     },
diff --git a/packages/llm/llm-retry/tests/loader-composition.spec.ts b/packages/llm/llm-retry/tests/loader-composition.spec.ts
index 1ce91a8b29..5c5a177040 100644
--- a/packages/llm/llm-retry/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-retry/tests/loader-composition.spec.ts
@@ -107,7 +107,7 @@ describe('real Loader composition', () => {
 
     const adapter = new TransientOnceAdapter()
     loaded.llm.registerAdapter(['mock'], adapter)
-    const agent = loaded.agentLoop.create(SessionId('loader-retry'), { provider: 'mock', model: 'mock' })
+    const agent = await loaded.agentLoop.create(SessionId('loader-retry'), { provider: 'mock', model: 'mock' })
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'recover' }], source: { kind: 'user' } }))
     await agent.whenIdle()
 
diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts
index 61c3d2bab5..adabf7df9b 100644
--- a/packages/llm/llm-retry/tests/persistence.spec.ts
+++ b/packages/llm/llm-retry/tests/persistence.spec.ts
@@ -28,6 +28,7 @@ describe('JSONL retry-event persistence', () => {
     const ctx = await backend()
     try {
       const session = ctx.sessions.create(SessionId('retry-jsonl'))
+      const handle = await ctx.sessionPersistence.create(session.header)
       session.append('turn/start', { turn: 1 })
       session.append('step/start', { turn: 1, step: 1 })
       session.append('request/header', {
@@ -52,9 +53,14 @@ describe('JSONL retry-event persistence', () => {
 
       expect(session.deriveMessages()).toEqual([])
       await ctx.sessions.flush(session)
-      const loaded = await ctx.sessionPersistence.load(session.id)
-
-      expect(loaded.events.find(item => item.type === 'llm/retry')).toEqual(event)
+      await handle.close()
+      const reader = await ctx.sessionPersistence.open(session.id, 'read')
+      try {
+        const loaded = await reader.read()
+        expect(loaded.find(item => item.type === 'llm/retry')).toEqual(event)
+      } finally {
+        await reader.close()
+      }
     } finally {
       await ctx.fiber.dispose()
     }
diff --git a/packages/llm/llm-retry/tests/retry.spec.ts b/packages/llm/llm-retry/tests/retry.spec.ts
index 1516ff20a4..3ea3ee5134 100644
--- a/packages/llm/llm-retry/tests/retry.spec.ts
+++ b/packages/llm/llm-retry/tests/retry.spec.ts
@@ -184,7 +184,7 @@ describe('provider-routed retry policy', () => {
     ;({ ctx: context } = await harness(adapter, {
       mock: normalConfig({ retryableCodes: ['SERVER', 'RATE_LIMIT'] }),
     }, undefined, { random: () => 0.5 }))
-    const agent = context.agentLoop.create(SessionId('retry-success'), {
+    const agent = await context.agentLoop.create(SessionId('retry-success'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -235,7 +235,7 @@ describe('provider-routed retry policy', () => {
     // adapters' empty-completion classification end to end (finish-chunk error
     // delivery, not a thrown stream error).
     ;({ ctx: context } = await harness(adapter))
-    const agent = context.agentLoop.create(SessionId('retry-empty-response'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-empty-response'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
@@ -277,7 +277,7 @@ describe('provider-routed retry policy', () => {
         return [{ type: 'text', text: 'unexpected' }]
       },
     }))
-    const agent = context.agentLoop.create(SessionId('retry-partial'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-partial'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
@@ -323,7 +323,7 @@ describe('provider-routed retry policy', () => {
     }) }, undefined, {
       random: () => samples.shift() ?? 0.5,
     }))
-    const agent = context.agentLoop.create(SessionId('retry-exhausted'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-exhausted'), { provider: 'mock', model: 'mock' })
     const first = waitForRetry(context, agent, 1)
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
@@ -354,7 +354,7 @@ describe('provider-routed retry policy', () => {
     ;({ ctx: context } = await harness(adapter, { mock: normalConfig({
       backoff: { initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 1 },
     }) }, undefined, { random: () => 0 }))
-    const agent = context.agentLoop.create(SessionId('retry-zero-delay'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-zero-delay'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
@@ -375,7 +375,7 @@ describe('provider-routed retry policy', () => {
     ;({ ctx: context } = await harness(accepted, { mock: normalConfig({
       backoff: { jitterRatio: 1 },
     }) }))
-    const acceptedAgent = context.agentLoop.create(SessionId('retry-after-accepted'), { provider: 'mock', model: 'mock' })
+    const acceptedAgent = await context.agentLoop.create(SessionId('retry-after-accepted'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, acceptedAgent, 1)
     acceptedAgent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     expect((await scheduled).data.delayMs).toBe(2_000)
@@ -389,7 +389,7 @@ describe('provider-routed retry policy', () => {
       new LlmError('wait too long', 'RATE_LIMIT', { providerRetryAfterMs: 10_001 }),
     ])
     ;({ ctx: context } = await harness(rejected))
-    const rejectedAgent = context.agentLoop.create(SessionId('retry-after-rejected'), { provider: 'mock', model: 'mock' })
+    const rejectedAgent = await context.agentLoop.create(SessionId('retry-after-rejected'), { provider: 'mock', model: 'mock' })
     const rejectedIdle = waitForIdle(context, rejectedAgent)
     rejectedAgent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await rejectedIdle
@@ -408,7 +408,7 @@ describe('provider-routed retry policy', () => {
       maxDelayMs: 4,
       jitterRatio: 0.5,
     }) }, undefined, { random: () => 1 }))
-    const agent = context.agentLoop.create(SessionId('retry-always-over-cap'), {
+    const agent = await context.agentLoop.create(SessionId('retry-always-over-cap'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -427,7 +427,7 @@ describe('provider-routed retry policy', () => {
     vi.useFakeTimers()
     const adapter = new ScriptedAdapter([new LlmError('bad key', 'AUTH')])
     ;({ ctx: context } = await harness(adapter))
-    const agent = context.agentLoop.create(SessionId('retry-auth'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-auth'), { provider: 'mock', model: 'mock' })
     const idle = waitForIdle(context, agent)
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await idle
@@ -441,7 +441,7 @@ describe('provider-routed retry policy', () => {
     const mounted = await harness(adapter, { mock: alwaysConfig() })
     context = mounted.ctx
     mounted.disposeAdapter()
-    const agent = context.agentLoop.create(SessionId('retry-no-serving-policy'), {
+    const agent = await context.agentLoop.create(SessionId('retry-no-serving-policy'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -473,7 +473,7 @@ describe('provider-routed retry policy', () => {
       other: alwaysConfig({ initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 0 }),
     }))
 
-    const normalAgent = context.agentLoop.create(SessionId('retry-provider-normal'), {
+    const normalAgent = await context.agentLoop.create(SessionId('retry-provider-normal'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -482,7 +482,7 @@ describe('provider-routed retry policy', () => {
     await normalIdle
     expect(normalAgent.session.snapshotEvents().some(event => event.type === 'llm/retry')).toBe(false)
 
-    const alwaysAgent = context.agentLoop.create(SessionId('retry-provider-always'), {
+    const alwaysAgent = await context.agentLoop.create(SessionId('retry-provider-always'), {
       provider: 'other',
       model: 'mock',
     })
@@ -515,7 +515,7 @@ describe('provider-routed retry policy', () => {
         provider: 'other',
       }))
     }))
-    const agent = context.agentLoop.create(SessionId('retry-provider-rerouted'), {
+    const agent = await context.agentLoop.create(SessionId('retry-provider-rerouted'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -552,7 +552,7 @@ describe('provider-routed retry policy', () => {
         provider: adapter.requests.length === 0 ? 'mock' : 'other',
       }))
     }))
-    const agent = context.agentLoop.create(SessionId('retry-provider-budgets'), {
+    const agent = await context.agentLoop.create(SessionId('retry-provider-budgets'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -600,7 +600,7 @@ describe('provider-routed retry policy', () => {
         maxDelayMs: 1,
       }) })
       context = mounted.ctx
-      const agent = context.agentLoop.create(SessionId('retry-serving-registration'), {
+      const agent = await context.agentLoop.create(SessionId('retry-serving-registration'), {
         provider: 'mock',
         model: 'mock',
       })
@@ -667,7 +667,7 @@ describe('provider-routed retry policy', () => {
       maxDelayMs: 4,
       jitterRatio: 0.1,
     }) }, undefined, { random: () => 1 }))
-    const agent = context.agentLoop.create(SessionId('retry-always-unbounded'), {
+    const agent = await context.agentLoop.create(SessionId('retry-always-unbounded'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -704,7 +704,7 @@ describe('provider-routed retry policy', () => {
       initialDelayMs: 1,
       maxDelayMs: 1,
     }) }))
-    const agent = context.agentLoop.create(SessionId('retry-always-context-isolation'), {
+    const agent = await context.agentLoop.create(SessionId('retry-always-context-isolation'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -733,7 +733,7 @@ describe('provider-routed retry policy', () => {
     ])
     ;({ ctx: context } = await harness(adapter, { mock: alwaysConfig() }))
     context.on('agent/request-error', async () => ({ kind: 'retry' }))
-    const agent = context.agentLoop.create(SessionId('retry-always-composition'), {
+    const agent = await context.agentLoop.create(SessionId('retry-always-composition'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -760,7 +760,7 @@ describe('provider-routed retry policy', () => {
       maxDelayMs: 1,
     }) }))
     context.on('agent/request-error', failDownstream)
-    const agent = context.agentLoop.create(SessionId('retry-always-downstream-error'), {
+    const agent = await context.agentLoop.create(SessionId('retry-always-downstream-error'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -783,7 +783,7 @@ describe('provider-routed retry policy', () => {
     ])
     const mounted = await harness(adapter, { mock: alwaysConfig() })
     context = mounted.ctx
-    const agent = context.agentLoop.create(SessionId('retry-hmr'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-hmr'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await scheduled
@@ -811,7 +811,7 @@ describe('provider-routed retry policy', () => {
       order.push('downstream')
       return { kind: 'retry' }
     })
-    const agent = context.agentLoop.create(SessionId('retry-delegated-disposal'), {
+    const agent = await context.agentLoop.create(SessionId('retry-delegated-disposal'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -851,7 +851,7 @@ describe('provider-routed retry policy', () => {
       order.push('downstream')
       return decision
     })
-    const agent = context.agentLoop.create(SessionId('retry-delegated-cancel'), {
+    const agent = await context.agentLoop.create(SessionId('retry-delegated-cancel'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -890,7 +890,7 @@ describe('provider-routed retry policy', () => {
       entered.resolve(undefined)
       return downstream.promise
     })
-    const agent = context.agentLoop.create(SessionId('retry-delegated-sync-cancel'), {
+    const agent = await context.agentLoop.create(SessionId('retry-delegated-sync-cancel'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -934,7 +934,7 @@ describe('provider-routed retry policy', () => {
       downstreamCalls += 1
       return next()
     })
-    const agent = context.agentLoop.create(SessionId('retry-captured-disposal'), {
+    const agent = await context.agentLoop.create(SessionId('retry-captured-disposal'), {
       provider: 'mock',
       model: 'mock',
     })
@@ -958,7 +958,7 @@ describe('provider-routed retry policy', () => {
       textResponse('must not run'),
     ])
     ;({ ctx: context } = await harness(adapter, { mock: alwaysConfig() }))
-    const agent = context.agentLoop.create(SessionId('retry-cancel'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-cancel'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await scheduled
@@ -989,7 +989,7 @@ describe('provider-routed retry policy', () => {
         return next()
       })
     }))
-    const agent = context.agentLoop.create(SessionId('retry-pre-cancel'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-pre-cancel'), { provider: 'mock', model: 'mock' })
     const idle = waitForIdle(context, agent)
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
@@ -1010,7 +1010,7 @@ describe('provider-routed retry policy', () => {
       textResponse('must not run'),
     ])
     ;({ ctx: context } = await harness(adapter))
-    const agent = context.agentLoop.create(SessionId('retry-event-cancel'), { provider: 'mock', model: 'mock' })
+    const agent = await context.agentLoop.create(SessionId('retry-event-cancel'), { provider: 'mock', model: 'mock' })
     context.on('session/event', (session, event) => {
       if (session === agent.session && event.type === 'llm/retry') agent.cancel({ kind: 'user' })
     })
diff --git a/packages/llm/llm-retry/tests/transport-recovery.spec.ts b/packages/llm/llm-retry/tests/transport-recovery.spec.ts
index c9b8c7eaca..0d62e3a22c 100644
--- a/packages/llm/llm-retry/tests/transport-recovery.spec.ts
+++ b/packages/llm/llm-retry/tests/transport-recovery.spec.ts
@@ -88,7 +88,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
   it('recovers from a true refused connection after the endpoint starts during backoff', async () => {
     const port = await unusedPort()
     context = await harness(`http://127.0.0.1:${port}`, { initialDelayMs: 100 })
-    const agent = context.agentLoop.create(SessionId('wire-refused'), {
+    const agent = await context.agentLoop.create(SessionId('wire-refused'), {
       provider: 'deepseek-official',
       model: 'mock-model',
     })
@@ -123,7 +123,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
       successText: 'recovered response',
     })
     context = await harness(server.baseURL)
-    const agent = context.agentLoop.create(SessionId(`wire-${behavior}`), {
+    const agent = await context.agentLoop.create(SessionId(`wire-${behavior}`), {
       provider: 'deepseek-official',
       model: 'mock-model',
     })
@@ -152,7 +152,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
       successText: 'recovered from empty',
     })
     context = await harness(server.baseURL)
-    const agent = context.agentLoop.create(SessionId('wire-empty'), {
+    const agent = await context.agentLoop.create(SessionId('wire-empty'), {
       provider: 'deepseek-official',
       model: 'mock-model',
     })
@@ -180,7 +180,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
       chunkSize: 100,
     })
     context = await harness(server.baseURL)
-    const agent = context.agentLoop.create(SessionId('wire-partial-eof'), {
+    const agent = await context.agentLoop.create(SessionId('wire-partial-eof'), {
       provider: 'deepseek-official',
       model: 'mock-model',
     })
@@ -207,7 +207,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
     // This crosses the real HTTP idle timer, so leave scheduler slack between
     // the stalled attempt and the mock server's immediate successful response.
     context = await harness(server.baseURL, { streamIdleTimeoutMs: 1_000 })
-    const agent = context.agentLoop.create(SessionId('wire-stall'), {
+    const agent = await context.agentLoop.create(SessionId('wire-stall'), {
       provider: 'deepseek-official',
       model: 'mock-model',
     })
@@ -225,7 +225,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
       apiKey: 'mock-key',
     })
     context = await harness(server.baseURL)
-    const agent = context.agentLoop.create(SessionId('wire-exhausted'), {
+    const agent = await context.agentLoop.create(SessionId('wire-exhausted'), {
       provider: 'deepseek-official',
       model: 'mock-model',
     })
diff --git a/packages/plan/plan-mode/tests/integration.spec.ts b/packages/plan/plan-mode/tests/integration.spec.ts
index 0cbb6649d7..5e4240e05b 100644
--- a/packages/plan/plan-mode/tests/integration.spec.ts
+++ b/packages/plan/plan-mode/tests/integration.spec.ts
@@ -79,7 +79,7 @@ describe('plan mode through the agent loop', () => {
       textResponse('Noted in the plan.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('it-plan-seed'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('it-plan-seed'), { provider: 'mock', model: 'mock' })
     // Selected while idle: the mode commits immediately, before the first assembly.
     ctx.planMode.set(agent, true)
 
@@ -109,7 +109,7 @@ describe('plan mode through the agent loop', () => {
       textResponse('Second turn, plan mode.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('it-plan-flip'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('it-plan-flip'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
@@ -147,7 +147,7 @@ describe('plan mode through the agent loop', () => {
       textResponse('Entered plan mode on the next step.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('it-plan-retry-flip'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('it-plan-retry-flip'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/request-error', async ({ agent: subject }, next) => {
       if (subject !== agent) return next()
       ctx.planMode.set(agent, true)
diff --git a/packages/schedule/schedule/tests/jsonl-restart.spec.ts b/packages/schedule/schedule/tests/jsonl-restart.spec.ts
index ea67d764c1..742ffd2c35 100644
--- a/packages/schedule/schedule/tests/jsonl-restart.spec.ts
+++ b/packages/schedule/schedule/tests/jsonl-restart.spec.ts
@@ -82,6 +82,16 @@ async function settleCurrentTasks(): Promise<void> {
   await new Promise<void>(resolve => setImmediate(resolve))
 }
 
+/** Read one stored session's header and full event log through a read handle. */
+async function readStored(ctx: Context, id: SessionId) {
+  const handle = await ctx.sessionPersistence.open(id, 'read')
+  try {
+    return { header: handle.header, inheritedEventCount: handle.inheritedEventCount, events: await handle.read() }
+  } finally {
+    await handle.close()
+  }
+}
+
 describe('Schedule production JSONL restart', () => {
   it('resumes one overdue reminder exactly once across fresh runtime mounts', async () => {
     const root = await mkdtemp(join(tmpdir(), 'dsh-schedule-jsonl-'))
@@ -94,7 +104,9 @@ describe('Schedule production JSONL restart', () => {
       ScheduleId('schedule-1'), 'restart reminder', 1, Date.now() - 60_000,
     )
     pending.append('schedule/change', { version: 1, operation: 'create', schedule: pendingRecord })
-    await expect(first.sessions.flush(pending)).resolves.toBe(true)
+    const seed = await first.sessionPersistence.create(pending.header)
+    await seed.append(pending.snapshotEvents())
+    await seed.close()
     await disposeContext(first)
 
     const dispatchingAdapter = new RecordingAdapter()
@@ -107,7 +119,7 @@ describe('Schedule production JSONL restart', () => {
     await dispatched
     await handle.agent.whenIdle()
     await expect(restarted.sessions.flush(handle.agent.session)).resolves.toBe(true)
-    const dispatchedStored = await restarted.sessionPersistence.inspect(sessionId)
+    const dispatchedStored = await readStored(restarted, sessionId)
     expect(foldScheduleEvents(dispatchedStored.events, dispatchedStored.inheritedEventCount).active)
       .toEqual([])
     const dispatches = dispatchedStored.events.filter(event =>
@@ -131,7 +143,7 @@ describe('Schedule production JSONL restart', () => {
     expect(replayAdapter.requests).toEqual([])
     expect(replayHandle.agent.session.snapshotEvents().filter(event =>
       event.type === 'schedule/change' && event.data.operation === 'dispatch')).toHaveLength(1)
-    const replayedStored = await replayed.sessionPersistence.inspect(sessionId)
+    const replayedStored = await readStored(replayed, sessionId)
     expect(replayedStored.events.filter(event =>
       event.type === 'schedule/change' && event.data.operation === 'dispatch')).toHaveLength(1)
     await replayHandle.dispose()
diff --git a/packages/schedule/schedule/tests/plugin.spec.ts b/packages/schedule/schedule/tests/plugin.spec.ts
index 09231bd792..5a8f5712e5 100644
--- a/packages/schedule/schedule/tests/plugin.spec.ts
+++ b/packages/schedule/schedule/tests/plugin.spec.ts
@@ -1,17 +1,75 @@
 import { describe, expect, it } from 'vitest'
-import { Context, Service } from '@deepseek-ai/cordis'
+import { Context } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import { ToolCallId } from '@deepseek-ai/dsh-llm'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionLogOffset, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import {
+  SessionPersistence,
+  SessionPersistenceNotFoundError,
+  SessionPersistenceRevision,
+} from '@deepseek-ai/dsh-session-persistence'
+import type { SessionAccess, SessionHandle, SessionPersistenceSnapshot } from '@deepseek-ai/dsh-session-persistence'
 import * as toolSchedule from '../src/index.ts'
 
-class PersistenceProbe extends Service {
-  constructor(ctx: Context) {
-    super(ctx, 'sessionPersistence')
+interface StoredProbeSession {
+  readonly header: SessionHeader
+  readonly events: SessionEvent[]
+}
+
+/** In-memory handle-based persistence, just enough for agent-loop's write path. */
+class PersistenceProbe extends SessionPersistence {
+  private readonly stored = new Map<string, StoredProbeSession>()
+
+  override async create(header: SessionHeader): Promise<SessionHandle> {
+    const entry: StoredProbeSession = { header, events: [] }
+    this.stored.set(header.id, entry)
+    return this.handle(entry, 'write')
+  }
+
+  // Appends are durable on resolution here; nothing buffers, so the service-wide flush is a no-op.
+  override async flush(): Promise<void> {}
+
+  override async open(id: SessionId, access: SessionAccess): Promise<SessionHandle> {
+    const entry = this.stored.get(id)
+    if (entry === undefined) throw new SessionPersistenceNotFoundError(id)
+    return this.handle(entry, access)
+  }
+
+  override async stat(id: SessionId): Promise<SessionPersistenceSnapshot | undefined> {
+    const entry = this.stored.get(id)
+    return entry === undefined ? undefined : this.snapshot(entry)
+  }
+
+  override async list(): Promise<SessionPersistenceSnapshot[]> {
+    return [...this.stored.values()].map(entry => this.snapshot(entry))
+  }
+
+  private snapshot(entry: StoredProbeSession): SessionPersistenceSnapshot {
+    return {
+      header: entry.header,
+      revision: SessionPersistenceRevision(`probe-${entry.header.id}-${entry.events.length}`),
+      eventCount: entry.events.length,
+    }
+  }
+
+  private handle(entry: StoredProbeSession, access: SessionAccess): SessionHandle {
+    return {
+      id: entry.header.id,
+      header: entry.header,
+      inheritedEventCount: SessionLogOffset(0),
+      access,
+      read: async (offset = 0, length = Number.MAX_SAFE_INTEGER) =>
+        entry.events.slice(offset, offset + length),
+      append: async (events) => { entry.events.push(...events) },
+      flush: async () => {},
+      close: async () => {},
+      [Symbol.asyncDispose]: async () => {},
+    }
   }
 }
 
diff --git a/packages/session-query/session-log-export/README.i18n.yaml b/packages/session-query/session-log-export/README.i18n.yaml
index 2fcd2c63d0..e3c17174b7 100644
--- a/packages/session-query/session-log-export/README.i18n.yaml
+++ b/packages/session-query/session-log-export/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/session-query/session-log-export/README.md
-README.md: a096cea71b2e0bed4882a6e8d23c8f35dc3d0fb7
-README.zh.md: 0c2da35ae0be9420cfd6ff076dd038c3a8edf2cb
+README.md: f7cfa5c755c0f3e4c68bd20de712ed00bdf97ff4
+README.zh.md: 244df44b339a75d4a6d1e4a2fd4c41a692936f66
diff --git a/packages/session-query/session-log-export/README.md b/packages/session-query/session-log-export/README.md
index a096cea71b..f7cfa5c755 100644
--- a/packages/session-query/session-log-export/README.md
+++ b/packages/session-query/session-log-export/README.md
@@ -29,7 +29,7 @@ Use this package when the Web bundle should let users export a session log. It r
 
 ### When to choose it
 
-Choose it for a Web deployment that needs user-facing session export with a visible download dialog. Avoid it when a programmatic or Host-side export is needed: this package produces a browser download, not a Host path write, and it requires the shipped JSONL provider's per-Session raw artifact in plaintext or zstd form.
+Choose it for a Web deployment that needs user-facing session export with a visible download dialog. Avoid it when a programmatic or Host-side export is needed: this package produces a browser download, not a Host path write. The logs are serialized from persistence read handles, so any mounted backend is supported.
 
 ### Composition
 
@@ -79,7 +79,7 @@ The package has two halves. The Host half ([`src/index.ts`](src/index.ts)) regis
 
 Both entry paths issue a `HEAD` preflight to `GET /api/session.export?...`, then hand the GET URL to the browser download manager without buffering the ZIP in JavaScript. One controller owns one in-flight download per session, collapses concurrent gestures into that operation, and cancels the preflight on plugin disposal. Modal state lives in a snapshot store keyed by session, so the button and the command share one dialog per session.
 
-The Host route is a feature-owned exact Fetch contribution. Connection applies its Host/Origin and browser-session checks and bridges the streaming `Response`; this package owns query validation, live-session flushes, raw artifact and attachment reads, ZIP generation, and HTTP status semantics.
+The Host route is a feature-owned exact Fetch contribution. Connection applies its Host/Origin and browser-session checks and bridges the streaming `Response`; this package owns query validation, live-session flushes, handle-based log reads and attachment reads, ZIP generation, and HTTP status semantics.
 
 </details>
 
@@ -121,7 +121,6 @@ None. The log-only command lifecycle and browser download do not change the deri
 
 These limits define when this package is a poor fit or needs special operational care. They are current package constraints, not a task backlog.
 
-- **Requires a per-Session raw artifact** — the download endpoint reads the shipped JSONL provider's plaintext or zstd artifact; an out-of-tree provider without a raw artifact cannot serve this route.
 - **Browser download, not a Host-path writer** — the browser chooses the local destination; no Host path or native folder action is returned.
 - **Preflight reports only pre-stream failures** — a descendant or attachment failure after the browser accepts the GET is reported by the browser download manager, not by the dialog.
 
diff --git a/packages/session-query/session-log-export/README.zh.md b/packages/session-query/session-log-export/README.zh.md
index 0c2da35ae0..244df44b33 100644
--- a/packages/session-query/session-log-export/README.zh.md
+++ b/packages/session-query/session-log-export/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 何时选择
 
-为需要带可见下载弹窗的用户级会话导出的 Web 部署选择它。需要程序化或 Host 侧导出时避免使用：本包产生的是浏览器下载，而非 Host 路径写入，并且它要求随产品交付的 JSONL provider 提供逐 Session 的明文或 zstd 原始产物。
+为需要带可见下载弹窗的用户级会话导出的 Web 部署选择它。需要程序化或 Host 侧导出时避免使用：本包产生的是浏览器下载，而非 Host 路径写入。日志从持久化读句柄序列化而来，因此任何已挂载后端都受支持。
 
 ### 组合
 
@@ -79,7 +79,7 @@ Web bundle 将本包与 Connection、`dsh-commands`、`dsh-client-ui-commands` 
 
 两条入口都会对 `GET /api/session.export?...` 发出 `HEAD` 预检，然后把 GET URL 交给浏览器下载管理器，JavaScript 不缓冲 ZIP。一个控制器按会话持有一项进行中的下载，把并发操作折叠进该任务，并在插件释放时取消预检。弹窗状态存放在按会话键控的快照存储中，因此按钮与命令按会话共享一个弹窗。
 
-Host 路由是业务拥有的精确 Fetch contribution。Connection 应用 Host/Origin 与浏览器会话检查并桥接流式 `Response`；本包拥有查询校验、活动会话 flush、原始产物与附件读取、ZIP 生成和 HTTP 状态语义。
+Host 路由是业务拥有的精确 Fetch contribution。Connection 应用 Host/Origin 与浏览器会话检查并桥接流式 `Response`；本包拥有查询校验、活动会话 flush、基于句柄的日志读取与附件读取、ZIP 生成和 HTTP 状态语义。
 
 </details>
 
@@ -121,7 +121,6 @@ Host 路由是业务拥有的精确 Fetch contribution。Connection 应用 Host/
 
 这些限制说明本包何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。
 
-- **要求逐 Session 原始产物**——下载端点读取随产品交付的 JSONL provider 所提供的明文或 zstd 产物；没有原始产物的仓库外 provider 无法服务该 route。
 - **浏览器下载，而非 Host 路径写入**——目标位置由浏览器选择；不会返回 Host 路径或原生文件夹操作。
 - **预检只报告流式传输前的失败**——浏览器接受 GET 后发生的子会话或附件读取失败由浏览器下载管理器报告，不通过弹窗报告。
 
diff --git a/packages/session-query/session-log-export/package.json b/packages/session-query/session-log-export/package.json
index 9fd76fcf84..ec306c1b5b 100644
--- a/packages/session-query/session-log-export/package.json
+++ b/packages/session-query/session-log-export/package.json
@@ -41,7 +41,8 @@
     "@deepseek-ai/dsh-brand": "workspace:^"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "workspace:^"
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "workspace:^",
@@ -53,16 +54,16 @@
     "@deepseek-ai/dsh-client-store": "workspace:^",
     "@deepseek-ai/dsh-client-ui-commands": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
     "@deepseek-ai/dsh-client-ui-session": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-query": "workspace:^",
     "@types/react": "~18.3.1",
-    "react": "^18.2.0",
-    "@deepseek-ai/dsh-session": "workspace:^"
+    "react": "^18.2.0"
   },
   "dsh": {
     "client": {
diff --git a/packages/session-query/session-log-export/src/archive.ts b/packages/session-query/session-log-export/src/archive.ts
index 2f7d1fbd11..b13a774cee 100644
--- a/packages/session-query/session-log-export/src/archive.ts
+++ b/packages/session-query/session-log-export/src/archive.ts
@@ -1,16 +1,18 @@
 /**
  * Host-side session-log download: streams one ZIP archive whose files are the
- * sessions' stored artifact text verbatim plus every referenced media object.
- * The root artifact sits under its original base name (`session.jsonl`); each
- * subagent descendant under `subagents/<id>/<filename>`; each image referenced
- * by any included log under `media/<attachmentId>.<ext>` (content-addressed,
- * so one archive never duplicates a shared image). No manifest is written —
- * every file is byte-identical to the backend's durable artifact or attachment
- * store and self-describing through its own header line or media type. Before
- * each live session's artifact read, the SessionStore flush barrier makes the
- * current in-memory log durable; cold sessions need no barrier. Request abort
- * and response-consumer cancellation share one producer signal and terminate
- * the active compressor.
+ * sessions' logical session logs plus every referenced media object. Each log
+ * is read through a persistence read handle and serialized here as canonical
+ * JSONL — one header line, then one line per validated event — so every
+ * backend (JSONL, SQLite, future) exports identically. The root log sits at
+ * `session.jsonl`; each subagent descendant under
+ * `subagents/<id>/session.jsonl`; each image referenced by any included log
+ * under `media/<attachmentId>.<ext>` (content-addressed, so one archive never
+ * duplicates a shared image). No manifest is written — every file is
+ * self-describing through its own header line or media type. Before each live
+ * session's log read, the SessionStore flush barrier makes the current
+ * in-memory log durable; cold sessions need no barrier. Request abort and
+ * response-consumer cancellation share one producer signal and terminate the
+ * active compressor.
  * Compression runs on the host with fflate's streaming Zip API, so the archive
  * bytes are produced incrementally and the host never holds the whole archive
  * in one buffer; production waits for consumer pull whenever the response queue
@@ -23,8 +25,9 @@ import { Zip, ZipDeflate } from 'fflate'
 import type { Context } from '@deepseek-ai/cordis'
 import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type { SessionLineageNode, SessionQueryEngine } from '@deepseek-ai/dsh-session-query'
-import type { SessionId, SessionStore } from '@deepseek-ai/dsh-session'
-import type { SessionPersistence, SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionEvent, SessionHeader, SessionId, SessionStore } from '@deepseek-ai/dsh-session'
+import type { SessionHandle, SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+import { SessionPersistenceNotFoundError } from '@deepseek-ai/dsh-session-persistence'
 
 /** Valid fflate DEFLATE levels accepted by session-log export. */
 export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
@@ -84,11 +87,86 @@ export async function flushLiveSessionLog(
   signal?.throwIfAborted()
 }
 
-/** One exported file: a stored artifact text or one referenced media object. */
+/** One exported file: a serialized session log or one referenced media object. */
 export type SessionLogZipEntry =
   | { readonly path: string; readonly content: string }
   | { readonly path: string; readonly data: Uint8Array }
 
+/** The zip base filename for every exported session log. */
+export const SESSION_LOG_FILENAME = 'session.jsonl'
+
+/**
+ * Serialize one session's logical log as canonical JSONL text: the header
+ * line, then one line per event, with a trailing newline.
+ * @param header - the session's immutable header.
+ * @param inheritedEventCount - the exact fork-inherited prefix length stored
+ *   beside the header (`0` when `header.isSeeded` is false).
+ * @param events - the validated committed events in seq order.
+ * @returns the JSONL text.
+ */
+export function serializeSessionLog(
+  header: SessionHeader,
+  inheritedEventCount: number,
+  events: readonly SessionEvent[],
+): string {
+  // Match the JSONL backend's canonical header line: lineage is the physical
+  // `seedLength`, and `delegationDepth` is required-on-read there, so an
+  // omitted top-level depth serializes as 0 and the exported log parses as a
+  // valid log.
+  /* jscpd:ignore-start -- deliberately mirrors the JSONL backend's
+     `toHeaderLine`: the exported text is the canonical v0 physical header
+     line, and this backend-agnostic package must not depend on one backend
+     implementation. */
+  const lines = [JSON.stringify({
+    type: 'session',
+    version: header.version,
+    id: header.id,
+    createdAt: header.createdAt,
+    ...header.cwd !== undefined ? { cwd: header.cwd } : {},
+    ...header.parentSession !== undefined ? { parentSession: header.parentSession } : {},
+    ...header.isSeeded ? { seedLength: inheritedEventCount } : {},
+    ...header.origin !== undefined ? { origin: header.origin } : {},
+    delegationDepth: header.delegationDepth ?? 0,
+    ...header.agentPreset !== undefined ? { agentPreset: header.agentPreset } : {},
+  })]
+  /* jscpd:ignore-end */
+  for (const event of events) lines.push(JSON.stringify(event))
+  return `${lines.join('\n')}\n`
+}
+
+/**
+ * Read one session's complete logical log through a read handle and serialize
+ * it. The read observes the committed log only — persistence never returns a
+ * torn tail — and a handle read after a resolved flush observes at least the
+ * flushed prefix.
+ * @param persistence - the mounted persistence backend.
+ * @param id - the session to read.
+ * @param signal - optional cancellation forwarded to the open and read.
+ * @returns the serialized JSONL text, or `undefined` when the session does not exist.
+ */
+export async function readSessionLogText(
+  persistence: SessionPersistence,
+  id: SessionId,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  const options = signal === undefined ? {} : { signal }
+  let handle: SessionHandle
+  try {
+    handle = await persistence.open(id, 'read', options)
+  } catch (error) {
+    // Absence is `open`'s decision; every other failure (corruption,
+    // unsupported format, I/O, cancellation) stays fail-loud.
+    if (error instanceof SessionPersistenceNotFoundError) return undefined
+    throw error
+  }
+  try {
+    const events = await handle.read(0, undefined, options)
+    return serializeSessionLog(handle.header, Number(handle.inheritedEventCount), events)
+  } finally {
+    await handle.close()
+  }
+}
+
 /** Zip extension for each accepted raster media type. */
 const MEDIA_TYPE_EXTENSIONS: Record<ImageAttachmentRef['mediaType'], string> = {
   'image/png': 'png',
@@ -201,16 +279,16 @@ export function sessionLogZipFilename(sessionId: string): string {
 }
 
 /**
- * Yield the export entries in zip order: the preloaded root artifact first,
- * then every subagent descendant in lineage order (each flushed when live,
- * read from the persistence backend right before it is yielded, and dropped
+ * Yield the export entries in zip order: the preloaded root log first, then
+ * every subagent descendant in lineage order (each flushed when live, read
+ * through a persistence read handle right before it is yielded, and dropped
  * after the consumer moves on), then every distinct media object referenced by any of
  * the included logs (read and verified from the attachment store, one archive
- * entry per attachment id). The host holds at most one descendant's artifact
- * text and one media object at a time beyond the root.
+ * entry per attachment id). The host holds at most one descendant's log text
+ * and one media object at a time beyond the root.
  * @param deps - the mounted export services (the caller answered 500 before this runs).
- * @param root - the already-read root artifact (read by the caller so the
- * missing-session path can answer cleanly before streaming starts).
+ * @param rootContent - the already-serialized root log (read by the caller so
+ * the missing-session path can answer cleanly before streaming starts).
  * @param sessionId - the root session id.
  * @param includeDescendants - whether to include every subagent descendant.
  * @param signal - optional cancellation forwarded to lineage, persistence, and attachment reads.
@@ -218,7 +296,7 @@ export function sessionLogZipFilename(sessionId: string): string {
  */
 export async function* sessionLogZipEntries(
   deps: SessionLogExportReady,
-  root: SessionRawArtifact,
+  rootContent: string,
   sessionId: SessionId,
   includeDescendants: boolean,
   signal?: AbortSignal,
@@ -227,8 +305,8 @@ export async function* sessionLogZipEntries(
   const rememberMedia = (content: string): void => {
     for (const [id, ref] of imageRefsInArtifact(content)) media.set(id, ref)
   }
-  rememberMedia(root.content)
-  yield { path: root.filename, content: root.content }
+  rememberMedia(rootContent)
+  yield { path: SESSION_LOG_FILENAME, content: rootContent }
   if (includeDescendants) {
     const seen = new Set<SessionId>([sessionId])
     const collect = async function* (
@@ -240,15 +318,15 @@ export async function* sessionLogZipEntries(
         if (seen.has(id)) continue
         seen.add(id)
         await flushLiveSessionLog(deps, id, signal)
-        const raw = await deps.sessionPersistence.readRaw(id, signal)
+        const content = await readSessionLogText(deps.sessionPersistence, id, signal)
         signal?.throwIfAborted()
-        if (raw === undefined) {
-          throw new Error(`subagent "${id}" has no stored log artifact`)
+        if (content === undefined) {
+          throw new Error(`subagent "${id}" has no stored log`)
         }
-        rememberMedia(raw.content)
+        rememberMedia(content)
         yield {
-          path: `subagents/${safeSessionIdSegment(id)}/${raw.filename}`,
-          content: raw.content,
+          path: `subagents/${safeSessionIdSegment(id)}/${SESSION_LOG_FILENAME}`,
+          content,
         }
         yield* collect(node.descendants)
       }
@@ -371,14 +449,14 @@ async function pushArtifactChunks(
 }
 
 /**
- * Stream one session-log ZIP as a WHATWG ReadableStream. The root artifact is
- * read and validated by the caller before this is called (missing root or
+ * Stream one session-log ZIP as a WHATWG ReadableStream. The root log is read
+ * and serialized by the caller before this is called (a missing root or
  * missing services answer cleanly before any byte is produced); each entry is
  * then encoded and deflated in bounded chunks as it is produced, so the
  * archive bytes arrive incrementally. A descendant that fails to read errors
  * the stream (fail-loud, never silent under-export).
  * @param deps - the mounted export services (the caller answered 500 before this runs).
- * @param root - the already-read root artifact (first zip entry).
+ * @param rootContent - the already-serialized root log (first zip entry).
  * @param sessionId - the root session id.
  * @param includeDescendants - whether to include every subagent descendant.
  * @param compressionLevel - validated fflate DEFLATE level for every ZIP entry.
@@ -387,7 +465,7 @@ async function pushArtifactChunks(
  */
 export function streamSessionLogZip(
   deps: SessionLogExportReady,
-  root: SessionRawArtifact,
+  rootContent: string,
   sessionId: SessionId,
   includeDescendants: boolean,
   compressionLevel: SessionLogCompressionLevel,
@@ -422,7 +500,7 @@ export function streamSessionLogZip(
       zip = archive
       void (async () => {
         try {
-          for await (const entry of sessionLogZipEntries(deps, root, sessionId, includeDescendants, producerSignal)) {
+          for await (const entry of sessionLogZipEntries(deps, rootContent, sessionId, includeDescendants, producerSignal)) {
             const deflate = new ZipDeflate(entry.path, { level: compressionLevel })
             archive.add(deflate)
             if ('content' in entry) {
diff --git a/packages/session-query/session-log-export/src/index.ts b/packages/session-query/session-log-export/src/index.ts
index 88c4cc6ccb..0ec33bc2e5 100644
--- a/packages/session-query/session-log-export/src/index.ts
+++ b/packages/session-query/session-log-export/src/index.ts
@@ -6,10 +6,10 @@ import { brandString } from '@deepseek-ai/dsh-brand'
 import type {} from '@deepseek-ai/dsh-attachment'
 import type { CommandResult } from '@deepseek-ai/dsh-commands'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
 import {
   DEFAULT_SESSION_LOG_COMPRESSION_LEVEL,
   flushLiveSessionLog,
+  readSessionLogText,
   sessionLogExportDeps,
   sessionLogZipFilename,
   streamSessionLogZip,
@@ -20,6 +20,9 @@ import {
 export {
   DEFAULT_SESSION_LOG_COMPRESSION_LEVEL,
   flushLiveSessionLog,
+  readSessionLogText,
+  serializeSessionLog,
+  SESSION_LOG_FILENAME,
   sessionLogExportDeps,
   sessionLogZipEntries,
   sessionLogZipFilename,
@@ -121,32 +124,31 @@ async function sessionLogExportResponse(
       { status: 500 },
     )
   }
-  if (!deps.sessionPersistence.supportsRawArtifacts) {
-    return new Response(
-      'session log export is unavailable: the persistence backend does not expose per-session raw artifacts',
-      { status: 501 },
-    )
-  }
   const ready: SessionLogExportReady = {
     sessionQuery: deps.sessionQuery,
     sessionPersistence: deps.sessionPersistence,
     attachments: deps.attachments,
     sessions: deps.sessions,
   }
-  let root: SessionRawArtifact | undefined
+  let rootContent: string | undefined
   try {
     await flushLiveSessionLog(deps, sessionId, request.signal)
-    root = await deps.sessionPersistence.readRaw(sessionId, request.signal)
+    rootContent = await readSessionLogText(deps.sessionPersistence, sessionId, request.signal)
     request.signal.throwIfAborted()
   } catch {
     request.signal.throwIfAborted()
-    return new Response('session log export failed to prepare the stored artifact', { status: 500 })
+    // Root preparation failure (flush, open, or read): answer 500 without
+    // echoing the error, which may carry absolute host paths into the
+    // browser error bar.
+    return new Response('session log export failed to read the stored log', { status: 500 })
+  }
+  if (rootContent === undefined) {
+    return new Response('session not found', { status: 404 })
   }
-  if (root === undefined) return new Response('session not found', { status: 404 })
   const response = new Response(
     streamSessionLogZip(
       ready,
-      root,
+      rootContent,
       sessionId,
       descendantsValue === 'true',
       compressionLevel,
diff --git a/packages/session-query/session-log-export/tests/archive.host.spec.ts b/packages/session-query/session-log-export/tests/archive.host.spec.ts
index 66ebe197c0..6ab02812e2 100644
--- a/packages/session-query/session-log-export/tests/archive.host.spec.ts
+++ b/packages/session-query/session-log-export/tests/archive.host.spec.ts
@@ -1,19 +1,21 @@
 /**
  * session.export host path: the GET download endpoint streams a ZIP whose
- * files are the stored artifacts verbatim (root + optional descendants), and
- * the degenerate compositions fail loudly (missing services → 500, missing
- * root → 404, missing descendant → errored stream).
+ * files are the sessions' logical logs serialized as canonical JSONL (root +
+ * optional descendants) read through persistence read handles, and the
+ * degenerate compositions fail loudly (missing services → 500, missing root →
+ * 404, missing descendant → errored stream).
  */
 
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import { randomBytes } from 'node:crypto'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { unzipSync, strFromU8 } from 'fflate'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
-import { SessionLogOffset } from '@deepseek-ai/dsh-session'
-import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionLineageNode } from '@deepseek-ai/dsh-session-query'
-import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
+import { SessionPersistenceNotFoundError } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionAccess, SessionHandle } from '@deepseek-ai/dsh-session-persistence'
 import { HostConnectionService } from '@deepseek-ai/dsh-client-connection'
 import type { BrowserAuth } from '@deepseek-ai/dsh-client-connection/src/browser-auth.ts'
 import * as SessionLogExport from '../src/index.ts'
@@ -25,20 +27,28 @@ function header(id: string, parentSession?: SessionId): SessionHeader {
     version: 0,
     id: sid(id),
     createdAt: 1000,
-    cwd: '/proj',
     isSeeded: false,
+    cwd: '/proj',
     ...parentSession === undefined ? {} : { parentSession },
     delegationDepth: parentSession === undefined ? 0 : 1,
   }
 }
 
-function artifact(id: string, parentSession?: SessionId, content?: string): SessionRawArtifact {
-  return {
-    meta: header(id, parentSession),
-    inheritedEventCount: SessionLogOffset(0),
-    filename: 'session.jsonl',
-    content: content ?? `{"type":"session","version":0,"id":"${id}","createdAt":1000}\n{"type":"turn/start","seq":0,"time":2000,"data":{"turn":1}}\n`,
-  }
+/** One stored logical session log served by the fake persistence backend. */
+interface StoredLog {
+  readonly header: SessionHeader
+  readonly events: readonly SessionEvent[]
+}
+
+const turnStart: SessionEvent = { type: 'turn/start', seq: SessionSeq(0), time: 2000, data: { turn: 1 } }
+
+function log(id: string, parentSession?: SessionId, events: readonly SessionEvent[] = [turnStart]): StoredLog {
+  return { header: header(id, parentSession), events }
+}
+
+/** The expected zip text for one stored log: the canonical JSONL serialization. */
+function logText(stored: StoredLog): string {
+  return SessionLogExport.serializeSessionLog(stored.header, 0, stored.events)
 }
 
 function node(id: string, ...descendants: SessionLineageNode[]): SessionLineageNode {
@@ -53,23 +63,38 @@ function storedImage(id: string, mediaType: ImageAttachmentRef['mediaType'] = 'i
   }
 }
 
-/** A user/message event line carrying one image reference. */
-function imageEventLine(id: string, mediaType: ImageAttachmentRef['mediaType'] = 'image/png'): string {
-  return `{"type":"user/message","seq":1,"time":1000,"data":{"content":[{"type":"image","attachment":{"attachmentId":"${id}","mediaType":"${mediaType}","bytes":4,"width":2,"height":2}}]}}`
+/** A user/message event carrying one image reference. */
+function imageEvent(id: string, mediaType: ImageAttachmentRef['mediaType'] = 'image/png'): SessionEvent {
+  return {
+    type: 'user/message', seq: SessionSeq(1), time: 1000,
+    data: { content: [{ type: 'image', attachment: { attachmentId: id, mediaType, bytes: 4, width: 2, height: 2 } }] },
+  } as unknown as SessionEvent
+}
+
+/** A read handle over one stored log; only what readSessionLogText touches. */
+function readHandle(stored: StoredLog): SessionHandle {
+  return {
+    id: stored.header.id,
+    header: stored.header,
+    access: 'read',
+    inheritedEventCount: 0,
+    read: async () => stored.events,
+    close: async () => {},
+  } as unknown as SessionHandle
 }
 
 async function buildApi(
-  artifacts: Record<string, SessionRawArtifact>,
+  logs: Record<string, StoredLog>,
   descendants: SessionLineageNode[] = [],
   services: {
     query?: boolean
-    persistence?: boolean | 'throw' | 'unsupported'
+    persistence?: boolean | 'throw'
     attachments?: boolean | ((ref: ImageAttachmentRef, signal?: AbortSignal) => Promise<ReturnType<typeof storedImage>>)
     sessions?: {
       get(id: SessionId): { readonly id: SessionId } | undefined
       flush(session: { readonly id: SessionId }): Promise<boolean>
     }
-    readRaw?: (id: SessionId, signal?: AbortSignal) => Promise<SessionRawArtifact | undefined>
+    open?: (id: SessionId, access: SessionAccess, options?: { signal?: AbortSignal }) => Promise<SessionHandle>
     traceSession?: (id: SessionId, signal?: AbortSignal) => Promise<{
       target: { header: SessionHeader; live: boolean; persisted: boolean }
       ancestors: readonly SessionLineageNode[]
@@ -97,10 +122,17 @@ async function buildApi(
   }
   if (persistence) {
     ctx.provide('sessionPersistence', {
-      supportsRawArtifacts: persistence !== 'unsupported',
-      readRaw: services.readRaw ?? (async (id: SessionId) => {
+      stat: async (id: SessionId) => {
+        // A custom `open` owns the scenario: absence must reach it, not stop here.
+        if (services.open !== undefined || persistence === 'throw') return { header: header(String(id)) }
+        const stored = logs[id]
+        return stored === undefined ? undefined : { header: stored.header }
+      },
+      open: services.open ?? (async (id: SessionId) => {
         if (persistence === 'throw') throw new Error('/host/private/session.jsonl')
-        return artifacts[id]
+        const stored = logs[id]
+        if (stored === undefined) throw new SessionPersistenceNotFoundError(id)
+        return readHandle(stored)
       }),
     } as never)
   }
@@ -148,6 +180,24 @@ async function responseBytes(response: Response): Promise<Uint8Array> {
   return new Uint8Array(await response.arrayBuffer())
 }
 
+/** Minimal ready services for the direct streamSessionLogZip chunking tests. */
+function directReady(): SessionLogExport.SessionLogExportReady {
+  return {
+    sessionQuery: { traceSession: async () => { throw new Error('unused') } } as never,
+    sessionPersistence: { open: async () => { throw new Error('unused') } } as never,
+    attachments: { readImage: async () => { throw new Error('no media') } } as never,
+    sessions: undefined,
+  }
+}
+
+/** Consume one directly built zip stream into its unpacked files. */
+async function directZipFiles(rootContent: string): Promise<Record<string, Uint8Array>> {
+  const stream = SessionLogExport.streamSessionLogZip(
+    directReady(), rootContent, sid('session-root'), false, 6, new AbortController().signal,
+  )
+  return unzipSync(new Uint8Array(await new Response(stream).arrayBuffer()))
+}
+
 describe('session export compression config', () => {
   it('defaults to level 6 and rejects values outside the integer 0-9 range', () => {
     expect(SessionLogExport.Config({})).toEqual({
@@ -163,9 +213,68 @@ describe('session export compression config', () => {
   })
 })
 
+describe('serializeSessionLog', () => {
+  it('writes the physical header line, one line per event, and a trailing newline', () => {
+    const stored = log('session-root')
+    expect(logText(stored)).toBe(
+      `${JSON.stringify({
+        type: 'session', version: 0, id: sid('session-root'), createdAt: 1000, cwd: '/proj', delegationDepth: 0,
+      })}\n${JSON.stringify(turnStart)}\n`,
+    )
+  })
+
+  it('serializes lineage as the physical seedLength and an omitted delegationDepth as 0', () => {
+    const seeded: SessionHeader = {
+      version: 0,
+      id: sid('seeded'),
+      createdAt: 1000,
+      isSeeded: true,
+      parentSession: sid('parent'),
+      origin: 'subagent',
+      agentPreset: 'minimal',
+    }
+    expect(SessionLogExport.serializeSessionLog(seeded, 3, [])).toBe(`${JSON.stringify({
+      type: 'session',
+      version: 0,
+      id: sid('seeded'),
+      createdAt: 1000,
+      parentSession: sid('parent'),
+      seedLength: 3,
+      origin: 'subagent',
+      delegationDepth: 0,
+      agentPreset: 'minimal',
+    })}\n`)
+  })
+})
+
+describe('readSessionLogText', () => {
+  it('reads without a signal and maps only open not-found to undefined', async () => {
+    const stored = log('session-root')
+    const persistence = {
+      open: async (id: SessionId) => {
+        if (id !== stored.header.id) throw new SessionPersistenceNotFoundError(id)
+        return readHandle(stored)
+      },
+    } as never
+    await expect(SessionLogExport.readSessionLogText(persistence, sid('session-root')))
+      .resolves.toBe(logText(stored))
+    await expect(SessionLogExport.readSessionLogText(persistence, sid('absent')))
+      .resolves.toBeUndefined()
+  })
+
+  it('propagates a non-not-found open failure', async () => {
+    const persistence = {
+      open: async () => { throw new Error('EACCES: permission denied') },
+    } as never
+    await expect(SessionLogExport.readSessionLogText(persistence, sid('session-root')))
+      .rejects.toThrow('EACCES: permission denied')
+  })
+})
+
 describe('session.export download endpoint', () => {
-  it('streams a ZIP with the root artifact verbatim under its original filename', async () => {
-    const api = await buildApi({ 'session-root': artifact('session-root') })
+  it('streams a ZIP with the root log serialized as canonical JSONL', async () => {
+    const stored = log('session-root')
+    const api = await buildApi({ 'session-root': stored })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root'),
     )
@@ -174,12 +283,12 @@ describe('session.export download endpoint', () => {
     expect(response.headers.get('content-disposition')).toContain('dsh-session-session-root.zip')
     const files = unzipSync(await responseBytes(response))
     expect(Object.keys(files)).toEqual(['session.jsonl'])
-    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(artifact('session-root').content)
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(logText(stored))
   })
 
   it('preflights root preparation through HEAD without streaming a body', async () => {
-    const readRaw = vi.fn(async () => artifact('session-root'))
-    const api = await buildApi({}, [], { readRaw })
+    const open = vi.fn(async () => readHandle(log('session-root')))
+    const api = await buildApi({}, [], { open })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root', { method: 'HEAD' }),
     )
@@ -188,7 +297,7 @@ describe('session.export download endpoint', () => {
     expect(response.headers.get('content-type')).toBe('application/zip')
     expect(response.headers.get('content-disposition')).toContain('dsh-session-session-root.zip')
     expect(response.body).toBeNull()
-    expect(readRaw).toHaveBeenCalledOnce()
+    expect(open).toHaveBeenCalledOnce()
   })
 
   it('returns a bodyless preparation error from HEAD', async () => {
@@ -202,10 +311,14 @@ describe('session.export download endpoint', () => {
   })
 
   it('uses the resolved compression level for ZIP entries', async () => {
-    const root = artifact('session-root', undefined, 'compressible\n'.repeat(32 * 1024))
-    const storedApi = await buildApi({ 'session-root': root }, [], { compressionLevel: 0 })
-    const compressedApi = await buildApi({ 'session-root': root }, [], { compressionLevel: 9 })
-    const stored = await storedApi.downloads.sessionLog(
+    const filler = {
+      type: 'user/message', seq: SessionSeq(1), time: 1000,
+      data: { content: [{ type: 'text', text: 'compressible '.repeat(32 * 1024) }] },
+    } as unknown as SessionEvent
+    const stored = log('session-root', undefined, [turnStart, filler])
+    const storedApi = await buildApi({ 'session-root': stored }, [], { compressionLevel: 0 })
+    const compressedApi = await buildApi({ 'session-root': stored }, [], { compressionLevel: 9 })
+    const uncompressed = await storedApi.downloads.sessionLog(
       { sessionId: sid('session-root'), includeDescendants: false },
       new AbortController().signal,
     )
@@ -213,17 +326,18 @@ describe('session.export download endpoint', () => {
       { sessionId: sid('session-root'), includeDescendants: false },
       new AbortController().signal,
     )
-    const storedBytes = await responseBytes(stored)
+    const storedBytes = await responseBytes(uncompressed)
     const compressedBytes = await responseBytes(compressed)
     expect(compressedBytes.byteLength).toBeLessThan(storedBytes.byteLength)
-    expect(strFromU8(unzipSync(compressedBytes)['session.jsonl'] as Uint8Array)).toBe(root.content)
+    expect(strFromU8(unzipSync(compressedBytes)['session.jsonl'] as Uint8Array)).toBe(logText(stored))
   })
 
-  it('includes descendant artifacts under subagents/<id>/ when requested', async () => {
+  it('includes descendant logs under subagents/<id>/ when requested', async () => {
+    const child = log('child-a', sid('session-root'))
     const api = await buildApi({
-      'session-root': artifact('session-root'),
-      'child-a': artifact('child-a', sid('session-root')),
-      'grandchild-a': artifact('grandchild-a', sid('child-a')),
+      'session-root': log('session-root'),
+      'child-a': child,
+      'grandchild-a': log('grandchild-a', sid('child-a')),
     }, [
       node('child-a', node('grandchild-a')),
     ])
@@ -238,27 +352,29 @@ describe('session.export download endpoint', () => {
       'subagents/grandchild-a/session.jsonl',
     ])
     expect(strFromU8(files['subagents/child-a/session.jsonl'] as Uint8Array))
-      .toBe(artifact('child-a').content)
+      .toBe(logText(child))
   })
 
-  it('flushes each live root and descendant immediately before reading its artifact', async () => {
-    const stored: Record<string, SessionRawArtifact> = {
-      'session-root': artifact('session-root', undefined, 'stale root'),
-      'child-a': artifact('child-a', sid('session-root'), 'stale child'),
+  it('flushes each live root and descendant immediately before reading its log', async () => {
+    const staleMarker = { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } } as SessionEvent
+    const durableMarker = { type: 'turn/start', seq: SessionSeq(0), time: 2, data: { turn: 1 } } as SessionEvent
+    const stored: Record<string, StoredLog> = {
+      'session-root': log('session-root', undefined, [staleMarker]),
+      'child-a': log('child-a', sid('session-root'), [staleMarker]),
     }
-    const durable: Record<string, SessionRawArtifact> = {
-      'session-root': artifact('session-root', undefined, 'durable root'),
-      'child-a': artifact('child-a', sid('session-root'), 'durable child'),
+    const durable: Record<string, StoredLog> = {
+      'session-root': log('session-root', undefined, [durableMarker]),
+      'child-a': log('child-a', sid('session-root'), [durableMarker]),
     }
     const flushed: SessionId[] = []
     const api = await buildApi(stored, [node('child-a')], {
       sessions: {
         get: id => durable[id] === undefined ? undefined : { id },
         flush: async (session) => {
-          const artifactAfterFlush = durable[session.id]
-          if (artifactAfterFlush === undefined) throw new Error('unexpected session')
+          const logAfterFlush = durable[session.id]
+          if (logAfterFlush === undefined) throw new Error('unexpected session')
           flushed.push(session.id)
-          stored[session.id] = artifactAfterFlush
+          stored[session.id] = logAfterFlush
           return true
         },
       },
@@ -268,14 +384,14 @@ describe('session.export download endpoint', () => {
     )
     const files = unzipSync(await responseBytes(response))
     expect(flushed).toEqual([sid('session-root'), sid('child-a')])
-    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe('durable root')
-    expect(strFromU8(files['subagents/child-a/session.jsonl'] as Uint8Array)).toBe('durable child')
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(logText(durable['session-root'] as StoredLog))
+    expect(strFromU8(files['subagents/child-a/session.jsonl'] as Uint8Array)).toBe(logText(durable['child-a'] as StoredLog))
   })
 
-  it('reads a cold artifact without asking the live-session store to flush', async () => {
+  it('reads a cold log without asking the live-session store to flush', async () => {
     const flush = vi.fn(async () => true)
-    const root = artifact('session-root')
-    const api = await buildApi({ 'session-root': root }, [], {
+    const stored = log('session-root')
+    const api = await buildApi({ 'session-root': stored }, [], {
       sessions: {
         get: () => undefined,
         flush,
@@ -287,28 +403,20 @@ describe('session.export download endpoint', () => {
     )
     const files = unzipSync(await responseBytes(response))
     expect(flush).not.toHaveBeenCalled()
-    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(root.content)
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(logText(stored))
   })
 
-  it('answers 404 for a missing root session', async () => {
+  it('answers 404 for a session the backend does not store', async () => {
     const api = await buildApi({})
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root'),
     )
     expect(response.status).toBe(404)
-  })
-
-  it('answers 501 when the persistence backend has no per-session raw artifacts', async () => {
-    const api = await buildApi({}, [], { persistence: 'unsupported' })
-    const response = await toFetchHandler(api).fetch(
-      new Request('http://host/api/session.export?sessionId=session-root'),
-    )
-    expect(response.status).toBe(501)
-    expect(await response.text()).toContain('does not expose per-session raw artifacts')
+    expect(await response.text()).toBe('session not found')
   })
 
   it('answers 400 when the sessionId query parameter is absent', async () => {
-    const api = await buildApi({ 'session-root': artifact('session-root') })
+    const api = await buildApi({ 'session-root': log('session-root') })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?includeDescendants=true'),
     )
@@ -316,7 +424,7 @@ describe('session.export download endpoint', () => {
   })
 
   it('answers 400 for an includeDescendants value other than true or false', async () => {
-    const api = await buildApi({ 'session-root': artifact('session-root') })
+    const api = await buildApi({ 'session-root': log('session-root') })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=1'),
     )
@@ -332,9 +440,9 @@ describe('session.export download endpoint', () => {
     expect(await response.text()).toContain('session-query')
   })
 
-  it('fails the whole export when a descendant has no stored artifact', async () => {
+  it('fails the whole export when a descendant has no stored log', async () => {
     const api = await buildApi({
-      'session-root': artifact('session-root'),
+      'session-root': log('session-root'),
     }, [node('child-missing')])
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=true'),
@@ -348,35 +456,34 @@ describe('session.export download endpoint', () => {
   it('keeps an astral character whole when its surrogate pair straddles a push boundary', async () => {
     // The push loop slices by 2^16 code units and must back off one unit when
     // the boundary lands inside a surrogate pair; otherwise the pair re-encodes
-    // as U+FFFD and the exported artifact is silently corrupted.
-    const root = { ...artifact('session-root'), content: `${'a'.repeat((1 << 16) - 1)}😀tail` }
-    const api = await buildApi({ 'session-root': root })
-    const response = await toFetchHandler(api).fetch(
-      new Request('http://host/api/session.export?sessionId=session-root'),
-    )
-    const files = unzipSync(await responseBytes(response))
-    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(root.content)
+    // as U+FFFD and the exported log is silently corrupted.
+    const content = `${'a'.repeat((1 << 16) - 1)}😀tail`
+    const files = await directZipFiles(content)
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(content)
   })
 
-  it('splits a long artifact on a plain code-unit boundary without backoff', async () => {
+  it('splits a long log on a plain code-unit boundary without backoff', async () => {
     // A boundary that lands on a BMP character needs no surrogate backoff; the
     // round trip must still be byte-identical across the multi-chunk push.
-    const root = { ...artifact('session-root'), content: 'z'.repeat((1 << 16) + 4096) }
-    const api = await buildApi({ 'session-root': root })
-    const response = await toFetchHandler(api).fetch(
-      new Request('http://host/api/session.export?sessionId=session-root'),
-    )
-    const files = unzipSync(await responseBytes(response))
-    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(root.content)
+    const content = 'z'.repeat((1 << 16) + 4096)
+    const files = await directZipFiles(content)
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(content)
+  })
+
+  it('streams an empty root text as an empty zip entry', async () => {
+    const files = await directZipFiles('')
+    expect(Object.keys(files)).toEqual(['session.jsonl'])
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe('')
   })
 
   it('waits for response pull capacity before reading the next archive entry', async () => {
-    const root = artifact('session-root', undefined, [
-      imageEventLine('after-root'),
-      randomBytes(512 * 1024).toString('base64'),
-    ].join('\n'))
+    const filler = {
+      type: 'user/message', seq: SessionSeq(2), time: 1000,
+      data: { content: [{ type: 'text', text: randomBytes(512 * 1024).toString('base64') }] },
+    } as unknown as SessionEvent
+    const stored = log('session-root', undefined, [imageEvent('after-root'), filler])
     let imageReads = 0
-    const api = await buildApi({ 'session-root': root }, [], {
+    const api = await buildApi({ 'session-root': stored }, [], {
       attachments: async (ref) => {
         imageReads += 1
         return storedImage(String(ref.attachmentId), ref.mediaType)
@@ -401,23 +508,12 @@ describe('session.export download endpoint', () => {
     expect(files['media/after-root.png']).toEqual(storedImage('after-root').data)
   })
 
-  it('exports an empty artifact as an empty zip entry', async () => {
-    const root = { ...artifact('session-root'), content: '' }
-    const api = await buildApi({ 'session-root': root })
-    const response = await toFetchHandler(api).fetch(
-      new Request('http://host/api/session.export?sessionId=session-root'),
-    )
-    const files = unzipSync(await responseBytes(response))
-    expect(Object.keys(files)).toEqual(['session.jsonl'])
-    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe('')
-  })
-
   it('exports a shared lineage node once (seen-set dedup)', async () => {
     const api = await buildApi({
-      'session-root': artifact('session-root'),
-      'child-a': artifact('child-a', sid('session-root')),
-      'child-b': artifact('child-b', sid('session-root')),
-      shared: artifact('shared', sid('child-a')),
+      'session-root': log('session-root'),
+      'child-a': log('child-a', sid('session-root')),
+      'child-b': log('child-b', sid('session-root')),
+      shared: log('shared', sid('child-a')),
     }, [
       node('child-a', node('shared')),
       node('child-b', node('shared')),
@@ -434,19 +530,19 @@ describe('session.export download endpoint', () => {
     ])
   })
 
-  it('answers 500 without leaking the backend error when the root artifact read fails', async () => {
+  it('answers 500 without leaking the backend error when the root read fails', async () => {
     const api = await buildApi({}, [], { query: true, persistence: 'throw' })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root'),
     )
     expect(response.status).toBe(500)
     const body = await response.text()
-    expect(body).toBe('session log export failed to prepare the stored artifact')
+    expect(body).toBe('session log export failed to read the stored log')
     expect(body).not.toContain('/host/private/')
   })
 
   it('answers the private-error-safe 500 when the live root flush fails', async () => {
-    const api = await buildApi({ 'session-root': artifact('session-root') }, [], {
+    const api = await buildApi({ 'session-root': log('session-root') }, [], {
       sessions: {
         get: id => ({ id }),
         flush: async () => { throw new Error('/host/private/flush-state') },
@@ -457,7 +553,7 @@ describe('session.export download endpoint', () => {
     )
     expect(response.status).toBe(500)
     const body = await response.text()
-    expect(body).toBe('session log export failed to prepare the stored artifact')
+    expect(body).toBe('session log export failed to read the stored log')
     expect(body).not.toContain('/host/private/')
   })
 
@@ -465,11 +561,11 @@ describe('session.export download endpoint', () => {
     const reads: Array<{ id: SessionId; signal: AbortSignal | undefined }> = []
     const traces: AbortSignal[] = []
     const api = await buildApi({}, [node('child-a')], {
-      readRaw: async (id, signal) => {
-        reads.push({ id, signal })
-        return id === sid('session-root')
-          ? artifact('session-root')
-          : artifact('child-a', sid('session-root'))
+      open: async (id, _access, options) => {
+        reads.push({ id, signal: options?.signal })
+        return readHandle(id === sid('session-root')
+          ? log('session-root')
+          : log('child-a', sid('session-root')))
       },
       traceSession: async (_id, signal) => {
         if (signal !== undefined) traces.push(signal)
@@ -503,7 +599,7 @@ describe('session.export download endpoint', () => {
   })
 
   it('preserves request cancellation instead of translating it to HTTP 500', async () => {
-    const api = await buildApi({ 'session-root': artifact('session-root') })
+    const api = await buildApi({ 'session-root': log('session-root') })
     const controller = new AbortController()
     const cancellation = new Error('request cancelled')
     controller.abort(cancellation)
@@ -519,8 +615,9 @@ describe('session.export download endpoint', () => {
       reportDescendantStarted = resolve
     })
     const api = await buildApi({}, [node('child-a')], {
-      readRaw: async (id, signal) => {
-        if (id === sid('session-root')) return artifact('session-root')
+      open: async (id, _access, options) => {
+        if (id === sid('session-root')) return readHandle(log('session-root'))
+        const signal = options?.signal
         if (signal === undefined) throw new Error('missing descendant signal')
         reportDescendantStarted(signal)
         return new Promise((_, reject) => {
@@ -548,11 +645,8 @@ describe('session.export download endpoint', () => {
     const attachmentStarted = new Promise<AbortSignal>((resolve) => {
       reportAttachmentStarted = resolve
     })
-    const root = artifact('session-root', undefined, [
-      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
-      imageEventLine('slow-img'),
-    ].join('\n') + '\n')
-    const api = await buildApi({ 'session-root': root }, [], {
+    const stored = log('session-root', undefined, [imageEvent('slow-img')])
+    const api = await buildApi({ 'session-root': stored }, [], {
       attachments: async (_ref, signal) => {
         if (signal === undefined) throw new Error('missing attachment signal')
         reportAttachmentStarted(signal)
@@ -582,8 +676,9 @@ describe('session.export download endpoint', () => {
       reportDescendantStarted = resolve
     })
     const api = await buildApi({}, [node('child-a')], {
-      readRaw: async (id, signal) => {
-        if (id === sid('session-root')) return artifact('session-root')
+      open: async (id, _access, options) => {
+        if (id === sid('session-root')) return readHandle(log('session-root'))
+        const signal = options?.signal
         if (signal === undefined) throw new Error('missing descendant signal')
         reportDescendantStarted(signal)
         return new Promise((_, reject) => {
@@ -606,8 +701,8 @@ describe('session.export download endpoint', () => {
 
   it('normalizes a non-Error descendant failure before erroring the stream', async () => {
     const api = await buildApi({}, [node('child-a')], {
-      readRaw: async (id) => {
-        if (id === sid('session-root')) return artifact('session-root')
+      open: async (id) => {
+        if (id === sid('session-root')) return readHandle(log('session-root'))
         throw 'descendant read failed'
       },
     })
@@ -619,11 +714,8 @@ describe('session.export download endpoint', () => {
   })
 
   it('includes media objects referenced by the root log under media/<id>.<ext>', async () => {
-    const root = artifact('session-root', undefined, [
-      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
-      imageEventLine('img-1'),
-    ].join('\n') + '\n')
-    const api = await buildApi({ 'session-root': root })
+    const stored = log('session-root', undefined, [imageEvent('img-1')])
+    const api = await buildApi({ 'session-root': stored })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root'),
     )
@@ -634,12 +726,11 @@ describe('session.export download endpoint', () => {
   })
 
   it('collects media referenced from nested tool results', async () => {
-    const nested = '{"type":"assistant/message","seq":2,"time":2000,"data":{"content":[{"type":"tool-result","content":[{"type":"image","attachment":{"attachmentId":"nested-1","mediaType":"image/webp","bytes":4,"width":2,"height":2}}]}]}}'
-    const root = artifact('session-root', undefined, [
-      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
-      nested,
-    ].join('\n') + '\n')
-    const api = await buildApi({ 'session-root': root })
+    const nested = {
+      type: 'assistant/message', seq: SessionSeq(2), time: 2000,
+      data: { content: [{ type: 'tool-result', content: [{ type: 'image', attachment: { attachmentId: 'nested-1', mediaType: 'image/webp', bytes: 4, width: 2, height: 2 } }] }] },
+    } as unknown as SessionEvent
+    const api = await buildApi({ 'session-root': log('session-root', undefined, [nested]) })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root'),
     )
@@ -648,18 +739,21 @@ describe('session.export download endpoint', () => {
   })
 
   it('scans the wrapped, inserted, and chunk carriers plus non-object content items', async () => {
-    const block = (id: string, mediaType: string) =>
-      `{"type":"image","attachment":{"attachmentId":"${id}","mediaType":"${mediaType}","bytes":4,"width":2,"height":2}}`
-    const wrapped = `{"type":"assistant/message","seq":2,"time":2000,"data":{"message":{"role":"assistant","content":["noise",${block('wrapped-1', 'image/jpeg')}]}}}`
-    const inserted = `{"type":"context/inserted","seq":3,"time":3000,"data":{"inserted":[{"content":[${block('inserted-1', 'image/gif')}]}]}}`
-    const chunk = `{"type":"assistant/chunk","seq":4,"time":4000,"data":{"chunk":{"type":"block-end","block":${block('chunk-1', 'image/png')}}}}`
-    const root = artifact('session-root', undefined, [
-      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
-      wrapped,
-      inserted,
-      chunk,
-    ].join('\n') + '\n')
-    const api = await buildApi({ 'session-root': root })
+    const block = (id: string, mediaType: string): unknown =>
+      ({ type: 'image', attachment: { attachmentId: id, mediaType, bytes: 4, width: 2, height: 2 } })
+    const wrapped = {
+      type: 'assistant/message', seq: SessionSeq(2), time: 2000,
+      data: { message: { role: 'assistant', content: ['noise', block('wrapped-1', 'image/jpeg')] } },
+    } as unknown as SessionEvent
+    const inserted = {
+      type: 'context/inserted', seq: SessionSeq(3), time: 3000,
+      data: { inserted: [{ content: [block('inserted-1', 'image/gif')] }] },
+    } as unknown as SessionEvent
+    const chunk = {
+      type: 'assistant/chunk', seq: SessionSeq(4), time: 4000,
+      data: { chunk: { type: 'block-end', block: block('chunk-1', 'image/png') } },
+    } as unknown as SessionEvent
+    const api = await buildApi({ 'session-root': log('session-root', undefined, [wrapped, inserted, chunk]) })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root'),
     )
@@ -673,15 +767,8 @@ describe('session.export download endpoint', () => {
   })
 
   it('deduplicates one media object referenced by several included logs', async () => {
-    const line = imageEventLine('shared-img')
-    const root = artifact('session-root', undefined, [
-      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
-      line,
-    ].join('\n') + '\n')
-    const child = artifact('child-a', sid('session-root'), [
-      '{"type":"session","version":0,"id":"child-a","createdAt":1000}',
-      line,
-    ].join('\n') + '\n')
+    const root = log('session-root', undefined, [imageEvent('shared-img')])
+    const child = log('child-a', sid('session-root'), [imageEvent('shared-img')])
     const api = await buildApi({ 'session-root': root, 'child-a': child }, [node('child-a')])
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=true'),
@@ -692,11 +779,8 @@ describe('session.export download endpoint', () => {
   })
 
   it('includes descendant media only when descendants are requested', async () => {
-    const child = artifact('child-a', sid('session-root'), [
-      '{"type":"session","version":0,"id":"child-a","createdAt":1000}',
-      imageEventLine('child-img'),
-    ].join('\n') + '\n')
-    const api = await buildApi({ 'session-root': artifact('session-root'), 'child-a': child }, [node('child-a')])
+    const child = log('child-a', sid('session-root'), [imageEvent('child-img')])
+    const api = await buildApi({ 'session-root': log('session-root'), 'child-a': child }, [node('child-a')])
     const without = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root'),
     )
@@ -712,11 +796,8 @@ describe('session.export download endpoint', () => {
   })
 
   it('fails the whole export when a referenced image cannot be read', async () => {
-    const root = artifact('session-root', undefined, [
-      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
-      imageEventLine('gone-img'),
-    ].join('\n') + '\n')
-    const api = await buildApi({ 'session-root': root }, [], {
+    const stored = log('session-root', undefined, [imageEvent('gone-img')])
+    const api = await buildApi({ 'session-root': stored }, [], {
       attachments: async () => { throw new Error('attachment bytes missing') },
     })
     const response = await toFetchHandler(api).fetch(
@@ -727,7 +808,7 @@ describe('session.export download endpoint', () => {
   })
 
   it('answers 500 when the deployment mounts no attachments service', async () => {
-    const api = await buildApi({ 'session-root': artifact('session-root') }, [], { attachments: false })
+    const api = await buildApi({ 'session-root': log('session-root') }, [], { attachments: false })
     const response = await toFetchHandler(api).fetch(
       new Request('http://host/api/session.export?sessionId=session-root'),
     )
diff --git a/packages/session-query/session-log-export/tests/route.host.spec.ts b/packages/session-query/session-log-export/tests/route.host.spec.ts
index 19d07bb9de..fcfe1df75d 100644
--- a/packages/session-query/session-log-export/tests/route.host.spec.ts
+++ b/packages/session-query/session-log-export/tests/route.host.spec.ts
@@ -1,9 +1,8 @@
 import { Context } from '@deepseek-ai/cordis'
 import { HostConnectionService } from '@deepseek-ai/dsh-client-connection'
 import type { BrowserAuth } from '@deepseek-ai/dsh-client-connection/src/browser-auth.ts'
-import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionHandle } from '@deepseek-ai/dsh-session-persistence'
 import { strFromU8, unzipSync } from 'fflate'
 import { describe, expect, it } from 'vitest'
 import {
@@ -15,28 +14,22 @@ import {
 
 const sid = (value: string): SessionId => value as SessionId
 
-function artifact(id: string): SessionRawArtifact {
+function readHandle(id: string): SessionHandle {
   const header: SessionHeader = {
     version: 0,
     id: sid(id),
     createdAt: 1,
-    cwd: '/workspace',
     isSeeded: false,
+    cwd: '/workspace',
     delegationDepth: 0,
   }
   return {
-    meta: header,
-    inheritedEventCount: SessionLogOffset(0),
-    filename: 'session.jsonl',
-    content: `${JSON.stringify({
-      type: 'session',
-      version: header.version,
-      id: header.id,
-      createdAt: header.createdAt,
-      cwd: header.cwd,
-      delegationDepth: header.delegationDepth,
-    })}\n`,
-  }
+    id: header.id,
+    header,
+    access: 'read',
+    read: async () => [],
+    close: async () => {},
+  } as unknown as SessionHandle
 }
 
 async function mounted(withServices: boolean): Promise<{
@@ -50,8 +43,8 @@ async function mounted(withServices: boolean): Promise<{
       traceSession: async () => ({ descendants: [] }),
     } as never)
     ctx.provide('sessionPersistence', {
-      supportsRawArtifacts: true,
-      readRaw: async (id: SessionId) => artifact(String(id)),
+      stat: async (id: SessionId) => ({ header: readHandle(String(id)).header }),
+      open: async (id: SessionId) => readHandle(String(id)),
     } as never)
     ctx.provide('attachments', {
       readImage: async () => { throw new Error('fixture has no images') },
@@ -74,9 +67,7 @@ describe('Session log export Fetch route', () => {
     expect(response.status).toBe(200)
     expect(response.headers.get('content-type')).toBe('application/zip')
     const files = unzipSync(new Uint8Array(await response.arrayBuffer()))
-    const exported = strFromU8(files['session.jsonl'] as Uint8Array)
-    expect(exported).toContain('"id":"session-1"')
-    expect(exported).not.toContain('isSeeded')
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toContain('"id":"session-1"')
 
     const head = await shared.fetch(new Request(
       `http://host${SESSION_LOG_EXPORT_PATH}?sessionId=session-1`, { method: 'HEAD' },
diff --git a/packages/session-query/session-query-sqlite/README.i18n.yaml b/packages/session-query/session-query-sqlite/README.i18n.yaml
index 23e7b38fac..70ff2fc46a 100644
--- a/packages/session-query/session-query-sqlite/README.i18n.yaml
+++ b/packages/session-query/session-query-sqlite/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/session-query/session-query-sqlite/README.md
-README.md: 1db3999186beebc10a6a3c6874122fa65f2787a3
-README.zh.md: f6ef419293ab0df3a3edfd171cc60bc62ee4bcb0
+README.md: 9d0f4965aceb552ff6fd8cc3e0fc2cadf59125b3
+README.zh.md: 6b0e5641e791205fdfb066ea62eb69f6f990f5f7
diff --git a/packages/session-query/session-query-sqlite/README.md b/packages/session-query/session-query-sqlite/README.md
index 1db3999186..9d0f4965ac 100644
--- a/packages/session-query/session-query-sqlite/README.md
+++ b/packages/session-query/session-query-sqlite/README.md
@@ -49,7 +49,8 @@ Choose it when you want full-text recall over prior sessions with ranking and pa
 | `maxLimit` | `100` | Largest accepted request page size |
 | `snippetChars` | `240` | Maximum snippet length in Unicode code points |
 | `readWindowMax` | `50` | Maximum `before`/`after` raw events for the inherited `readEvent()` |
-| `persistedInspectConcurrency` | `4` | Concurrent persisted-log inspections for inherited batch reads |
+| `persistedReadConcurrency` | `4` | Concurrent persisted-log reads for inherited batch reads |
+| `preparedSessionCacheSize` | `5` | Cold prepared-Session observations the inherited `observeSession` reader retains for reuse |
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-session-query-sqlite) is the exhaustive source for every accepted field and its JSDoc.
 
@@ -84,7 +85,7 @@ This section explains the design decisions behind the backend and points at the
 The backend is built on one separation and three commitments:
 
 - **Derived index, never the source store.** The FTS rows live in a dedicated disposable database; the session-persistence database is never opened here.
-- **Live-preferred observation.** One serialized state machine compares persistence snapshot revisions, inspects only new or changed logs, and reconciles in one transaction, so a search reflects the newest stable state.
+- **Live-preferred observation.** One serialized state machine compares persistence snapshot revisions, reads only new or changed logs through short-lived read handles, and reconciles in one transaction, so a search reflects the newest stable state.
 - **Generation-bound cursors.** Every corpus change bumps a generation; cursors carry the generation they were created under and fail stale rather than returning a shifted page.
 - **Literal phrases as data.** Caller query text is quoted into one FTS5 phrase so query syntax stays inert, and reserved highlight markers are stripped from documents before indexing.
 
@@ -101,7 +102,7 @@ The design history lives in the [SQLite FTS5 session search note](../../../.agen
 
 ### Index lifecycle
 
-Persisted FTS rows live in a dedicated derived database and survive restarts; live sessions use connection-local TEMP tables that shadow the durable base for the same session and reveal it again when the live owner detaches. Both tables retain the exact inherited cut in numeric `seed_length`; reconstructed headers expose only `isSeeded`, while the cut participates in live fingerprints and persisted source revisions. Each search runs one serialized observation: list persistence snapshots, compare per-session revisions with the indexed rows, inspect only new or changed logs, extract semantic documents, and commit the reconciliation in one transaction before running the query. Repeated queries and unchanged reopens inspect nothing; switching stores or observing new, changed, deleted, or externally repaired sources reconciles on the next stable observation. Source or transaction failure commits nothing and the next search retries.
+Persisted FTS rows live in a dedicated derived database and survive restarts; live sessions use connection-local TEMP tables that shadow the durable base for the same session and reveal it again when the live owner detaches. Both tables retain the exact inherited cut in numeric `seed_length`; reconstructed headers expose only `isSeeded`, while the cut participates in live fingerprints and persisted source revisions. Each search runs one serialized observation: list persistence snapshots, compare per-session revisions with the indexed rows, read only new or changed logs through a read handle (balancing an interrupted final turn in memory, never writing back), extract semantic documents, and commit the reconciliation in one transaction before running the query. Repeated queries and unchanged reopens read nothing; switching stores or observing new, changed, deleted, or externally repaired sources reconciles on the next stable observation. Source or transaction failure commits nothing and the next search retries.
 
 ### Schema ownership
 
diff --git a/packages/session-query/session-query-sqlite/README.zh.md b/packages/session-query/session-query-sqlite/README.zh.md
index f6ef419293..6b0e5641e7 100644
--- a/packages/session-query/session-query-sqlite/README.zh.md
+++ b/packages/session-query/session-query-sqlite/README.zh.md
@@ -49,7 +49,8 @@ kind: "package-reference"
 | `maxLimit` | `100` | 接受的最大请求分页大小 |
 | `snippetChars` | `240` | 按 Unicode 码点计算的最大 snippet 长度 |
 | `readWindowMax` | `50` | 继承的 `readEvent()` 的 `before`/`after` 原始事件数上限 |
-| `persistedInspectConcurrency` | `4` | 继承批量读取的并发持久化日志检查数 |
+| `persistedReadConcurrency` | `4` | 继承批量读取的并发持久化日志读取数 |
+| `preparedSessionCacheSize` | `5` | 继承的 `observeSession` 读取器为复用保留的冷 prepared-Session 观察数 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-session-query-sqlite)是每个受支持字段及其 JSDoc 的穷尽式真源。
 
@@ -84,7 +85,7 @@ kind: "package-reference"
 本后端建立在一个分离与三项承诺之上：
 
 - **派生索引，绝不动源存储。** FTS 行存放在专用可丢弃数据库中；这里的代码从不打开 session-persistence 数据库。
-- **实时优先的观察。** 一个串行化状态机比较持久化快照修订，只检查新增或已更改日志，并在一个事务中对账，因此搜索反映最新的稳定状态。
+- **实时优先的观察。** 一个串行化状态机比较持久化快照修订，只通过短生命周期读取 handle 读取新增或已更改日志，并在一个事务中对账，因此搜索反映最新的稳定状态。
 - **世代绑定的游标。** 每次语料库变化都会递增世代；游标携带其创建时的世代，宁可陈旧失败也不返回偏移后的页面。
 - **字面短语即数据。** 调用方查询文本被引成一个 FTS5 短语，查询语法保持惰性；保留高亮标记在索引前从文档中剥离。
 
@@ -101,7 +102,7 @@ kind: "package-reference"
 
 ### 索引生命周期
 
-持久化 FTS 行存放在专用派生数据库中并跨重启保留；实时会话使用连接本地 TEMP 表，遮蔽同一会话的持久化基库，并在实时所有者脱离后再次显示基库。两类表都在数字 `seed_length` 中保留精确继承切点；重建的 header 只公开 `isSeeded`，而切点参与实时 fingerprint 与持久来源修订。每次搜索执行一次串行化观察：列出持久化快照、把逐会话修订与已索引行比较、只检查新增或已更改日志、提取语义文档，并在运行查询前于一个事务中提交对账。重复查询与不变的重新打开不会检查任何内容；切换存储或观察到新增、已更改、已删除或经外部修复的来源时，会在下次稳定观察时对账。来源或事务失败不提交任何内容，下一次搜索重试。
+持久化 FTS 行存放在专用派生数据库中并跨重启保留；实时会话使用连接本地 TEMP 表，遮蔽同一会话的持久化基库，并在实时所有者脱离后再次显示基库。两类表都在数字 `seed_length` 中保留精确继承切点；重建的 header 只公开 `isSeeded`，而切点参与实时 fingerprint 与持久来源修订。每次搜索执行一次串行化观察：列出持久化快照、把逐会话修订与已索引行比较、只通过读取 handle 读取新增或已更改日志（在内存中补齐被中断的末尾轮次，从不写回）、提取语义文档，并在运行查询前于一个事务中提交对账。重复查询与不变的重新打开不读取任何内容；切换存储或观察到新增、已更改、已删除或经外部修复的来源时，会在下次稳定观察时对账。来源或事务失败不提交任何内容，下一次搜索重试。
 
 ### Schema 归属
 
diff --git a/packages/session-query/session-query-sqlite/src/index.ts b/packages/session-query/session-query-sqlite/src/index.ts
index 4722557a65..18f1fa572d 100644
--- a/packages/session-query/session-query-sqlite/src/index.ts
+++ b/packages/session-query/session-query-sqlite/src/index.ts
@@ -5,17 +5,11 @@
  */
 
 import { createHash, randomUUID } from 'node:crypto'
+import { SessionSeq } from '@deepseek-ai/dsh-session'
 import type { DatabaseSync } from 'node:sqlite'
 import { Context, Service, type Fiber } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
-import { SessionSeq } from '@deepseek-ai/dsh-session'
-import type {
-  Session,
-  SessionEvent,
-  SessionHeader,
-  SessionId,
-  SessionLogOffset,
-} from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionHeader, SessionId , SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
 import type {
   SessionPersistenceRevision,
@@ -23,11 +17,13 @@ import type {
 } from '@deepseek-ai/dsh-session-persistence'
 import SessionQueryEngine, {
   SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
+  SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE,
   SESSION_QUERY_READ_WINDOW_MAX,
   SessionQueryError,
   SessionSearchCursor,
   assertSessionHeadersCompatible,
   buildSessionEventSearchDocuments,
+  readColdSessionLog,
 } from '@deepseek-ai/dsh-session-query'
 import type {
   Config as SessionQueryConfig,
@@ -116,8 +112,10 @@ export interface Config extends SessionQueryConfig {
   maxLimit?: number
   /** Maximum snippet length in Unicode code points. Defaults to 240. */
   snippetChars?: number
-  /** Maximum concurrent persisted-log inspections in one inherited batch read. Defaults to 4. */
-  persistedInspectConcurrency?: number
+  /** Maximum concurrent persisted-log reads in one inherited batch read. Defaults to 4. */
+  persistedReadConcurrency?: number
+  /** Maximum cold prepared-Session observations the inherited reader retains for reuse. Defaults to 5. */
+  preparedSessionCacheSize?: number
 }
 
 interface ResolvedConfig {
@@ -128,7 +126,8 @@ interface ResolvedConfig {
   maxLimit: number
   snippetChars: number
   readWindowMax: number
-  persistedInspectConcurrency: number
+  persistedReadConcurrency: number
+  preparedSessionCacheSize: number
 }
 
 interface ObservedSession {
@@ -212,11 +211,16 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
     maxLimit: z.number().step(1).min(1).max(SQLITE_MAX_PAGE_LIMIT).default(SESSION_QUERY_SQLITE_MAX_LIMIT),
     snippetChars: z.number().step(1).min(1).default(SESSION_QUERY_SQLITE_SNIPPET_CHARS),
     readWindowMax: z.number().step(1).min(0).default(SESSION_QUERY_READ_WINDOW_MAX),
-    persistedInspectConcurrency: z.number()
+    persistedReadConcurrency: z.number()
       .step(1)
       .min(1)
       .max(Number.MAX_SAFE_INTEGER)
       .default(SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY),
+    preparedSessionCacheSize: z.number()
+      .step(1)
+      .min(1)
+      .max(Number.MAX_SAFE_INTEGER)
+      .default(SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE),
   })
 
   /** Validated and defaulted backend configuration. */
@@ -502,28 +506,26 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
         try {
           const canReuseIndexed = this._lastPersistenceIdentity === undefined
             || this._lastPersistenceIdentity === persistenceBinding.identity
-          const before = await persistence.listSnapshots(signal)
+          const listOptions = signal === undefined ? undefined : { signal }
+          const before = await persistence.list(listOptions)
           assertNotAborted(signal)
           persisted = materializePersistenceSnapshots(before)
           for (const entry of persisted.values()) {
             if (canReuseIndexed && indexed.get(entry.header.id)?.revision === entry.revision) continue
-            // Skip work already shadowed by a live owner. `inspect()` is
-            // non-mutating, so an owner attaching after this check cannot cause
-            // crash-repair side effects; the live-membership retry below makes
-            // the returned observation live-preferred.
+            // Skip work already shadowed by a live owner. The cold read is
+            // non-mutating (interrupted turns are balanced in memory only), so
+            // an owner attaching after this check cannot cause side effects;
+            // the live-membership retry below makes the returned observation
+            // live-preferred.
             if (initiallyLive.has(entry.header.id) || this.ctx.sessions.get(entry.header.id) !== undefined) continue
             assertNotAborted(signal)
-            const loaded = await persistence.inspect(entry.header.id, signal)
+            const loaded = await readColdSessionLog(persistence, entry.header.id, signal)
             assertNotAborted(signal)
-            assertSessionHeadersCompatible(entry.header, loaded.meta)
-            entry.loaded = observeSession(
-              loaded.meta,
-              loaded.inheritedEventCount,
-              loaded.events,
-            )
+            assertSessionHeadersCompatible(entry.header, loaded.header)
+            entry.loaded = observeSession(loaded.header, loaded.inheritedEventCount, loaded.events)
           }
           assertNotAborted(signal)
-          const afterSnapshots = await persistence.listSnapshots(signal)
+          const afterSnapshots = await persistence.list(listOptions)
           assertNotAborted(signal)
           const after = materializePersistenceSnapshots(afterSnapshots)
           if (!samePersistenceSnapshots(persisted, after)) continue
@@ -1026,8 +1028,10 @@ function resolveConfig(config: Config): ResolvedConfig {
     maxLimit: config.maxLimit ?? SESSION_QUERY_SQLITE_MAX_LIMIT,
     snippetChars: config.snippetChars ?? SESSION_QUERY_SQLITE_SNIPPET_CHARS,
     readWindowMax: config.readWindowMax ?? SESSION_QUERY_READ_WINDOW_MAX,
-    persistedInspectConcurrency: config.persistedInspectConcurrency
+    persistedReadConcurrency: config.persistedReadConcurrency
       ?? SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
+    preparedSessionCacheSize: config.preparedSessionCacheSize
+      ?? SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE,
   }
   if (typeof resolved.path !== 'string' || resolved.path.trim().length === 0) {
     throw invalidConfig('path must not be blank')
@@ -1041,10 +1045,16 @@ function resolveConfig(config: Config): ResolvedConfig {
     throw invalidConfig('readWindowMax must be a non-negative integer')
   }
   if (
-    !Number.isSafeInteger(resolved.persistedInspectConcurrency)
-    || resolved.persistedInspectConcurrency < 1
+    !Number.isSafeInteger(resolved.persistedReadConcurrency)
+    || resolved.persistedReadConcurrency < 1
   ) {
-    throw invalidConfig('persistedInspectConcurrency must be a positive safe integer')
+    throw invalidConfig('persistedReadConcurrency must be a positive safe integer')
+  }
+  if (
+    !Number.isSafeInteger(resolved.preparedSessionCacheSize)
+    || resolved.preparedSessionCacheSize < 1
+  ) {
+    throw invalidConfig('preparedSessionCacheSize must be a positive safe integer')
   }
   if (resolved.defaultLimit > resolved.maxLimit) {
     throw invalidConfig('defaultLimit must be less than or equal to maxLimit')
diff --git a/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts b/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts
index 29d37915fb..2c5bae0cf0 100644
--- a/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts
+++ b/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts
@@ -8,7 +8,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionSeq, SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SqliteSessionQueryEngine, * as queryModule from '@deepseek-ai/dsh-session-query-sqlite'
@@ -48,13 +48,8 @@ describe('dsh-session-query-sqlite real Loader path', () => {
     const query = await ctx.plugin(unwrapped, { path: searchPath })
 
     const id = SessionId('loader-path')
-    await ctx.sessionPersistence.create({
-      version: SESSION_FORMAT_VERSION,
-      id,
-      createdAt: 10,
-      isSeeded: false,
-    })
-    await ctx.sessionPersistence.append(id, [{
+    const writer = await ctx.sessionPersistence.create({ version: SESSION_FORMAT_VERSION, id, createdAt: 10, isSeeded: false })
+    await writer.append([{
       type: 'user/message',
       seq: SessionSeq(0),
       time: 10,
@@ -63,6 +58,7 @@ describe('dsh-session-query-sqlite real Loader path', () => {
       }),
       surfaceOp: 'append',
     }])
+    await writer.close()
 
     await expect(ctx.sessionQuery.searchSessions({ query: 'Loader needle' }))
       .resolves.toMatchObject({ items: [{ header: { id }, persisted: true, live: false }] })
diff --git a/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts b/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts
index e09d74ba12..c9d944bfc5 100644
--- a/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts
+++ b/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts
@@ -5,16 +5,21 @@ import { DatabaseSync } from 'node:sqlite'
 import { chmod, mkdtemp, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
-import SessionStore, {
-  SESSION_FORMAT_VERSION,
-  SessionId,
-  SessionLogOffset,
-  SessionSeq,
-} from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionLogOffset, SessionSeq, SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
-import SessionPersistence, { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
-import type { SessionEventSuffix, SessionInspection, SessionPersistenceSnapshot } from '@deepseek-ai/dsh-session-persistence'
+import SessionPersistence, {
+  SessionPersistenceNotFoundError,
+  SessionPersistenceRevision,
+  SessionReadOnlyError,
+} from '@deepseek-ai/dsh-session-persistence'
+import type {
+  SessionAccess,
+  SessionHandle,
+  SessionHandleReadOptions,
+  SessionPersistenceListOptions,
+  SessionPersistenceSnapshot,
+} from '@deepseek-ai/dsh-session-persistence'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SqliteSessionQueryEngine, {
   SESSION_QUERY_SQLITE_SCHEMA_VERSION,
@@ -46,7 +51,7 @@ function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}):
   return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, isSeeded: false, ...extra }
 }
 
-function messageEvents(text: string, time = 1): SessionEvent<'user/message'>[] {
+function messageEvents(text: string, time = 1): SessionEvent[] {
   return [{
     type: 'user/message',
     seq: SessionSeq(0),
@@ -72,145 +77,120 @@ function replaceCursorOffset(
   return SessionSearchCursor(Buffer.from(JSON.stringify({ ...payload, offset }), 'utf8').toString('base64url'))
 }
 
-class TestPersistence extends SessionPersistence {
-  override readonly supportsRawArtifacts = false
+class TestHandle implements SessionHandle {
+  readonly inheritedEventCount = SessionLogOffset(0)
 
-  static entries = new Map<SessionIdType, {
-    meta: SessionHeader
-    inheritedEventCount?: SessionLogOffset
-    events: SessionEvent[]
-  }>()
+  constructor(
+    readonly id: SessionIdType,
+    readonly header: SessionHeader,
+    readonly access: SessionAccess,
+  ) {}
+
+  async read(_offset = 0, _length?: number, options?: SessionHandleReadOptions): Promise<readonly SessionEvent[]> {
+    TestPersistence.reads.set(this.id, (TestPersistence.reads.get(this.id) ?? 0) + 1)
+    TestPersistence.readSignals.push(options?.signal)
+    if (TestPersistence.failure !== undefined) throw TestPersistence.failure
+    const entry = TestPersistence.entries.get(this.id)
+    if (entry === undefined) throw new SessionPersistenceNotFoundError(this.id)
+    await TestPersistence.readEffect?.(entry, options?.signal)
+    TestPersistence.readEffect = undefined
+    return structuredClone(entry.events)
+  }
+
+  append(events: readonly SessionEvent[]): Promise<void> {
+    if (this.access === 'read') return Promise.reject(new SessionReadOnlyError(this.id, 'append'))
+    const entry = TestPersistence.entries.get(this.id)
+    if (entry === undefined) return Promise.reject(new SessionPersistenceNotFoundError(this.id))
+    entry.events.push(...structuredClone(events))
+    TestPersistence.revisions.set(this.id, ++TestPersistence.nextRevision)
+    return Promise.resolve()
+  }
+
+  flush(): Promise<void> {
+    if (this.access === 'read') return Promise.reject(new SessionReadOnlyError(this.id, 'flush'))
+    return Promise.resolve()
+  }
+
+  close(): Promise<void> {
+    return Promise.resolve()
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close()
+  }
+}
+
+class TestPersistence extends SessionPersistence {
+  static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
   static revisions = new Map<SessionIdType, number>()
   static nextRevision = 0
-  static loads = new Map<SessionIdType, number>()
-  static inspections = new Map<SessionIdType, number>()
-  static inspectSignals: Array<AbortSignal | undefined> = []
-  static snapshotSignals: Array<AbortSignal | undefined> = []
-  static loadEffect: ((entry: { meta: SessionHeader; events: SessionEvent[] }) => void) | undefined
-  static inspectEffect: ((
+  static reads = new Map<SessionIdType, number>()
+  static readSignals: Array<AbortSignal | undefined> = []
+  static listSignals: Array<AbortSignal | undefined> = []
+  static readEffect: ((
     entry: { meta: SessionHeader; events: SessionEvent[] },
     signal?: AbortSignal,
   ) => void | Promise<void>) | undefined
   static listGate: Promise<void> | undefined
   static listStarted: (() => void) | undefined
-  static snapshotEffect: ((signal?: AbortSignal) => void | Promise<void>) | undefined
-  static snapshotOverride: (() => SessionPersistenceSnapshot[]) | undefined
+  static listEffect: ((signal?: AbortSignal) => void | Promise<void>) | undefined
+  static listOverride: (() => SessionPersistenceSnapshot[]) | undefined
   static failure: unknown
 
-  locate(_meta: SessionHeader): undefined {
-    return undefined
-  }
-
-  borrowSession(_id: SessionIdType, _signal?: AbortSignal): ReturnType<SessionPersistence['borrowSession']> {
-    return Promise.reject(new Error('not used'))
-  }
-
-  static reset(entries: readonly {
-    meta: SessionHeader
-    inheritedEventCount?: SessionLogOffset
-    events: SessionEvent[]
-  }[] = []): void {
+  static reset(entries: readonly { meta: SessionHeader; events: SessionEvent[] }[] = []): void {
     this.entries = new Map()
     this.revisions = new Map()
-    this.loads = new Map()
-    this.inspections = new Map()
-    this.inspectSignals = []
-    this.snapshotSignals = []
-    this.loadEffect = undefined
-    this.inspectEffect = undefined
+    this.reads = new Map()
+    this.readSignals = []
+    this.listSignals = []
+    this.readEffect = undefined
     for (const entry of entries) this.set(entry)
     this.listGate = undefined
     this.listStarted = undefined
-    this.snapshotEffect = undefined
-    this.snapshotOverride = undefined
+    this.listEffect = undefined
+    this.listOverride = undefined
     this.failure = undefined
   }
 
-  static set(entry: {
-    meta: SessionHeader
-    inheritedEventCount?: SessionLogOffset
-    events: SessionEvent[]
-  }): void {
+  static set(entry: { meta: SessionHeader; events: SessionEvent[] }): void {
     this.entries.set(entry.meta.id, structuredClone(entry))
     this.revisions.set(entry.meta.id, ++this.nextRevision)
   }
 
-  create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void> {
-    TestPersistence.set({
-      meta,
-      ...inheritedEventCount === undefined ? {} : { inheritedEventCount },
-      events: [],
+  create(header: SessionHeader): Promise<SessionHandle> {
+    TestPersistence.set({ meta: header, events: [] })
+    return Promise.resolve(new TestHandle(header.id, structuredClone(header), 'write'))
+  }
+
+  // Appends are durable on resolution here; nothing buffers, so the service-wide flush is a no-op.
+  async flush(): Promise<void> {}
+
+  open(id: SessionIdType, access: SessionAccess): Promise<SessionHandle> {
+    const entry = TestPersistence.entries.get(id)
+    if (entry === undefined) return Promise.reject(new SessionPersistenceNotFoundError(id))
+    return Promise.resolve(new TestHandle(id, structuredClone(entry.meta), access))
+  }
+
+  stat(id: SessionIdType): Promise<SessionPersistenceSnapshot | undefined> {
+    const entry = TestPersistence.entries.get(id)
+    if (entry === undefined) return Promise.resolve(undefined)
+    return Promise.resolve({
+      header: structuredClone(entry.meta),
+      revision: SessionPersistenceRevision(`test:${TestPersistence.revisions.get(id)}`),
     })
-    return Promise.resolve()
   }
 
-  append(id: SessionIdType, events: readonly SessionEvent[]): Promise<void> {
-    const entry = TestPersistence.entries.get(id)
-    if (entry === undefined) return Promise.reject(new Error('missing test session'))
-    entry.events.push(...structuredClone(events))
-    TestPersistence.revisions.set(id, ++TestPersistence.nextRevision)
-    return Promise.resolve()
-  }
-
-  async load(id: SessionIdType): Promise<SessionInspection> {
-    TestPersistence.loads.set(id, (TestPersistence.loads.get(id) ?? 0) + 1)
-    if (TestPersistence.failure !== undefined) throw TestPersistence.failure
-    const entry = TestPersistence.entries.get(id)
-    if (entry === undefined) throw new Error('missing test session')
-    if (TestPersistence.loadEffect !== undefined) {
-      const effect = TestPersistence.loadEffect
-      TestPersistence.loadEffect = undefined
-      effect(entry)
-      TestPersistence.revisions.set(id, ++TestPersistence.nextRevision)
-    }
-    return {
-      ...structuredClone(entry),
-      inheritedEventCount: entry.inheritedEventCount ?? SessionLogOffset(0),
-    }
-  }
-
-  async inspect(id: SessionIdType, signal?: AbortSignal): Promise<SessionInspection> {
-    TestPersistence.inspections.set(id, (TestPersistence.inspections.get(id) ?? 0) + 1)
-    TestPersistence.inspectSignals.push(signal)
-    if (TestPersistence.failure !== undefined) throw TestPersistence.failure
-    const entry = TestPersistence.entries.get(id)
-    if (entry === undefined) throw new Error('missing test session')
-    await TestPersistence.inspectEffect?.(entry, signal)
-    TestPersistence.inspectEffect = undefined
-    return {
-      ...structuredClone(entry),
-      inheritedEventCount: entry.inheritedEventCount ?? SessionLogOffset(0),
-    }
-  }
-
-  async readFrom(
-    id: SessionIdType,
-    fromSeq: SessionLogOffset,
-    signal?: AbortSignal,
-  ): Promise<SessionEventSuffix> {
-    const whole = await this.inspect(id, signal)
-    return { ...whole, fromSeq, events: whole.events.filter(event => event.seq >= fromSeq) }
-  }
-
-  async list(): Promise<SessionHeader[]> {
+  async list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]> {
+    TestPersistence.listSignals.push(options?.signal)
     TestPersistence.listStarted?.()
     await TestPersistence.listGate
     if (TestPersistence.failure !== undefined) throw TestPersistence.failure
-    return [...TestPersistence.entries.values()].map(entry => structuredClone(entry.meta))
-  }
-
-
-  async listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]> {
-    TestPersistence.snapshotSignals.push(signal)
-    TestPersistence.listStarted?.()
-    await TestPersistence.listGate
-    if (TestPersistence.failure !== undefined) throw TestPersistence.failure
-    const snapshots = TestPersistence.snapshotOverride?.()
+    const snapshots = TestPersistence.listOverride?.()
       ?? [...TestPersistence.entries.values()].map(entry => ({
         header: structuredClone(entry.meta),
         revision: SessionPersistenceRevision(`test:${TestPersistence.revisions.get(entry.meta.id)}`),
       }))
-    await TestPersistence.snapshotEffect?.(signal)
+    await TestPersistence.listEffect?.(options?.signal)
     return snapshots
   }
 }
@@ -227,25 +207,25 @@ describe('SQLite session search', () => {
   it('defaults and validates opening policy and persisted inspection concurrency through its Cordis config', async () => {
     const defaultCtx = await liveContext()
     expect((defaultCtx.sessionQuery as SqliteSessionQueryEngine).config.openAt).toBe('startup')
-    expect((defaultCtx.sessionQuery as SqliteSessionQueryEngine).config.persistedInspectConcurrency)
+    expect((defaultCtx.sessionQuery as SqliteSessionQueryEngine).config.persistedReadConcurrency)
       .toBe(SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY)
 
     const configuredValue = 2
     const configured = new SqliteSessionQueryEngine.Config({
       path: ':memory:',
       openAt: 'first-search',
-      persistedInspectConcurrency: configuredValue,
+      persistedReadConcurrency: configuredValue,
     })
     expect(configured.openAt).toBe('first-search')
-    expect(configured.persistedInspectConcurrency).toBe(configuredValue)
+    expect(configured.persistedReadConcurrency).toBe(configuredValue)
     const configuredCtx = await liveContext(configured)
-    expect((configuredCtx.sessionQuery as SqliteSessionQueryEngine).config.persistedInspectConcurrency)
+    expect((configuredCtx.sessionQuery as SqliteSessionQueryEngine).config.persistedReadConcurrency)
       .toBe(configuredValue)
 
-    for (const persistedInspectConcurrency of [0, Number.MAX_SAFE_INTEGER + 1]) {
+    for (const persistedReadConcurrency of [0, Number.MAX_SAFE_INTEGER + 1]) {
       expect(() => new SqliteSessionQueryEngine.Config({
         path: ':memory:',
-        persistedInspectConcurrency,
+        persistedReadConcurrency,
       })).toThrow()
     }
     expect(() => new SqliteSessionQueryEngine.Config({
@@ -371,43 +351,10 @@ describe('SQLite session search', () => {
     await expect(ctx.sessionQuery.searchEvents({ sessionId: session.id, query: 'AI' }))
       .resolves.toMatchObject({
         session: session.header,
-        items: [{ sessionId: session.id, seq: 2, snippet: 'An AI helper' }],
+        items: [{ sessionId: session.id, seq: SessionSeq(2), snippet: 'An AI helper' }],
       })
     await expect(ctx.sessionQuery.searchSessions({ query: 'AI' }))
       .resolves.toMatchObject({ items: [{ header: session.header, live: true, persisted: false }] })
-    const db = (ctx.sessionQuery as unknown as { _db: DatabaseSync })._db
-    expect(db.prepare('SELECT seed_length FROM temp.live_sessions WHERE id = ?').get(session.id))
-      .toEqual({ seed_length: 1 })
-  })
-
-  it('retains a persisted inherited cut and reindexes when that source identity changes', async () => {
-    const meta = header('persisted-seed-cut', 10, { isSeeded: true })
-    const events: SessionEvent[] = [
-      ...messageEvents('persisted cut needle'),
-      { ...messageEvents('second inherited event')[0]!, seq: SessionSeq(1) },
-    ]
-    TestPersistence.reset([{
-      meta,
-      inheritedEventCount: SessionLogOffset(1),
-      events,
-    }])
-    const ctx = await liveContext()
-    await ctx.plugin(TestPersistence)
-    const db = (ctx.sessionQuery as unknown as { _db: DatabaseSync })._db
-
-    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
-      .resolves.toMatchObject({ items: [{ header: { ...meta, isSeeded: true } }] })
-    expect(db.prepare('SELECT seed_length FROM persisted_sessions WHERE id = ?').get(meta.id))
-      .toEqual({ seed_length: 1 })
-
-    TestPersistence.set({
-      meta,
-      inheritedEventCount: SessionLogOffset(2),
-      events,
-    })
-    await ctx.sessionQuery.searchSessions({ query: 'needle' })
-    expect(db.prepare('SELECT seed_length FROM persisted_sessions WHERE id = ?').get(meta.id))
-      .toEqual({ seed_length: 2 })
   })
 
   it('excludes assistant reasoning while indexing visible answer text', async () => {
@@ -467,7 +414,7 @@ describe('SQLite session search', () => {
         { kind: 'type', values: ['user/message'] },
         { kind: 'surface', values: ['current'] },
       ],
-    })).resolves.toMatchObject({ items: [{ seq: 2, surface: 'current' }] })
+    })).resolves.toMatchObject({ items: [{ seq: SessionSeq(2), surface: 'current' }] })
 
     const grouped = await ctx.sessionQuery.searchSessions({
       query: 'needle',
@@ -485,7 +432,7 @@ describe('SQLite session search', () => {
       header: { id: SessionId('a'), cwd: '/a', parentSession: parent },
       live: true,
       persisted: false,
-      bestMatch: { seq: 0, surface: 'shadowed' },
+      bestMatch: { seq: SessionSeq(0), surface: 'shadowed' },
     })
   })
 
@@ -510,7 +457,7 @@ describe('SQLite session search', () => {
       sessionId: session.id,
       query: 'needle',
       filters: eventFilters,
-    })).resolves.toMatchObject({ items: [{ sessionId: session.id, seq: 0 }] })
+    })).resolves.toMatchObject({ items: [{ sessionId: session.id, seq: SessionSeq(0) }] })
   })
 
   it('rejects unsupported FTS5 outer-predicate counts with typed errors', async () => {
@@ -745,8 +692,10 @@ describe('SQLite session search', () => {
       { path: ':memory:', maxLimit: 1e100 },
       { path: ':memory:', snippetChars: 0 },
       { path: ':memory:', readWindowMax: -1 },
-      { path: ':memory:', persistedInspectConcurrency: 0 },
-      { path: ':memory:', persistedInspectConcurrency: Number.MAX_SAFE_INTEGER + 1 },
+      { path: ':memory:', persistedReadConcurrency: 0 },
+      { path: ':memory:', persistedReadConcurrency: Number.MAX_SAFE_INTEGER + 1 },
+      { path: ':memory:', preparedSessionCacheSize: 0 },
+      { path: ':memory:', preparedSessionCacheSize: Number.MAX_SAFE_INTEGER + 1 },
       { path: ':memory:', defaultLimit: 3, maxLimit: 2 },
       { path: ':memory:', openAt: 'later' },
       { path: ':memory:', journalMode: 'memory' },
@@ -884,14 +833,12 @@ describe('SQLite reconciliation and source lifecycle', () => {
     })).resolves.toMatchObject({
       items: [{ header: shared, live: true, persisted: true }],
     })
-    expect(TestPersistence.loads.get(shared.id)).toBeUndefined()
-    expect(TestPersistence.inspections.get(shared.id)).toBeUndefined()
+    expect(TestPersistence.reads.get(shared.id)).toBeUndefined()
 
     detach()
     await expect(ctx.sessionQuery.searchSessions({ query: 'persisted' }))
       .resolves.toMatchObject({ items: [{ header: shared, live: false, persisted: true }] })
-    expect(TestPersistence.loads.get(shared.id)).toBeUndefined()
-    expect(TestPersistence.inspections.get(shared.id)).toBe(1)
+    expect(TestPersistence.reads.get(shared.id)).toBe(1)
     await persistence.dispose()
   })
 
@@ -899,8 +846,8 @@ describe('SQLite reconciliation and source lifecycle', () => {
     TestPersistence.reset()
     const ctx = await liveContext()
     await ctx.plugin(TestPersistence)
-    TestPersistence.snapshotEffect = () => {
-      TestPersistence.snapshotEffect = undefined
+    TestPersistence.listEffect = () => {
+      TestPersistence.listEffect = undefined
       ctx.sessions.create(SessionId('attached'), { seed: messageEvents('attached needle') })
     }
 
@@ -908,16 +855,13 @@ describe('SQLite reconciliation and source lifecycle', () => {
       .resolves.toMatchObject({ items: [{ header: { id: SessionId('attached') } }] })
   })
 
-  it('cannot crash-repair a log when live ownership begins during persisted inspection', async () => {
-    const shared = header('attach-during-inspect', 10)
+  it('prefers a live owner that attaches during a persisted read and never mutates the store', async () => {
+    const shared = header('attach-during-read', 10)
     const persistedEvents = messageEvents('persisted needle')
     TestPersistence.reset([{ meta: shared, events: persistedEvents }])
     const ctx = await liveContext()
     await ctx.plugin(TestPersistence)
-    TestPersistence.loadEffect = (entry) => {
-      entry.events = messageEvents('incorrect repair')
-    }
-    TestPersistence.inspectEffect = () => {
+    TestPersistence.readEffect = () => {
       ctx.sessions.create(shared.id, {
         seed: messageEvents('live needle'),
         meta: { createdAt: shared.createdAt },
@@ -926,7 +870,7 @@ describe('SQLite reconciliation and source lifecycle', () => {
 
     await expect(ctx.sessionQuery.searchSessions({ query: 'live' }))
       .resolves.toMatchObject({ items: [{ header: shared, live: true, persisted: true }] })
-    expect(TestPersistence.loads.get(shared.id)).toBeUndefined()
+    // The cold read is observation-only: the stored log is unchanged.
     expect(TestPersistence.entries.get(shared.id)?.events).toEqual(persistedEvents)
   })
 
@@ -937,8 +881,8 @@ describe('SQLite reconciliation and source lifecycle', () => {
     const detachFirst = ctx.sessions.enter(first)
     ctx.sessions.announce(first)
     await ctx.plugin(TestPersistence)
-    TestPersistence.snapshotEffect = () => {
-      TestPersistence.snapshotEffect = undefined
+    TestPersistence.listEffect = () => {
+      TestPersistence.listEffect = undefined
       detachFirst()
       ctx.sessions.create(SessionId('second'), { seed: messageEvents('second needle') })
     }
@@ -1040,10 +984,10 @@ describe('SQLite reconciliation and source lifecycle', () => {
     TestPersistence.revisions.set(durable.id, revision)
     const replacement = await ctx.plugin(TestPersistence)
     const page = await ctx.sessionQuery.searchSessions({ query: 'new needle' })
-    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    expect(TestPersistence.reads.get(durable.id)).toBe(2)
     expect(page).toMatchObject({ items: [{ header: durable }] })
     await expect(ctx.sessionQuery.searchSessions({ query: 'old' })).resolves.toEqual({ items: [] })
-    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    expect(TestPersistence.reads.get(durable.id)).toBe(2)
     await replacement.dispose()
   })
 
@@ -1053,7 +997,7 @@ describe('SQLite reconciliation and source lifecycle', () => {
     const ctx = await liveContext()
     const persistence = await ctx.plugin(TestPersistence)
     let lists = 0
-    TestPersistence.snapshotEffect = async () => {
+    TestPersistence.listEffect = async () => {
       lists += 1
       if (lists === 2) await persistence.dispose()
     }
@@ -1068,15 +1012,15 @@ describe('SQLite reconciliation and source lifecycle', () => {
     TestPersistence.reset([{ meta: first, events: messageEvents('first needle') }])
     const ctx = await liveContext()
     await ctx.plugin(TestPersistence)
-    TestPersistence.snapshotEffect = () => {
-      TestPersistence.snapshotEffect = undefined
+    TestPersistence.listEffect = () => {
+      TestPersistence.listEffect = undefined
       TestPersistence.set({ meta: added, events: messageEvents('added needle') })
     }
 
     const page = await ctx.sessionQuery.searchSessions({ query: 'needle' })
     expect(page.items.map(item => item.header.id).sort()).toEqual([added.id, first.id].sort())
-    expect(TestPersistence.inspections.get(first.id)).toBe(2)
-    expect(TestPersistence.inspections.get(added.id)).toBe(1)
+    expect(TestPersistence.reads.get(first.id)).toBe(2)
+    expect(TestPersistence.reads.get(added.id)).toBe(1)
   })
 
   it('fails after one retry when persistence snapshots keep changing', async () => {
@@ -1085,7 +1029,7 @@ describe('SQLite reconciliation and source lifecycle', () => {
     const ctx = await liveContext()
     await ctx.plugin(TestPersistence)
     let lists = 0
-    TestPersistence.snapshotEffect = () => {
+    TestPersistence.listEffect = () => {
       lists += 1
       TestPersistence.set({ meta: durable, events: messageEvents(`durable needle ${lists}`) })
     }
@@ -1118,7 +1062,7 @@ describe('SQLite reconciliation and source lifecycle', () => {
 
     await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
       .resolves.toMatchObject({ items: [{ header: durable }] })
-    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    expect(TestPersistence.reads.get(durable.id)).toBe(2)
     list.mockRestore()
   })
 
@@ -1128,20 +1072,20 @@ describe('SQLite reconciliation and source lifecycle', () => {
     const ctx = await liveContext()
     await ctx.plugin(TestPersistence)
 
-    TestPersistence.snapshotOverride = () => 'not-an-array' as never
+    TestPersistence.listOverride = () => 'not-an-array' as never
     await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
-    TestPersistence.snapshotOverride = () => [{ header: durable, revision: 1 as never }]
+    TestPersistence.listOverride = () => [{ header: durable, revision: 1 as never }]
     await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
-    TestPersistence.snapshotOverride = () => [
+    TestPersistence.listOverride = () => [
       { header: durable, revision: SessionPersistenceRevision('duplicate:1') },
       { header: durable, revision: SessionPersistenceRevision('duplicate:2') },
     ]
     await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
 
-    TestPersistence.snapshotOverride = undefined
+    TestPersistence.listOverride = undefined
     const typed = new SessionQueryError('typed persistence failure', 'SESSION_QUERY_PERSISTENCE_FAILED')
     TestPersistence.failure = typed
     await expect(ctx.sessionQuery.searchSessions({ query: 'needle' })).rejects.toBe(typed)
@@ -1177,9 +1121,9 @@ describe('SQLite reconciliation and source lifecycle', () => {
     const firstPersistence = await first.plugin(TestPersistence)
     const firstSearch = await first.plugin(SqliteSessionQueryEngine, { path })
     await first.sessionQuery.searchSessions({ query: 'needle' })
-    expect(Object.fromEntries(TestPersistence.inspections)).toEqual({ unchanged: 1, changed: 1, deleted: 1 })
+    expect(Object.fromEntries(TestPersistence.reads)).toEqual({ unchanged: 1, changed: 1, deleted: 1 })
     await first.sessionQuery.searchSessions({ query: 'needle' })
-    expect(Object.fromEntries(TestPersistence.inspections)).toEqual({ unchanged: 1, changed: 1, deleted: 1 })
+    expect(Object.fromEntries(TestPersistence.reads)).toEqual({ unchanged: 1, changed: 1, deleted: 1 })
     await firstSearch.dispose()
     await firstPersistence.dispose()
 
@@ -1199,7 +1143,7 @@ describe('SQLite reconciliation and source lifecycle', () => {
     const secondSearch = await second.plugin(SqliteSessionQueryEngine, { path })
     const result = await second.sessionQuery.searchSessions({ query: 'needle' })
     expect(result.items.map(item => item.header.id).sort()).toEqual([added.id, changed.id, unchanged.id].sort())
-    expect(Object.fromEntries(TestPersistence.inspections)).toEqual({
+    expect(Object.fromEntries(TestPersistence.reads)).toEqual({
       unchanged: 1,
       changed: 2,
       deleted: 1,
@@ -1240,29 +1184,27 @@ describe('SQLite reconciliation and source lifecycle', () => {
     await expect(second.sessionQuery.searchSessions({ query: 'live' })).resolves.toEqual({ items: [] })
     await expect(second.sessionQuery.searchSessions({ query: 'persisted' }))
       .resolves.toMatchObject({ items: [{ header: shared, live: false, persisted: true }] })
-    expect(TestPersistence.inspections.get(shared.id)).toBe(1)
+    expect(TestPersistence.reads.get(shared.id)).toBe(1)
     await searchAgain.dispose()
     await persistenceAgain.dispose()
   })
 
-  it('refreshes after an external mutating load repair without loading from the query path', async () => {
+  it('refreshes after an external writer replaces a stored log, then reuses the new revision', async () => {
     const durable = header('repair')
     TestPersistence.reset([{ meta: durable, events: messageEvents('before repair') }])
     const ctx = await liveContext()
     const persistence = await ctx.plugin(TestPersistence)
     await expect(ctx.sessionQuery.searchSessions({ query: 'before' }))
       .resolves.toMatchObject({ items: [{ header: durable }] })
-    TestPersistence.loadEffect = (entry) => {
-      entry.events = messageEvents('repaired needle')
-    }
-    await ctx.sessionPersistence.load(durable.id)
+    // An external writer (resume-time torn-tail repair, or another append)
+    // replaces the stored log and moves its revision.
+    TestPersistence.set({ meta: durable, events: messageEvents('repaired needle') })
 
     await expect(ctx.sessionQuery.searchSessions({ query: 'repaired' }))
       .resolves.toMatchObject({ items: [{ header: durable }] })
-    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    expect(TestPersistence.reads.get(durable.id)).toBe(2)
     await ctx.sessionQuery.searchSessions({ query: 'repaired' })
-    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
-    expect(TestPersistence.loads.get(durable.id)).toBe(1)
+    expect(TestPersistence.reads.get(durable.id)).toBe(2)
     await persistence.dispose()
   })
 
@@ -1294,7 +1236,7 @@ describe('SQLite reconciliation and source lifecycle', () => {
     db.exec('PRAGMA query_only = OFF')
     // seq 2: one-event seed, end-seed, then the live message.
     await expect(ctx.sessionQuery.searchEvents({ sessionId: live.id, query: 'needle' }))
-      .resolves.toMatchObject({ items: [{ seq: 2 }] })
+      .resolves.toMatchObject({ items: [{ seq: SessionSeq(2) }] })
   })
 })
 
@@ -1524,8 +1466,8 @@ describe('SQLite schema, cancellation, and real persistence integration', () =>
         )
 
       expect(result.items).toHaveLength(1)
-      expect(TestPersistence.snapshotSignals).toEqual([controller.signal, controller.signal])
-      expect(TestPersistence.inspectSignals).toEqual([controller.signal])
+      expect(TestPersistence.listSignals).toEqual([controller.signal, controller.signal])
+      expect(TestPersistence.readSignals).toEqual([controller.signal])
     },
   )
 
@@ -1547,8 +1489,8 @@ describe('SQLite schema, cancellation, and real persistence integration', () =>
         )
 
       await expect(pending).rejects.toThrow(expectCode('SESSION_QUERY_ABORTED'))
-      expect(TestPersistence.snapshotSignals).toEqual([])
-      expect(TestPersistence.inspectSignals).toEqual([])
+      expect(TestPersistence.listSignals).toEqual([])
+      expect(TestPersistence.readSignals).toEqual([])
     },
   )
 
@@ -1560,8 +1502,8 @@ describe('SQLite schema, cancellation, and real persistence integration', () =>
     const started = Promise.withResolvers<AbortSignal>()
     const abortObserved = Promise.withResolvers<undefined>()
     const cleanup = Promise.withResolvers<undefined>()
-    TestPersistence.snapshotEffect = async (signal) => {
-      TestPersistence.snapshotEffect = undefined
+    TestPersistence.listEffect = async (signal) => {
+      TestPersistence.listEffect = undefined
       if (signal === undefined) throw new Error('expected reconciliation signal')
       started.resolve(signal)
       await new Promise<void>((resolve) => {
@@ -1583,8 +1525,8 @@ describe('SQLite schema, cancellation, and real persistence integration', () =>
     controller.abort(new Error('cooperative list cancellation'))
     await abortObserved.promise
     expect(settled).toBe(false)
-    expect(TestPersistence.snapshotSignals).toEqual([controller.signal])
-    expect(TestPersistence.inspectSignals).toEqual([])
+    expect(TestPersistence.listSignals).toEqual([controller.signal])
+    expect(TestPersistence.readSignals).toEqual([])
 
     cleanup.resolve(undefined)
     await expect(pending).rejects.toThrow(expectCode('SESSION_QUERY_ABORTED'))
@@ -1621,8 +1563,8 @@ describe('SQLite schema, cancellation, and real persistence integration', () =>
 
     expect(firstSettled).toBe(false)
     expect(secondSettled).toBe(false)
-    expect(TestPersistence.snapshotSignals).toEqual([controller.signal])
-    expect(TestPersistence.inspectSignals).toEqual([])
+    expect(TestPersistence.listSignals).toEqual([controller.signal])
+    expect(TestPersistence.readSignals).toEqual([])
 
     cleanup.resolve(undefined)
     await expect(first).rejects.toThrow(expectCode('SESSION_QUERY_ABORTED'))
@@ -1640,8 +1582,8 @@ describe('SQLite schema, cancellation, and real persistence integration', () =>
     await ctx.plugin(TestPersistence)
     const started = Promise.withResolvers<AbortSignal>()
     const cleanup = Promise.withResolvers<undefined>()
-    TestPersistence.inspectEffect = async (_entry, signal) => {
-      TestPersistence.inspectEffect = undefined
+    TestPersistence.readEffect = async (_entry, signal) => {
+      TestPersistence.readEffect = undefined
       if (signal === undefined) throw new Error('expected reconciliation signal')
       started.resolve(signal)
       await cleanup.promise
@@ -1658,14 +1600,14 @@ describe('SQLite schema, cancellation, and real persistence integration', () =>
     controller.abort(new Error('ignored inspect cancellation'))
     await Promise.resolve()
     expect(settled).toBe(false)
-    expect(TestPersistence.snapshotSignals).toEqual([controller.signal])
-    expect(TestPersistence.inspections.get(first.id)).toBe(1)
-    expect(TestPersistence.inspections.get(second.id)).toBeUndefined()
+    expect(TestPersistence.listSignals).toEqual([controller.signal])
+    expect(TestPersistence.reads.get(first.id)).toBe(1)
+    expect(TestPersistence.reads.get(second.id)).toBeUndefined()
 
     cleanup.resolve(undefined)
     await expect(pending).rejects.toThrow(expectCode('SESSION_QUERY_ABORTED'))
-    expect(TestPersistence.snapshotSignals).toEqual([controller.signal])
-    expect(TestPersistence.inspections.get(second.id)).toBeUndefined()
+    expect(TestPersistence.listSignals).toEqual([controller.signal])
+    expect(TestPersistence.reads.get(second.id)).toBeUndefined()
   })
 
   it('cancels both queued and in-flight source waits without committing them', async () => {
@@ -1840,85 +1782,80 @@ describe('SQLite schema, cancellation, and real persistence integration', () =>
     await persistence.dispose()
   })
 
-  it('combines the real JSONL persistence backend with the real SQLite search service keylessly', async () => {
-    const persistenceRoot = await temporaryPath('canonical')
+  it('combines the real JSONL persistence backend with the real search service keylessly', async () => {
+    const persistenceRoot = await temporaryPath('sessions')
     const searchPath = await temporaryPath('derived.db')
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     await ctx.plugin(SessionProjectionRegistry)
-    const persistence = await ctx.plugin(JsonlSessionPersistence, {
-      root: persistenceRoot,
-      compression: 'none',
-    })
+    const persistence = await ctx.plugin(JsonlSessionPersistence, { root: persistenceRoot, compression: 'none' })
     const search = await ctx.plugin(SqliteSessionQueryEngine, { path: searchPath })
     const meta = header('real', 10, { cwd: '/work' })
-    await ctx.sessionPersistence.create(meta)
-    await ctx.sessionPersistence.append(meta.id, messageEvents('real search needle'))
+    const writer = await ctx.sessionPersistence.create(meta)
+    await writer.append(messageEvents('real JSONL needle'))
+    await writer.close()
 
-    await expect(ctx.sessionQuery.searchSessions({ query: 'search needle' }))
+    await expect(ctx.sessionQuery.searchSessions({ query: 'JSONL needle' }))
       .resolves.toMatchObject({ items: [{ header: meta, persisted: true, live: false }] })
-    await expect(ctx.sessionQuery.searchEvents({ sessionId: meta.id, query: 'search needle' }))
-      .resolves.toMatchObject({ session: meta, items: [{ sessionId: meta.id, seq: 0 }] })
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: meta.id, query: 'JSONL needle' }))
+      .resolves.toMatchObject({ session: meta, items: [{ sessionId: meta.id, seq: SessionSeq(0) }] })
     await expect(ctx.sessionQuery.searchEvents({ sessionId: SessionId('absent'), query: 'needle' }))
       .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
     await search.dispose()
-    await expect(ctx.sessionPersistence.load(meta.id)).resolves.toMatchObject({ meta, events: [{ seq: 0 }] })
+    const reader = await ctx.sessionPersistence.open(meta.id, 'read')
+    expect(reader.header).toMatchObject(meta)
+    await expect(reader.read()).resolves.toMatchObject([{ seq: SessionSeq(0) }])
+    await reader.close()
     await persistence.dispose()
   })
 
-  it('reconciles colliding local revisions when a derived index reopens against another JSONL store', async () => {
-    const persistenceRootA = await temporaryPath('canonical-a')
-    const persistenceRootB = await temporaryPath('canonical-b')
+  it('reconciles a reopened derived index: unchanged revisions skip reads, another store reloads', async () => {
+    const persistenceRootA = await temporaryPath('sessions-a')
+    const persistenceRootB = await temporaryPath('sessions-b')
     const searchPath = await temporaryPath('derived-collision.db')
     const shared = header('same-id', 10)
+    const storeSession = async (ctx: Context, events: SessionEvent[]): Promise<void> => {
+      const writer = await ctx.sessionPersistence.create(shared)
+      await writer.append(events)
+      await writer.close()
+    }
 
     const first = new Context()
     await first.plugin(SessionStore)
     await first.plugin(SessionProjectionRegistry)
-    const persistenceA = await first.plugin(JsonlSessionPersistence, {
-      root: persistenceRootA,
-      compression: 'none',
-    })
-    await first.sessionPersistence.create(shared)
-    await first.sessionPersistence.append(shared.id, messageEvents('alpha source'))
-    const inspectA = vi.spyOn(first.sessionPersistence, 'inspect')
+    const persistenceA = await first.plugin(JsonlSessionPersistence, { root: persistenceRootA, compression: 'none' })
+    await storeSession(first, messageEvents('alpha source'))
+    const openA = vi.spyOn(first.sessionPersistence, 'open')
     const searchA = await first.plugin(SqliteSessionQueryEngine, { path: searchPath })
     await expect(first.sessionQuery.searchSessions({ query: 'alpha' }))
       .resolves.toMatchObject({ items: [{ header: shared }] })
-    expect(inspectA).toHaveBeenCalledTimes(1)
+    expect(openA).toHaveBeenCalledTimes(1)
     await searchA.dispose()
     await persistenceA.dispose()
 
     const reopened = new Context()
     await reopened.plugin(SessionStore)
     await reopened.plugin(SessionProjectionRegistry)
-    const persistenceAAgain = await reopened.plugin(JsonlSessionPersistence, {
-      root: persistenceRootA,
-      compression: 'none',
-    })
-    const reopenedInspect = vi.spyOn(reopened.sessionPersistence, 'inspect')
+    const persistenceAAgain = await reopened.plugin(JsonlSessionPersistence, { root: persistenceRootA, compression: 'none' })
+    const reopenedOpen = vi.spyOn(reopened.sessionPersistence, 'open')
     const searchAAgain = await reopened.plugin(SqliteSessionQueryEngine, { path: searchPath })
     await expect(reopened.sessionQuery.searchSessions({ query: 'alpha' }))
       .resolves.toMatchObject({ items: [{ header: shared }] })
-    expect(reopenedInspect).not.toHaveBeenCalled()
+    expect(reopenedOpen).not.toHaveBeenCalled()
     await searchAAgain.dispose()
     await persistenceAAgain.dispose()
 
     const second = new Context()
     await second.plugin(SessionStore)
     await second.plugin(SessionProjectionRegistry)
-    const persistenceB = await second.plugin(JsonlSessionPersistence, {
-      root: persistenceRootB,
-      compression: 'none',
-    })
-    await second.sessionPersistence.create(shared)
-    await second.sessionPersistence.append(shared.id, messageEvents('bravo source'))
-    const inspectB = vi.spyOn(second.sessionPersistence, 'inspect')
+    const persistenceB = await second.plugin(JsonlSessionPersistence, { root: persistenceRootB, compression: 'none' })
+    await storeSession(second, messageEvents('bravo source'))
+    const openB = vi.spyOn(second.sessionPersistence, 'open')
     const searchB = await second.plugin(SqliteSessionQueryEngine, { path: searchPath })
     await expect(second.sessionQuery.searchSessions({ query: 'bravo' }))
       .resolves.toMatchObject({ items: [{ header: shared }] })
     await expect(second.sessionQuery.searchSessions({ query: 'alpha' })).resolves.toEqual({ items: [] })
-    expect(inspectB).toHaveBeenCalledTimes(1)
+    expect(openB).toHaveBeenCalledTimes(1)
     await searchB.dispose()
     await persistenceB.dispose()
   })
diff --git a/packages/session-query/session-query/README.i18n.yaml b/packages/session-query/session-query/README.i18n.yaml
index c6092ee220..7ad7fd3980 100644
--- a/packages/session-query/session-query/README.i18n.yaml
+++ b/packages/session-query/session-query/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/session-query/session-query/README.md
-README.md: 549ec7344d53a09e82568be4d1a21778367c38cc
-README.zh.md: d2161b9528306ead31d709c4d4f6fab20feec8fd
+README.md: bd078a69357d8b2f77d70411925ff37bf85ac642
+README.zh.md: d848899789e6c843575c09829f7e119d0ff03bdf
diff --git a/packages/session-query/session-query/README.md b/packages/session-query/session-query/README.md
index 549ec7344d..bd078a6935 100644
--- a/packages/session-query/session-query/README.md
+++ b/packages/session-query/session-query/README.md
@@ -52,12 +52,13 @@ The text clause is a literal, case-insensitive, whitespace-flexible scan of extr
 
 ### Configuration
 
-The two inherited knobs are set through the mounted backend's config:
+The inherited knobs are set through the mounted backend's config:
 
 | Field | Default | Meaning |
 |---|---|---|
 | `readWindowMax` | `50` | Maximum `before`/`after` raw events accepted by `readEvent` |
-| `persistedInspectConcurrency` | `4` | Concurrent persisted-log inspections in one batch title read |
+| `persistedReadConcurrency` | `4` | Concurrent persisted-log reads in one batch title read |
+| `preparedSessionCacheSize` | `5` | Cold prepared-Session observations retained for reuse across `observeSession` reads |
 
 ### Failures and recovery
 
@@ -90,6 +91,8 @@ The decision history lives in the [unified service decision](../../../.agents/no
 |---|---|
 | [`src/index.ts`](src/index.ts) | Service definition: the abstract `SessionQueryEngine`, concrete reads, config validation |
 | [`src/corpus.ts`](src/corpus.ts) | Live-preferred corpus resolution, optional persistence binding, batch projections |
+| [`src/observation.ts`](src/observation.ts) | Live-preferred point observations with a bounded revision-keyed prepared-Session cache |
+| [`src/cold-read.ts`](src/cold-read.ts) | Handle-based cold log read with in-memory interrupted-turn closers |
 | [`src/types.ts`](src/types.ts) | Public records, filters, requests, and page types |
 | [`src/config.ts`](src/config.ts) | Inherited config and the closed `SessionQueryError` taxonomy |
 | [`src/filters.ts`](src/filters.ts) | Provider-independent predicates and the literal text scan |
@@ -101,7 +104,11 @@ The decision history lives in the [unified service decision](../../../.agents/no
 
 ### Corpus resolution
 
-`SessionCorpus` binds optional `ctx.sessionPersistence` through a fiber and resolves each read live-first: a known live target is snapshotted without consulting persistence; otherwise the session is listed, inspected non-mutatingly, and re-checked for a live attachment before cloning. Header compatibility is asserted between listed and loaded observations. Batch title reads run one metadata listing and bounded-concurrency inspections, isolating per-session failures while cancellation rejects the whole batch.
+`SessionCorpus` binds optional `ctx.sessionPersistence` through a fiber and resolves each read live-first: a known live target is snapshotted without consulting persistence; otherwise the session is listed, read completely through a short-lived read handle, and re-checked for a live attachment before cloning. A cold log whose writer crashed mid-turn is balanced in memory with `interruptedTurnClosers` — persistence is never mutated by a read. Header compatibility is asserted between listed and loaded observations. Batch title reads run one metadata listing and bounded-concurrency reads, isolating per-session failures while cancellation rejects the whole batch.
+
+### Observation cache
+
+`observeSession` builds point observations without a listing preflight. The cold path stats the stored session first and consults an own bounded cache keyed by the persistence instance and the `stat` revision: an unchanged revision reuses the restored unpublished Session without re-reading the log; a changed revision, or a replaced persistence instance, reloads through the handle seam and replaces the entry. The cache holds `preparedSessionCacheSize` entries with least-recently-used eviction, entries pinned by active observation leases are never evicted, and a session that goes live mid-read retries the live path.
 
 ### Reads and traces
 
diff --git a/packages/session-query/session-query/README.zh.md b/packages/session-query/session-query/README.zh.md
index d2161b9528..d848899789 100644
--- a/packages/session-query/session-query/README.zh.md
+++ b/packages/session-query/session-query/README.zh.md
@@ -52,12 +52,13 @@ kind: "package-reference"
 
 ### 配置
 
-两个继承的旋钮通过挂载后端的配置设置：
+继承的旋钮通过挂载后端的配置设置：
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
 | `readWindowMax` | `50` | `readEvent` 接受的 `before`/`after` 原始事件数上限 |
-| `persistedInspectConcurrency` | `4` | 一次批量标题读取中的并发持久化日志检查数 |
+| `persistedReadConcurrency` | `4` | 一次批量标题读取中的并发持久化日志读取数 |
+| `preparedSessionCacheSize` | `5` | 为跨 `observeSession` 读取复用而保留的冷 prepared-Session 观察数 |
 
 ### 失败与恢复
 
@@ -90,6 +91,8 @@ kind: "package-reference"
 |---|---|
 | [`src/index.ts`](src/index.ts) | 服务定义：抽象 `SessionQueryEngine`、具体读取、配置校验 |
 | [`src/corpus.ts`](src/corpus.ts) | 实时优先的语料库解析、可选持久化绑定、批量投影 |
+| [`src/observation.ts`](src/observation.ts) | 实时优先的定点观察，带按修订键控的有界 prepared-Session 缓存 |
+| [`src/cold-read.ts`](src/cold-read.ts) | 基于 handle 的冷日志读取，附内存中的中断轮次闭合事件 |
 | [`src/types.ts`](src/types.ts) | 公共记录、过滤器、请求与分页类型 |
 | [`src/config.ts`](src/config.ts) | 继承配置与封闭的 `SessionQueryError` 分类体系 |
 | [`src/filters.ts`](src/filters.ts) | 提供方无关谓词与字面文本扫描 |
@@ -101,7 +104,11 @@ kind: "package-reference"
 
 ### 语料库解析
 
-`SessionCorpus` 通过 fiber 绑定可选的 `ctx.sessionPersistence`，并实时优先解析每次读取：已知实时目标直接快照，不查询持久化；否则先列出会话，再以不修改日志的方式检查，并在克隆前重新检查是否出现实时挂载。列表与加载观察之间会断言 header 兼容性。批量标题读取执行一次元数据列表与有界并发检查，把逐会话失败隔离，而取消会拒绝整个批次。
+`SessionCorpus` 通过 fiber 绑定可选的 `ctx.sessionPersistence`，并实时优先解析每次读取：已知实时目标直接快照，不查询持久化；否则先列出会话，再通过短生命周期的读取 handle 完整读出日志，并在克隆前重新检查是否出现实时挂载。写入者在轮次中途崩溃的冷日志用 `interruptedTurnClosers` 在内存中补齐 —— 读取从不修改持久化。列表与加载观察之间会断言 header 兼容性。批量标题读取执行一次元数据列表与有界并发读取，把逐会话失败隔离，而取消会拒绝整个批次。
+
+### 观察缓存
+
+`observeSession` 不经过列表预检直接构建定点观察。冷路径先对存储会话执行 `stat`，再查询自有的有界缓存，缓存键为持久化实例加 `stat` 修订：修订未变则复用已恢复的未发布 Session，不再重读日志；修订变化或持久化实例被替换则经 handle 缝重新加载并替换条目。缓存保留 `preparedSessionCacheSize` 个条目并按最久未用淘汰，被活跃观察租约钉住的条目从不被淘汰；读取中途转为实时的会话会重试实时路径。
 
 ### 读取与追踪
 
diff --git a/packages/session-query/session-query/src/cold-read.ts b/packages/session-query/session-query/src/cold-read.ts
new file mode 100644
index 0000000000..1732091d9b
--- /dev/null
+++ b/packages/session-query/session-query/src/cold-read.ts
@@ -0,0 +1,48 @@
+/** One-shot cold session read through the handle-based persistence seam. */
+
+import { interruptedTurnClosers } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
+
+/** A stored session log balanced for read-only viewing. */
+export interface ColdSessionLog {
+  /** The stored header, fixed when the read handle opened. */
+  readonly header: SessionHeader
+  /** Exact fork-inherited event count paired with {@link header}. */
+  readonly inheritedEventCount: SessionLogOffset
+  /** Stored events plus deterministic in-memory closers for an interrupted final turn; nothing is written back. */
+  readonly events: SessionEvent[]
+}
+
+/**
+ * Read one complete stored session log without taking ownership or mutating
+ * storage: open a read handle, read the validated contiguous log, close the
+ * handle, and append `interruptedTurnClosers` so a log whose writer crashed
+ * mid-turn folds as a balanced transcript. Backend failures propagate
+ * unmapped — each caller owns its error taxonomy.
+ * @param persistence - the mounted persistence service.
+ * @param sessionId - the stored session to read.
+ * @param signal - optional cancellation for the open and read work.
+ * @returns the stored header and the balanced event log.
+ */
+export async function readColdSessionLog(
+  persistence: SessionPersistence,
+  sessionId: SessionId,
+  signal?: AbortSignal,
+): Promise<ColdSessionLog> {
+  const options = signal === undefined ? undefined : { signal }
+  const handle = await persistence.open(sessionId, 'read', options)
+  let events: readonly SessionEvent[]
+  try {
+    events = await handle.read(0, undefined, options)
+  } catch (error: unknown) {
+    try {
+      await handle.close()
+    } catch {
+      // The read failure is the actionable cause; a close failure on the same broken handle adds nothing.
+    }
+    throw error
+  }
+  await handle.close()
+  return { header: handle.header, inheritedEventCount: handle.inheritedEventCount, events: [...events, ...interruptedTurnClosers(events)] }
+}
diff --git a/packages/session-query/session-query/src/config.ts b/packages/session-query/session-query/src/config.ts
index 99039bcbfa..e5475e3df6 100644
--- a/packages/session-query/session-query/src/config.ts
+++ b/packages/session-query/session-query/src/config.ts
@@ -5,15 +5,24 @@ import { HarnessError } from '@deepseek-ai/dsh-llm'
 /** Default maximum `before`/`after` raw-event window. */
 export const SESSION_QUERY_READ_WINDOW_MAX = 50
 
-/** Default maximum number of concurrent persisted-log inspections in one batch read. */
+/** Default maximum number of concurrent persisted-log reads in one batch read. */
 export const SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY = 4
 
+/** Default maximum number of cold prepared-Session observations retained for reuse. */
+export const SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE = 5
+
 /** Backend-independent configuration inherited by every session-query implementation. */
 export interface Config {
   /** Maximum accepted raw read context on either side. Defaults to 50. */
   readWindowMax?: number
-  /** Maximum concurrent persisted-log inspections in one batch read. Defaults to 4. */
-  persistedInspectConcurrency?: number
+  /** Maximum concurrent persisted-log reads in one batch read. Defaults to 4. */
+  persistedReadConcurrency?: number
+  /**
+   * Maximum cold prepared-Session observations retained for reuse, keyed by
+   * durable revision. Entries pinned by active observation leases do not count
+   * against this bound until released. Defaults to 5.
+   */
+  preparedSessionCacheSize?: number
 }
 
 /** Stable machine-routable failure taxonomy for session reads, traces, and search. */
diff --git a/packages/session-query/session-query/src/corpus.ts b/packages/session-query/session-query/src/corpus.ts
index a9746b1793..a6e44c85ad 100644
--- a/packages/session-query/session-query/src/corpus.ts
+++ b/packages/session-query/session-query/src/corpus.ts
@@ -1,16 +1,11 @@
 /** Live/persisted logical-corpus resolution for session-query. */
 
 import type { Context, Fiber } from '@deepseek-ai/cordis'
-import type {
-  Session,
-  SessionEvent,
-  SessionHeader,
-  SessionId,
-  SessionLogOffset,
-} from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionHeader, SessionId , SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
 import type { SessionRecord } from './types.ts'
 import { SessionQueryError } from './config.ts'
+import { readColdSessionLog, type ColdSessionLog } from './cold-read.ts'
 import { assertSessionHeadersCompatible } from './sources.ts'
 
 /** Detached source selected for one exact read. */
@@ -27,8 +22,6 @@ export interface LogicalSession {
 export interface LogicalSessionSource {
   /** Header selected with `events`; callers must clone retained output. */
   readonly header: SessionHeader
-  /** Exact fork-inherited event count paired with {@link header}. */
-  readonly inheritedEventCount: SessionLogOffset
   /** Raw events selected with `header`; valid only for the projection call. */
   readonly events: readonly SessionEvent[]
 }
@@ -45,7 +38,7 @@ export class SessionCorpus {
 
   constructor(
     private readonly _ctx: Context,
-    private readonly _persistedInspectConcurrency: number,
+    private readonly _persistedReadConcurrency: number,
   ) {
     this._optionalPersistenceFiber = _ctx.inject(['sessionPersistence'], (childCtx: Context) => {
       const service = childCtx.sessionPersistence
@@ -116,9 +109,9 @@ export class SessionCorpus {
       signal?.throwIfAborted()
       return snapshot
     }
-    assertSessionHeadersCompatible(loaded.meta, listed)
+    assertSessionHeadersCompatible(loaded.header, listed)
     const snapshot = {
-      header: structuredClone(loaded.meta),
+      header: structuredClone(loaded.header),
       inheritedEventCount: loaded.inheritedEventCount,
       events: loaded.events.map(event => structuredClone(event)),
     }
@@ -193,10 +186,9 @@ export class SessionCorpus {
           resolved.set(sessionId, projectSource(sessionId, sourceLive(attached), project, signal))
           return
         }
-        assertSessionHeadersCompatible(loaded.meta, listed)
+        assertSessionHeadersCompatible(loaded.header, listed)
         resolved.set(sessionId, projectSource(sessionId, {
-          header: loaded.meta,
-          inheritedEventCount: loaded.inheritedEventCount,
+          header: loaded.header,
           events: loaded.events,
         }, project, signal))
       } catch (error: unknown) {
@@ -214,7 +206,7 @@ export class SessionCorpus {
         await resolvePersisted(unresolved[index] as SessionId)
       }
     }
-    const workerCount = Math.min(this._persistedInspectConcurrency, unresolved.length)
+    const workerCount = Math.min(this._persistedReadConcurrency, unresolved.length)
     const settlements = await Promise.allSettled(
       Array.from({ length: workerCount }, () => worker()),
     )
@@ -251,11 +243,7 @@ function projectSource<Value>(
 }
 
 function sourceLive(session: Session): LogicalSessionSource {
-  return {
-    header: session.header,
-    inheritedEventCount: session.inheritedEventCount,
-    events: session.snapshotEvents(),
-  }
+  return { header: session.header, events: session.snapshotEvents() }
 }
 
 function orderedResults<Value>(
@@ -270,7 +258,8 @@ async function listPersisted(
   signal?: AbortSignal,
 ): Promise<SessionHeader[]> {
   try {
-    return await persistence.list(signal)
+    const snapshots = await persistence.list(signal === undefined ? undefined : { signal })
+    return snapshots.map(snapshot => snapshot.header)
   } catch (error: unknown) {
     if (signal?.aborted) signal.throwIfAborted()
     throw new SessionQueryError(
@@ -285,9 +274,9 @@ async function inspectPersisted(
   persistence: SessionPersistence,
   sessionId: SessionId,
   signal?: AbortSignal,
-): Promise<Awaited<ReturnType<SessionPersistence['inspect']>>> {
+): Promise<ColdSessionLog> {
   try {
-    return await persistence.inspect(sessionId, signal)
+    return await readColdSessionLog(persistence, sessionId, signal)
   } catch (error: unknown) {
     if (signal?.aborted) signal.throwIfAborted()
     if (error instanceof Error && error.name === 'SessionPersistenceCorruptionError') {
@@ -298,7 +287,7 @@ async function inspectPersisted(
       )
     }
     throw new SessionQueryError(
-      `failed to inspect session "${sessionId}": ${errorMessage(error)}`,
+      `failed to read stored session "${sessionId}": ${errorMessage(error)}`,
       'SESSION_QUERY_PERSISTENCE_FAILED',
       { cause: error },
     )
diff --git a/packages/session-query/session-query/src/index.ts b/packages/session-query/session-query/src/index.ts
index 8d533f66c9..44360042e9 100644
--- a/packages/session-query/session-query/src/index.ts
+++ b/packages/session-query/session-query/src/index.ts
@@ -38,6 +38,7 @@ import type {
 } from './types.ts'
 import {
   SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
+  SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE,
   SESSION_QUERY_READ_WINDOW_MAX,
   SessionQueryError,
   type Config,
@@ -62,9 +63,12 @@ export { SessionSearchCursor } from './cursor.ts'
 export type { Config, SessionQueryErrorCode } from './config.ts'
 export {
   SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
+  SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE,
   SESSION_QUERY_READ_WINDOW_MAX,
   SessionQueryError,
 } from './config.ts'
+export { readColdSessionLog } from './cold-read.ts'
+export type { ColdSessionLog } from './cold-read.ts'
 export { extractSessionEventText } from './extraction.ts'
 export { buildSessionEventRecords, buildSessionEventSearchDocuments } from './documents.ts'
 export {
@@ -106,16 +110,24 @@ export abstract class SessionQueryEngine extends Service {
         'SESSION_QUERY_INVALID_CONFIG',
       )
     }
-    const persistedInspectConcurrency = config.persistedInspectConcurrency
+    const persistedReadConcurrency = config.persistedReadConcurrency
       ?? SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY
-    if (!Number.isSafeInteger(persistedInspectConcurrency) || persistedInspectConcurrency < 1) {
+    if (!Number.isSafeInteger(persistedReadConcurrency) || persistedReadConcurrency < 1) {
       throw new SessionQueryError(
-        'session-query: persistedInspectConcurrency must be a positive safe integer',
+        'session-query: persistedReadConcurrency must be a positive safe integer',
         'SESSION_QUERY_INVALID_CONFIG',
       )
     }
-    this._corpus = new SessionCorpus(ctx, persistedInspectConcurrency)
-    this._observations = new SessionObservationReader(ctx)
+    const preparedSessionCacheSize = config.preparedSessionCacheSize
+      ?? SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE
+    if (!Number.isSafeInteger(preparedSessionCacheSize) || preparedSessionCacheSize < 1) {
+      throw new SessionQueryError(
+        'session-query: preparedSessionCacheSize must be a positive safe integer',
+        'SESSION_QUERY_INVALID_CONFIG',
+      )
+    }
+    this._corpus = new SessionCorpus(ctx, persistedReadConcurrency)
+    this._observations = new SessionObservationReader(ctx, preparedSessionCacheSize)
   }
 
   /**
diff --git a/packages/session-query/session-query/src/observation.ts b/packages/session-query/session-query/src/observation.ts
index f2aebc9503..6ec40d3785 100644
--- a/packages/session-query/session-query/src/observation.ts
+++ b/packages/session-query/session-query/src/observation.ts
@@ -2,21 +2,16 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionHeader, SessionId , SessionLogOffset as SessionLogOffsetType , SessionSeqCursor } from '@deepseek-ai/dsh-session'
+import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
 import type {
-  Session,
-  SessionEvent,
-  SessionHeader,
-  SessionId,
-  SessionLogOffset as SessionLogOffsetType,
-  SessionSeqCursor,
-} from '@deepseek-ai/dsh-session'
-import type {
-  BorrowedSessionSource,
   SessionPersistenceRevision,
+  SessionPersistenceSnapshot,
 } from '@deepseek-ai/dsh-session-persistence'
 import type { ProjectionSnapshot } from '@deepseek-ai/dsh-session-projection'
 import type {} from '@deepseek-ai/dsh-session-projection-cache'
-import { SessionQueryError } from './config.ts'
+import { SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE, SessionQueryError } from './config.ts'
+import { readColdSessionLog, type ColdSessionLog } from './cold-read.ts'
 
 /** One exact immutable Session cut retained for the caller's read lifetime. */
 export interface SessionObservation extends Disposable {
@@ -24,10 +19,10 @@ export interface SessionObservation extends Disposable {
   readonly source: 'live' | 'prepared'
   /** Immutable Session identity metadata. */
   readonly header: SessionHeader
+  /** Exact fork-inherited event count paired with {@link header}. */
+  readonly inheritedEventCount: SessionLogOffsetType
   /** Immutable contiguous events at {@link cursor}. */
   readonly events: readonly SessionEvent[]
-  /** Exact number of fork-inherited events in this Session lifecycle. */
-  readonly inheritedEventCount: SessionLogOffsetType
   /** Last observed event seq, or -1 for an empty log. */
   readonly cursor: SessionSeqCursor
   /** Durable source revision for a cold prepared observation. */
@@ -49,10 +44,45 @@ export interface SessionObservationOptions {
   readonly projectionMode?: 'all' | 'none'
 }
 
-/** Builds point observations without a corpus listing preflight. */
+/**
+ * One reusable cold observation: an unpublished restored Session plus the
+ * exact balanced log it represents, valid while the producing persistence
+ * instance still reports the same revision.
+ */
+interface PreparedEntry {
+  /** The persistence instance whose `stat` produced {@link revision}; revisions from another instance are incomparable. */
+  readonly persistence: SessionPersistence
+  /** Durable revision observed by `stat` immediately before the log read. */
+  readonly revision: SessionPersistenceRevision
+  /** Unpublished Session restored from the balanced log; never entered into the store. */
+  readonly session: Session
+  /** Immutable balanced log (stored events plus in-memory interrupted-turn closers). */
+  readonly events: readonly SessionEvent[]
+  /** Active observation leases; a pinned entry (`refs > 0`) is never evicted. */
+  refs: number
+}
+
+/**
+ * Builds point observations without a corpus listing preflight.
+ *
+ * Cold reads are cached per session id, keyed by the persistence instance and
+ * the `stat` revision observed before the log read: an unchanged revision
+ * reuses the restored Session without re-reading the log. The cache is bounded
+ * (least-recently-used unpinned entries are evicted past the capacity), and
+ * entries pinned by active leases survive eviction and replacement — a lease's
+ * cut stays valid for the lease lifetime even after a newer revision lands.
+ */
 export class SessionObservationReader {
-  /** @param ctx - context carrying Session and optional persistence/projection services. */
-  constructor(private readonly ctx: Context) {}
+  private readonly cache = new Map<SessionId, PreparedEntry>()
+
+  /**
+   * @param ctx - context carrying Session and optional persistence/projection services.
+   * @param cacheCapacity - maximum unpinned cold observations retained for reuse.
+   */
+  constructor(
+    private readonly ctx: Context,
+    private readonly cacheCapacity: number = SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE,
+  ) {}
 
   /**
    * Observe one live-preferred Session and retain a cold preparation until disposal.
@@ -72,90 +102,169 @@ export class SessionObservationReader {
       const persistence = this.ctx.get('sessionPersistence')
       if (persistence === undefined) throw notFound(sessionId)
 
-      let borrowed: BorrowedSessionSource
-      try {
-        borrowed = await persistence.borrowSession(sessionId, signal)
-      } catch (error: unknown) {
+      const snapshot = await this.statSource(persistence, sessionId, signal)
+      const attachedDuringStat = this.ctx.sessions.get(sessionId)
+      if (attachedDuringStat !== undefined) return this.live(attachedDuringStat, projectionMode)
+      let entry = this.cachedEntry(persistence, sessionId, snapshot.revision)
+      if (entry === undefined) {
+        const loaded = await this.loadSource(persistence, sessionId, signal)
         throwIfObservationAborted(signal)
-        if (hasErrorName(error, 'SessionPersistenceNotFoundError')) throw notFound(sessionId, error)
-        if (hasErrorName(error, 'SessionPersistenceCorruptionError')) {
+        const attached = this.ctx.sessions.get(sessionId)
+        if (attached !== undefined) return this.live(attached, projectionMode)
+        // Ownership transfer into `prepare` freezes the seed in place, so the
+        // entry keeps its own detached copies of the just-read events.
+        const seed = loaded.events.map(event => structuredClone(event))
+        let session: Session
+        try {
+          session = this.ctx.sessions.prepare(sessionId, {
+            seed,
+            meta: structuredClone(loaded.header),
+            inheritedEventCount: loaded.inheritedEventCount,
+            seedSource: 'persistence',
+          })
+        } catch (error: unknown) {
+          // The store rejects an id with a live owner: that owner is the
+          // fresher source, so retry the live path. Any other rejection means
+          // the stored log failed restore validation.
+          if (this.ctx.sessions.get(sessionId) !== undefined) continue
           throw new SessionQueryError(
-            `stored session "${sessionId}" is corrupt: ${error.message}`,
+            `stored session "${sessionId}" is corrupt: ${errorMessage(error)}`,
             'SESSION_QUERY_CORRUPT_SESSION',
             { cause: error },
           )
         }
+        entry = {
+          persistence,
+          revision: snapshot.revision,
+          session,
+          events: Object.freeze(seed),
+          refs: 0,
+        }
+        this.store(sessionId, entry)
+      }
+
+      let projections: ProjectionSnapshot | undefined
+      try {
+        projections = projectionMode === 'none' ? undefined : this.preparedProjections(entry)
+      } catch (error: unknown) {
         throw new SessionQueryError(
-          `failed to observe session "${sessionId}": ${errorMessage(error)}`,
-          'SESSION_QUERY_PERSISTENCE_FAILED',
+          `failed to project session "${sessionId}": ${errorMessage(error)}`,
+          'SESSION_QUERY_CORRUPT_SESSION',
           { cause: error },
         )
       }
+      return this.preparedLease(sessionId, entry, projections)
+    }
+  }
 
-      try {
-        throwIfObservationAborted(signal)
-        if (borrowed.inspection.meta.id !== sessionId) {
-          throw new SessionQueryError(
-            `session persistence returned "${borrowed.inspection.meta.id}" for "${sessionId}"`,
-            'SESSION_QUERY_SOURCE_CONFLICT',
-          )
-        }
-        const attached = this.ctx.sessions.get(sessionId)
-        if (attached !== undefined) {
-          const liveObservation = this.live(attached, projectionMode)
-          borrowed[Symbol.dispose]()
-          return liveObservation
-        }
-        if (borrowed.source === 'live') {
-          // The live Session disappeared between persistence's race check and
-          // this read. Retry against its now-cold durable identity.
-          borrowed[Symbol.dispose]()
-          continue
-        }
-        const prepared = borrowed
-        const events = prepared.inspection.events
-        let projections: ProjectionSnapshot | undefined
-        try {
-          projections = projectionMode === 'none'
-            ? undefined
-            : this.preparedProjections(prepared, events)
-        } catch (error: unknown) {
-          throw new SessionQueryError(
-            `failed to project session "${sessionId}": ${errorMessage(error)}`,
-            'SESSION_QUERY_CORRUPT_SESSION',
-            { cause: error },
-          )
-        }
-        let references = 1
-        const lease = (): SessionObservation => {
-          let disposed = false
-          return {
-            source: 'prepared',
-            header: prepared.inspection.meta,
-            events,
-            inheritedEventCount: prepared.inspection.inheritedEventCount,
-            cursor: events.at(-1)?.seq ?? -1,
-            revision: prepared.revision,
-            ...projections === undefined ? {} : { projections },
-            retain: () => {
-              if (disposed || references === 0) throw new Error(`session observation "${sessionId}" is disposed`)
-              references += 1
-              return lease()
-            },
-            [Symbol.dispose]: () => {
-              if (disposed) return
-              disposed = true
-              references -= 1
-              if (references === 0) prepared[Symbol.dispose]()
-            },
-          }
-        }
-        return lease()
-      } catch (error: unknown) {
-        borrowed[Symbol.dispose]()
-        throw error
+  /** Observe the stored snapshot, mapping absence and backend failures to the query taxonomy. */
+  private async statSource(
+    persistence: SessionPersistence,
+    sessionId: SessionId,
+    signal: AbortSignal | undefined,
+  ): Promise<SessionPersistenceSnapshot> {
+    let snapshot: SessionPersistenceSnapshot | undefined
+    try {
+      snapshot = await persistence.stat(sessionId, signal === undefined ? undefined : { signal })
+    } catch (error: unknown) {
+      throwIfObservationAborted(signal)
+      throw mapPersistenceFailure(sessionId, error)
+    }
+    throwIfObservationAborted(signal)
+    if (snapshot === undefined) throw notFound(sessionId)
+    if (snapshot.header.id !== sessionId) {
+      throw new SessionQueryError(
+        `session persistence returned "${snapshot.header.id}" for "${sessionId}"`,
+        'SESSION_QUERY_SOURCE_CONFLICT',
+      )
+    }
+    return snapshot
+  }
+
+  /** Read the complete balanced cold log, mapping backend failures to the query taxonomy. */
+  private async loadSource(
+    persistence: SessionPersistence,
+    sessionId: SessionId,
+    signal: AbortSignal | undefined,
+  ): Promise<ColdSessionLog> {
+    try {
+      return await readColdSessionLog(persistence, sessionId, signal)
+    } catch (error: unknown) {
+      throwIfObservationAborted(signal)
+      throw mapPersistenceFailure(sessionId, error)
+    }
+  }
+
+  /** Return a still-valid cached entry and mark it most recently used. */
+  private cachedEntry(
+    persistence: SessionPersistence,
+    sessionId: SessionId,
+    revision: SessionPersistenceRevision,
+  ): PreparedEntry | undefined {
+    const cached = this.cache.get(sessionId)
+    if (cached === undefined || cached.persistence !== persistence || cached.revision !== revision) {
+      return undefined
+    }
+    this.cache.delete(sessionId)
+    this.cache.set(sessionId, cached)
+    return cached
+  }
+
+  /** Insert or replace the entry for one id, then evict past the capacity. */
+  private store(sessionId: SessionId, entry: PreparedEntry): void {
+    // Replacing a stale revision only drops the map's reference; live leases
+    // keep the old entry alive through their own references.
+    this.cache.delete(sessionId)
+    this.cache.set(sessionId, entry)
+    this.evictPastCapacity(entry)
+  }
+
+  /**
+   * Evict oldest unpinned entries until the cache fits its capacity again.
+   * Runs on store and whenever a lease release unpins an entry, so leases
+   * that pinned every candidate cannot leave the cache over budget for good.
+   * @param keep - the entry being stored, about to be leased; never evicted.
+   */
+  private evictPastCapacity(keep?: PreparedEntry): void {
+    if (this.cache.size <= this.cacheCapacity) return
+    for (const [id, candidate] of this.cache) {
+      if (candidate === keep || candidate.refs > 0) continue
+      this.cache.delete(id)
+      if (this.cache.size <= this.cacheCapacity) return
+    }
+  }
+
+  /** Build one disposable lease over a cached entry, pinning it until every lease releases. */
+  private preparedLease(
+    sessionId: SessionId,
+    entry: PreparedEntry,
+    projections: ProjectionSnapshot | undefined,
+  ): SessionObservation {
+    entry.refs += 1
+    const lease = (): SessionObservation => {
+      let disposed = false
+      return {
+        source: 'prepared',
+        header: entry.session.header,
+        inheritedEventCount: entry.session.inheritedEventCount,
+        events: entry.events,
+        cursor: entry.events.at(-1)?.seq ?? -1,
+        revision: entry.revision,
+        ...projections === undefined ? {} : { projections },
+        retain: () => {
+          if (disposed) throw new Error(`session observation "${sessionId}" is disposed`)
+          entry.refs += 1
+          return lease()
+        },
+        [Symbol.dispose]: () => {
+          if (disposed) return
+          disposed = true
+          entry.refs -= 1
+          if (entry.refs === 0) this.evictPastCapacity()
+        },
       }
     }
+    return lease()
   }
 
   private live(
@@ -171,8 +280,8 @@ export class SessionObservationReader {
       return {
         source: 'live',
         header: session.header,
-        events,
         inheritedEventCount: session.inheritedEventCount,
+        events,
         cursor: events.at(-1)?.seq ?? -1,
         ...projections === undefined ? {} : { projections },
         retain: () => {
@@ -185,17 +294,13 @@ export class SessionObservationReader {
     return lease()
   }
 
-  private preparedProjections(
-    observation: Extract<BorrowedSessionSource, { readonly source: 'prepared' }>,
-    events: readonly SessionEvent[],
-  ): ProjectionSnapshot | undefined {
+  private preparedProjections(entry: PreparedEntry): ProjectionSnapshot | undefined {
     const registry = this.ctx.get('sessionProjections')
     if (registry === undefined) return undefined
-    const prepared = observation.preparedSession
     const cache = this.ctx.get('sessionProjectionCache')
     return cache === undefined
-      ? registry.hydrate(prepared, {}, events, SessionLogOffset(0))
-      : cache.hydratePrepared(prepared, events)
+      ? registry.hydrate(entry.session, {}, entry.events, SessionLogOffset(0))
+      : cache.hydratePrepared(entry.session, entry.events)
   }
 }
 
@@ -208,6 +313,22 @@ function throwIfObservationAborted(signal: AbortSignal | undefined): void {
   )
 }
 
+function mapPersistenceFailure(sessionId: SessionId, error: unknown): SessionQueryError {
+  if (hasErrorName(error, 'SessionPersistenceNotFoundError')) return notFound(sessionId, error)
+  if (hasErrorName(error, 'SessionPersistenceCorruptionError')) {
+    return new SessionQueryError(
+      `stored session "${sessionId}" is corrupt: ${error.message}`,
+      'SESSION_QUERY_CORRUPT_SESSION',
+      { cause: error },
+    )
+  }
+  return new SessionQueryError(
+    `failed to observe session "${sessionId}": ${errorMessage(error)}`,
+    'SESSION_QUERY_PERSISTENCE_FAILED',
+    { cause: error },
+  )
+}
+
 function notFound(sessionId: SessionId, cause?: unknown): SessionQueryError {
   return new SessionQueryError(
     `session "${sessionId}" not found`,
diff --git a/packages/session-query/session-query/src/types.ts b/packages/session-query/session-query/src/types.ts
index 01c196aa1f..04b7295b26 100644
--- a/packages/session-query/session-query/src/types.ts
+++ b/packages/session-query/session-query/src/types.ts
@@ -29,7 +29,7 @@ export interface SessionRecord {
   header: SessionHeader
   /** Whether the id currently exists in `ctx.sessions`. */
   live: boolean
-  /** Whether the active persistence backend currently materializes the id. */
+  /** Whether the active persistence backend currently lists the id, including a created-but-unmaterialized session it already observes. */
   persisted: boolean
 }
 
@@ -51,7 +51,7 @@ export interface SessionLogSnapshot {
   session: SessionHeader
   /** Exact number of fork-inherited events in the observed log. */
   inheritedEventCount: SessionLogOffset
-  /** Cloned contiguous raw events after persistence repair and replay validation. */
+  /** Cloned contiguous raw events after in-memory interrupted-turn balancing and replay validation. */
   events: SessionEvent[]
 }
 
diff --git a/packages/session-query/session-query/tests/observation.spec.ts b/packages/session-query/session-query/tests/observation.spec.ts
index ef2460e7a2..aa2e6c31b6 100644
--- a/packages/session-query/session-query/tests/observation.spec.ts
+++ b/packages/session-query/session-query/tests/observation.spec.ts
@@ -1,138 +1,138 @@
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, { Session, SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
-import type { SessionHeader } from '@deepseek-ai/dsh-session'
-import { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
-import type { BorrowedSessionSource } from '@deepseek-ai/dsh-session-persistence'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionLogOffset, SessionSeq, SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
+import SessionPersistence, {
+  SessionPersistenceCorruptionError,
+  SessionPersistenceNotFoundError,
+  SessionPersistenceRevision,
+  SessionReadOnlyError,
+} from '@deepseek-ai/dsh-session-persistence'
+import type {
+  SessionAccess,
+  SessionHandle,
+  SessionHandleReadOptions,
+  SessionPersistenceSnapshot,
+  SessionPersistenceStatOptions,
+} from '@deepseek-ai/dsh-session-persistence'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import { describe, expect, it, vi } from 'vitest'
 import { SessionObservationReader } from '../src/observation.ts'
 
 function header(id: string): SessionHeader {
-  return { version: 0, id: SessionId(id), createdAt: 1, cwd: '/workspace', isSeeded: false }
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt: 1, isSeeded: false, cwd: '/workspace' }
 }
 
-function preparedSource(
-  meta: SessionHeader,
-  dispose = vi.fn(),
-): BorrowedSessionSource {
-  const preparedSession = Session.create(meta.id, [], meta, SessionLogOffset(0))
+function messageEvent(seq: number, text: string): SessionEvent {
   return {
-    source: 'prepared',
-    inspection: {
-      meta: preparedSession.header,
-      inheritedEventCount: preparedSession.inheritedEventCount,
-      events: preparedSession.snapshotEvents(),
-    },
-    revision: SessionPersistenceRevision(`fixture:${meta.id}`),
-    preparedSession,
-    [Symbol.dispose]: dispose,
+    type: 'user/message',
+    seq: SessionSeq(seq),
+    time: seq + 1,
+    data: createUserMessage({
+      content: [{ type: 'text', text }], source: { kind: 'user' },
+    }),
+    surfaceOp: 'append',
   }
 }
 
-describe('SessionObservationReader', () => {
-  it('prefers a live Session that attaches while a prepared source is borrowed', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const meta = header('attached-during-borrow')
-    const dispose = vi.fn()
-    const prepared = preparedSource(meta, dispose)
-    ctx.provide('sessionPersistence', {
-      borrowSession: () => {
-        ctx.sessions.create(meta.id, { meta })
-        return Promise.resolve(prepared)
-      },
-    } as never)
+/** A log whose writer crashed mid-turn: read-only viewing must balance it in memory. */
+function interruptedLog(text: string): SessionEvent[] {
+  return [
+    { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+    messageEvent(1, text),
+  ]
+}
 
-    using observed = await new SessionObservationReader(ctx).read(meta.id, { projectionMode: 'none' })
+interface StoredEntry {
+  header: SessionHeader
+  events: SessionEvent[]
+  revision: string
+}
 
-    expect(observed.source).toBe('live')
-    expect(dispose).toHaveBeenCalledOnce()
-    await ctx.fiber.dispose()
-  })
+interface StubCounters {
+  stat: number
+  open: number
+  read: number
+}
 
-  it('releases a borrowed source once when the winning live projection fails', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(SessionProjectionRegistry)
-    const meta = header('attached-projection-failure')
-    const dispose = vi.fn()
-    const prepared = preparedSource(meta, dispose)
-    ctx.provide('sessionPersistence', {
-      borrowSession: () => {
-        ctx.sessions.create(meta.id, { meta })
-        return Promise.resolve(prepared)
-      },
-    } as never)
-    vi.spyOn(ctx.sessionProjections, 'snapshot').mockImplementation(() => {
-      throw new Error('projection failed')
+interface StubHooks {
+  /** Runs inside `stat` before it resolves. */
+  onStat?: () => void
+  /** Runs inside `read` before it resolves. */
+  onRead?: () => void
+  /** Replaces the read result for every open handle. */
+  readFailure?: unknown
+  /** Replaces the stat result. */
+  statFailure?: unknown
+}
+
+/** Object-stub persistence: only the members the observation reader touches. */
+function stubPersistence(
+  store: Map<SessionIdType, StoredEntry>,
+  counters: StubCounters,
+  hooks: StubHooks = {},
+): SessionPersistence {
+  const stat = (
+    id: SessionIdType,
+    options?: SessionPersistenceStatOptions,
+  ): Promise<SessionPersistenceSnapshot | undefined> => {
+    counters.stat += 1
+    void options
+    const entry = store.get(id)
+    hooks.onStat?.()
+    if (hooks.statFailure !== undefined) {
+      // Exercise containment of a backend violating the Error rejection convention.
+      // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+      return Promise.reject(hooks.statFailure)
+    }
+    if (entry === undefined) return Promise.resolve(undefined)
+    return Promise.resolve({
+      header: structuredClone(entry.header),
+      revision: SessionPersistenceRevision(entry.revision),
     })
+  }
+  const open = (id: SessionIdType, access: SessionAccess): Promise<SessionHandle> => {
+    counters.open += 1
+    const entry = store.get(id)
+    if (entry === undefined) return Promise.reject(new SessionPersistenceNotFoundError(id))
+    const handle: SessionHandle = {
+      id,
+      header: structuredClone(entry.header),
+      inheritedEventCount: SessionLogOffset(0),
+      access,
+      read: (
+        _offset?: number,
+        _length?: number,
+        options?: SessionHandleReadOptions,
+      ): Promise<readonly SessionEvent[]> => {
+        counters.read += 1
+        void options
+        hooks.onRead?.()
+        if (hooks.readFailure !== undefined) {
+          // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+          return Promise.reject(hooks.readFailure)
+        }
+        return Promise.resolve(structuredClone(entry.events))
+      },
+      append: () => Promise.reject(new SessionReadOnlyError(id, 'append')),
+      flush: () => Promise.reject(new SessionReadOnlyError(id, 'flush')),
+      close: () => Promise.resolve(),
+      [Symbol.asyncDispose]: () => Promise.resolve(),
+    }
+    return Promise.resolve(handle)
+  }
+  return { stat, open } as never
+}
 
-    await expect(new SessionObservationReader(ctx).read(meta.id)).rejects.toThrow('projection failed')
-    expect(dispose).toHaveBeenCalledOnce()
-    await ctx.fiber.dispose()
-  })
-
-  it('retries when persistence reports a live source that has already detached', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const meta = header('detached-live-source')
-    const disposeLive = vi.fn()
-    const prepared = preparedSource(meta)
-    const borrowSession = vi.fn()
-      .mockResolvedValueOnce({
-        source: 'live',
-        inspection: { meta, inheritedEventCount: SessionLogOffset(0), events: [] },
-        [Symbol.dispose]: disposeLive,
-      } satisfies BorrowedSessionSource)
-      .mockResolvedValueOnce(prepared)
-    ctx.provide('sessionPersistence', { borrowSession } as never)
-
-    using observed = await new SessionObservationReader(ctx).read(meta.id, { projectionMode: 'none' })
-
-    expect(observed.source).toBe('prepared')
-    expect(borrowSession).toHaveBeenCalledTimes(2)
-    expect(disposeLive).toHaveBeenCalledOnce()
-    await ctx.fiber.dispose()
-  })
-
-  it('returns a prepared observation without projections when no registry is mounted', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const meta = header('prepared-without-projections')
-    ctx.provide('sessionPersistence', {
-      borrowSession: () => Promise.resolve(preparedSource(meta)),
-    } as never)
-
-    using observed = await new SessionObservationReader(ctx).read(meta.id)
-
-    expect(observed.source).toBe('prepared')
-    expect(observed.projections).toBeUndefined()
-    await ctx.fiber.dispose()
-  })
-
-  it('reference-counts prepared leases and rejects retention after disposal', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const meta = header('prepared-leases')
-    const dispose = vi.fn()
-    ctx.provide('sessionPersistence', {
-      borrowSession: () => Promise.resolve(preparedSource(meta, dispose)),
-    } as never)
-    const observed = await new SessionObservationReader(ctx).read(meta.id, { projectionMode: 'none' })
-    const retained = observed.retain()
-
-    observed[Symbol.dispose]()
-    observed[Symbol.dispose]()
-    expect(dispose).not.toHaveBeenCalled()
-    expect(() => observed.retain()).toThrow('is disposed')
-    retained[Symbol.dispose]()
-    expect(dispose).toHaveBeenCalledOnce()
-    await ctx.fiber.dispose()
-  })
+async function readerContext(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  return ctx
+}
 
+describe('SessionObservationReader live path', () => {
   it('creates independent live leases and rejects retention after disposal', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
+    const ctx = await readerContext()
     const session = ctx.sessions.create(SessionId('live-leases'), { meta: { cwd: '/workspace' } })
     const reader = new SessionObservationReader(ctx)
     const observed = await reader.read(session.id, { projectionMode: 'none' })
@@ -145,37 +145,599 @@ describe('SessionObservationReader', () => {
     await ctx.fiber.dispose()
   })
 
-  it('carries the exact inherited cut on a live observation', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const inherited = [
-      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
-      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
-    ] as const
-    const session = ctx.sessions.create(SessionId('seeded-observation'), {
-      seed: inherited,
-      inheritedEventCount: SessionLogOffset(inherited.length),
-      meta: { cwd: '/workspace', isSeeded: true },
+  it('computes live projections when the registry is mounted and surfaces its failure raw', async () => {
+    const ctx = await readerContext()
+    await ctx.plugin(SessionProjectionRegistry)
+    const session = ctx.sessions.create(SessionId('live-projections'))
+    const reader = new SessionObservationReader(ctx)
+
+    using observed = await reader.read(session.id)
+    expect(observed.projections).toBeDefined()
+
+    vi.spyOn(ctx.sessionProjections, 'snapshot').mockImplementation(() => {
+      throw new Error('projection failed')
     })
-
-    using observed = await new SessionObservationReader(ctx).read(session.id, { projectionMode: 'none' })
-
-    expect(observed.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
+    await expect(reader.read(session.id)).rejects.toThrow('projection failed')
     await ctx.fiber.dispose()
   })
 
-  it('contains a non-Error persistence rejection', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    ctx.provide('sessionPersistence', {
-      // Exercise containment of a backend that violates the Error rejection convention.
-      borrowSession: () => Promise.reject('offline'), // oxlint-disable-line typescript/prefer-promise-reject-errors
-    } as never)
+  it('reports a missing session when no persistence service is mounted', async () => {
+    const ctx = await readerContext()
+    await expect(new SessionObservationReader(ctx).read(SessionId('absent'))).rejects.toMatchObject({
+      code: 'SESSION_QUERY_SESSION_NOT_FOUND',
+    })
+    await ctx.fiber.dispose()
+  })
+})
 
-    await expect(new SessionObservationReader(ctx).read(SessionId('failed'))).rejects.toMatchObject({
+describe('SessionObservationReader cold path', () => {
+  it('balances an interrupted stored turn in memory and exposes the durable revision', async () => {
+    const ctx = await readerContext()
+    const meta = header('interrupted-cold')
+    const store = new Map([[meta.id, { header: meta, events: interruptedLog('crashed'), revision: 'r1' }]])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx)
+
+    using observed = await reader.read(meta.id)
+
+    expect(observed.source).toBe('prepared')
+    expect(observed.header).toMatchObject({ id: meta.id, cwd: '/workspace' })
+    expect(observed.revision).toBe(SessionPersistenceRevision('r1'))
+    expect(observed.events.map(event => event.type)).toEqual(['turn/start', 'user/message', 'turn/end'])
+    expect(observed.cursor).toBe(2)
+    // No projection registry is mounted, so the observation carries none.
+    expect(observed.projections).toBeUndefined()
+    // Balancing is in-memory only: nothing was written back to the store.
+    expect(store.get(meta.id)?.events).toHaveLength(2)
+    await ctx.fiber.dispose()
+  })
+
+  it('observes an empty stored log with a -1 cursor', async () => {
+    const ctx = await readerContext()
+    const meta = header('empty-cold')
+    const store = new Map([[meta.id, { header: meta, events: [], revision: 'r1' }]])
+    ctx.provide('sessionPersistence', stubPersistence(store, { stat: 0, open: 0, read: 0 }))
+
+    using observed = await new SessionObservationReader(ctx).read(meta.id, { projectionMode: 'none' })
+
+    expect(observed.events).toEqual([])
+    expect(observed.cursor).toBe(-1)
+    await ctx.fiber.dispose()
+  })
+
+  it('reference-counts prepared leases and rejects retention after disposal', async () => {
+    const ctx = await readerContext()
+    const meta = header('prepared-leases')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'kept')], revision: 'r1' }]])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx)
+    const observed = await reader.read(meta.id, { projectionMode: 'none' })
+    const retained = observed.retain()
+
+    observed[Symbol.dispose]()
+    observed[Symbol.dispose]()
+    expect(() => observed.retain()).toThrow('is disposed')
+    retained[Symbol.dispose]()
+    await ctx.fiber.dispose()
+  })
+
+  it('serves an unchanged revision from its cache without re-reading the log', async () => {
+    const ctx = await readerContext()
+    const meta = header('cache-hit')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'stable')], revision: 'r1' }]])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx)
+
+    using first = await reader.read(meta.id, { projectionMode: 'none' })
+    using second = await reader.read(meta.id, { projectionMode: 'none' })
+
+    expect(counters).toEqual({ stat: 2, open: 1, read: 1 })
+    expect(second.events).toBe(first.events)
+    await ctx.fiber.dispose()
+  })
+
+  it('reloads when the durable revision changes', async () => {
+    const ctx = await readerContext()
+    const meta = header('cache-stale')
+    const entry = { header: meta, events: [messageEvent(0, 'old')], revision: 'r1' }
+    const store = new Map([[meta.id, entry]])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx)
+
+    using first = await reader.read(meta.id, { projectionMode: 'none' })
+    entry.events = [messageEvent(0, 'old'), messageEvent(1, 'new')]
+    entry.revision = 'r2'
+    using second = await reader.read(meta.id, { projectionMode: 'none' })
+
+    expect(counters).toEqual({ stat: 2, open: 2, read: 2 })
+    expect(first.cursor).toBe(0)
+    expect(second.cursor).toBe(1)
+    expect(second.revision).toBe(SessionPersistenceRevision('r2'))
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps pinned entries cached past the capacity and never evicts them', async () => {
+    const ctx = await readerContext()
+    const a = header('pinned-a')
+    const b = header('pinned-b')
+    const store = new Map([
+      [a.id, { header: a, events: [messageEvent(0, 'a')], revision: 'ra' }],
+      [b.id, { header: b, events: [messageEvent(0, 'b')], revision: 'rb' }],
+    ])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx, 1)
+
+    const pinnedA = await reader.read(a.id, { projectionMode: 'none' })
+    using pinnedB = await reader.read(b.id, { projectionMode: 'none' })
+    // Both entries are pinned by live leases, so both stay cached over capacity.
+    using hitA = await reader.read(a.id, { projectionMode: 'none' })
+    using hitB = await reader.read(b.id, { projectionMode: 'none' })
+
+    expect(counters.read).toBe(2)
+    expect(hitA.events).toBe(pinnedA.events)
+    expect(hitB.events).toBe(pinnedB.events)
+    pinnedA[Symbol.dispose]()
+    await ctx.fiber.dispose()
+  })
+
+  it('continues evicting past pinned entries until the cache reaches its bound', async () => {
+    const ctx = await readerContext()
+    const a = header('sweep-a')
+    const b = header('sweep-b')
+    const c = header('sweep-c')
+    const store = new Map([
+      [a.id, { header: a, events: [messageEvent(0, 'a')], revision: 'ra' }],
+      [b.id, { header: b, events: [messageEvent(0, 'b')], revision: 'rb' }],
+      [c.id, { header: c, events: [messageEvent(0, 'c')], revision: 'rc' }],
+    ])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx, 1)
+
+    using pinnedA = await reader.read(a.id, { projectionMode: 'none' })
+    void pinnedA
+    {
+      using observedB = await reader.read(b.id, { projectionMode: 'none' })
+      void observedB
+    }
+    {
+      // Storing C sweeps past pinned A and evicts unpinned B, and the cache
+      // stays over its bound because the remaining entries are protected.
+      using observedC = await reader.read(c.id, { projectionMode: 'none' })
+      void observedC
+    }
+    expect(counters.read).toBe(3)
+    using hitA = await reader.read(a.id, { projectionMode: 'none' })
+    void hitA
+    expect(counters.read).toBe(3)
+    using rereadB = await reader.read(b.id, { projectionMode: 'none' })
+    void rereadB
+    expect(counters.read).toBe(4)
+    await ctx.fiber.dispose()
+  })
+
+  it('evicts on lease release when pins forced the cache over its bound', async () => {
+    const ctx = await readerContext()
+    const a = header('release-a')
+    const b = header('release-b')
+    const store = new Map([
+      [a.id, { header: a, events: [messageEvent(0, 'a')], revision: 'ra' }],
+      [b.id, { header: b, events: [messageEvent(0, 'b')], revision: 'rb' }],
+    ])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx, 1)
+
+    const pinnedA = await reader.read(a.id, { projectionMode: 'none' })
+    {
+      using observedB = await reader.read(b.id, { projectionMode: 'none' })
+      void observedB
+    }
+    // B's release found the cache over its bound (A stayed pinned) and evicted
+    // the just-unpinned B instead of leaving it resident for good.
+    expect(counters.read).toBe(2)
+    {
+      using rereadB = await reader.read(b.id, { projectionMode: 'none' })
+      void rereadB
+    }
+    expect(counters.read).toBe(3)
+    pinnedA[Symbol.dispose]()
+    await ctx.fiber.dispose()
+  })
+
+  it('a release sweep keeps evicting while the cache stays over its bound', async () => {
+    const ctx = await readerContext()
+    const a = header('sweep-release-a')
+    const b = header('sweep-release-b')
+    const c = header('sweep-release-c')
+    const store = new Map([
+      [a.id, { header: a, events: [messageEvent(0, 'a')], revision: 'ra' }],
+      [b.id, { header: b, events: [messageEvent(0, 'b')], revision: 'rb' }],
+      [c.id, { header: c, events: [messageEvent(0, 'c')], revision: 'rc' }],
+    ])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx, 1)
+
+    const pinnedA = await reader.read(a.id, { projectionMode: 'none' })
+    const pinnedB = await reader.read(b.id, { projectionMode: 'none' })
+    const pinnedC = await reader.read(c.id, { projectionMode: 'none' })
+    // B's release evicts B but the cache is still over its bound past the
+    // remaining pins, so the sweep continues (and finds only pinned entries).
+    pinnedB[Symbol.dispose]()
+    pinnedC[Symbol.dispose]()
+    expect(counters.read).toBe(3)
+    {
+      using rereadB = await reader.read(b.id, { projectionMode: 'none' })
+      void rereadB
+    }
+    expect(counters.read).toBe(4)
+    pinnedA[Symbol.dispose]()
+    await ctx.fiber.dispose()
+  })
+
+  it('evicts the least recently used unpinned entry at the capacity bound', async () => {
+    const ctx = await readerContext()
+    const a = header('lru-a')
+    const b = header('lru-b')
+    const c = header('lru-c')
+    const store = new Map([
+      [a.id, { header: a, events: [messageEvent(0, 'a')], revision: 'ra' }],
+      [b.id, { header: b, events: [messageEvent(0, 'b')], revision: 'rb' }],
+      [c.id, { header: c, events: [messageEvent(0, 'c')], revision: 'rc' }],
+    ])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    const reader = new SessionObservationReader(ctx, 2)
+    const readOnce = async (id: SessionIdType): Promise<void> => {
+      using observed = await reader.read(id, { projectionMode: 'none' })
+      void observed
+    }
+
+    await readOnce(a.id)
+    await readOnce(b.id)
+    await readOnce(a.id) // cache hit; A becomes most recently used
+    expect(counters.read).toBe(2)
+    await readOnce(c.id) // evicts B (least recently used), keeps A
+    expect(counters.read).toBe(3)
+    await readOnce(a.id)
+    expect(counters.read).toBe(3)
+    await readOnce(b.id)
+    expect(counters.read).toBe(4)
+    await ctx.fiber.dispose()
+  })
+
+  it('discards cached revisions produced by a replaced persistence instance', async () => {
+    const meta = header('swapped-instance')
+
+    class SwapHandle implements SessionHandle {
+      readonly inheritedEventCount = SessionLogOffset(0)
+      constructor(readonly id: SessionIdType, readonly header: SessionHeader, readonly access: SessionAccess) {}
+      read(): Promise<readonly SessionEvent[]> {
+        SwapPersistence.readCalls += 1
+        return Promise.resolve([messageEvent(0, 'swap')])
+      }
+
+      append(): Promise<void> {
+        return Promise.reject(new SessionReadOnlyError(this.id, 'append'))
+      }
+
+      flush(): Promise<void> {
+        return Promise.reject(new SessionReadOnlyError(this.id, 'flush'))
+      }
+
+      close(): Promise<void> {
+        return Promise.resolve()
+      }
+
+      [Symbol.asyncDispose](): Promise<void> {
+        return this.close()
+      }
+    }
+
+    class SwapPersistence extends SessionPersistence {
+      static readCalls = 0
+
+      create(): Promise<SessionHandle> {
+        return Promise.reject(new Error('not used'))
+      }
+
+      // Appends are durable on resolution here; nothing buffers, so the service-wide flush is a no-op.
+      async flush(): Promise<void> {}
+
+      open(id: SessionIdType, access: SessionAccess): Promise<SessionHandle> {
+        return Promise.resolve(new SwapHandle(id, structuredClone(meta), access))
+      }
+
+      stat(): Promise<SessionPersistenceSnapshot | undefined> {
+        return Promise.resolve({
+          header: structuredClone(meta),
+          revision: SessionPersistenceRevision('constant'),
+        })
+      }
+
+      list(): Promise<readonly SessionPersistenceSnapshot[]> {
+        return Promise.resolve([])
+      }
+    }
+
+    const ctx = await readerContext()
+    const reader = new SessionObservationReader(ctx)
+    const first = await ctx.plugin(SwapPersistence)
+    {
+      using observed = await reader.read(meta.id, { projectionMode: 'none' })
+      void observed
+    }
+    expect(SwapPersistence.readCalls).toBe(1)
+    await first.dispose()
+    const second = await ctx.plugin(SwapPersistence)
+    {
+      using observed = await reader.read(meta.id, { projectionMode: 'none' })
+      void observed
+    }
+    // The revision string matches, but revisions from different instances are
+    // incomparable, so the cached entry must not be reused.
+    expect(SwapPersistence.readCalls).toBe(2)
+    await second.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('prefers a live Session that attaches while the cold log is read', async () => {
+    const ctx = await readerContext()
+    const meta = header('attached-during-read')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'stale')], revision: 'r1' }]])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters, {
+      onRead: () => {
+        ctx.sessions.create(meta.id, {
+          meta: { createdAt: meta.createdAt, ...meta.cwd === undefined ? {} : { cwd: meta.cwd } },
+        })
+      },
+    }))
+
+    using observed = await new SessionObservationReader(ctx).read(meta.id, { projectionMode: 'none' })
+
+    expect(observed.source).toBe('live')
+    await ctx.fiber.dispose()
+  })
+
+  it('prefers a live Session that attaches while the snapshot is stated', async () => {
+    const ctx = await readerContext()
+    const meta = header('attached-during-stat')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'stale')], revision: 'r1' }]])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters, {
+      onStat: () => {
+        ctx.sessions.create(meta.id, {
+          meta: { createdAt: meta.createdAt, ...meta.cwd === undefined ? {} : { cwd: meta.cwd } },
+        })
+      },
+    }))
+
+    using observed = await new SessionObservationReader(ctx).read(meta.id, { projectionMode: 'none' })
+
+    expect(observed.source).toBe('live')
+    expect(counters.open).toBe(0)
+    await ctx.fiber.dispose()
+  })
+
+  it('retries the live path when the store rejects preparation for a live owner', async () => {
+    const ctx = await readerContext()
+    const meta = header('prepare-collision')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'stale')], revision: 'r1' }]])
+    const counters = { stat: 0, open: 0, read: 0 }
+    ctx.provide('sessionPersistence', stubPersistence(store, counters))
+    vi.spyOn(ctx.sessions, 'prepare').mockImplementationOnce(() => {
+      // A racing owner claims the id between the reader's live check and its
+      // preparation; the nested create uses the store's real prepare.
+      ctx.sessions.create(meta.id, { meta: { createdAt: meta.createdAt, ...meta.cwd === undefined ? {} : { cwd: meta.cwd } } })
+      throw new Error(`session "${meta.id}" already exists`)
+    })
+
+    using observed = await new SessionObservationReader(ctx).read(meta.id, { projectionMode: 'none' })
+
+    expect(observed.source).toBe('live')
+    await ctx.fiber.dispose()
+  })
+
+  it('maps a stored log the restore validation refuses to a corrupt-session failure', async () => {
+    const ctx = await readerContext()
+    const meta = header('bad-restore')
+    const store = new Map([[meta.id, {
+      header: meta,
+      events: [{ ...messageEvent(0, 'gap'), seq: SessionSeq(5) }],
+      revision: 'r1',
+    }]])
+    ctx.provide('sessionPersistence', stubPersistence(store, { stat: 0, open: 0, read: 0 }))
+
+    await expect(new SessionObservationReader(ctx).read(meta.id)).rejects.toMatchObject({
+      code: 'SESSION_QUERY_CORRUPT_SESSION',
+      message: expect.stringContaining('is corrupt') as string,
+    })
+    await ctx.fiber.dispose()
+  })
+
+  it('maps stat absence, open not-found, corruption, and non-Error rejections', async () => {
+    const ctx = await readerContext()
+    const meta = header('failure-taxonomy')
+    const counters = { stat: 0, open: 0, read: 0 }
+    const store = new Map<SessionIdType, StoredEntry>()
+    const hooks: StubHooks = {}
+    ctx.provide('sessionPersistence', stubPersistence(store, counters, hooks))
+    const reader = new SessionObservationReader(ctx)
+
+    await expect(reader.read(meta.id)).rejects.toMatchObject({
+      code: 'SESSION_QUERY_SESSION_NOT_FOUND',
+    })
+
+    store.set(meta.id, { header: meta, events: [messageEvent(0, 'gone')], revision: 'r1' })
+    hooks.onStat = () => {
+      delete hooks.onStat
+      // Deleted between stat and open: open reports not-found.
+      store.delete(meta.id)
+    }
+    await expect(reader.read(meta.id)).rejects.toMatchObject({
+      code: 'SESSION_QUERY_SESSION_NOT_FOUND',
+      cause: expect.any(SessionPersistenceNotFoundError) as Error,
+    })
+
+    store.set(meta.id, { header: meta, events: [messageEvent(0, 'torn')], revision: 'r2' })
+    hooks.readFailure = new SessionPersistenceCorruptionError('stored prefix failed validation', {
+      cause: new Error('torn record'),
+    })
+    await expect(reader.read(meta.id)).rejects.toMatchObject({
+      code: 'SESSION_QUERY_CORRUPT_SESSION',
+      message: `stored session "${meta.id}" is corrupt: stored prefix failed validation`,
+    })
+    hooks.readFailure = undefined
+
+    hooks.statFailure = 'offline'
+    await expect(reader.read(meta.id)).rejects.toMatchObject({
       code: 'SESSION_QUERY_PERSISTENCE_FAILED',
       message: expect.stringContaining('unknown error') as string,
     })
     await ctx.fiber.dispose()
   })
+
+  it('reports a header whose id does not match the requested session as a source conflict', async () => {
+    const ctx = await readerContext()
+    const meta = header('expected-id')
+    const store = new Map([[meta.id, {
+      header: { ...meta, id: SessionId('other-id') },
+      events: [messageEvent(0, 'other')],
+      revision: 'r1',
+    }]])
+    ctx.provide('sessionPersistence', stubPersistence(store, { stat: 0, open: 0, read: 0 }))
+
+    await expect(new SessionObservationReader(ctx).read(meta.id)).rejects.toMatchObject({
+      code: 'SESSION_QUERY_SOURCE_CONFLICT',
+    })
+    await ctx.fiber.dispose()
+  })
+
+  it('maps pre-abort, stat-time, read-time, and post-read cancellation to aborted reads', async () => {
+    const ctx = await readerContext()
+    const meta = header('aborted-cold')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'slow')], revision: 'r1' }]])
+    const counters = { stat: 0, open: 0, read: 0 }
+    const hooks: StubHooks = {}
+    ctx.provide('sessionPersistence', stubPersistence(store, counters, hooks))
+    const reader = new SessionObservationReader(ctx)
+
+    const preAborted = new AbortController()
+    preAborted.abort(new Error('before start'))
+    await expect(reader.read(meta.id, { signal: preAborted.signal })).rejects.toMatchObject({
+      code: 'SESSION_QUERY_ABORTED',
+    })
+    expect(counters.stat).toBe(0)
+
+    const statAbort = new AbortController()
+    hooks.onStat = () => {
+      delete hooks.onStat
+      statAbort.abort(new Error('stat deadline'))
+      throw new Error('stat interrupted')
+    }
+    await expect(reader.read(meta.id, { signal: statAbort.signal })).rejects.toMatchObject({
+      code: 'SESSION_QUERY_ABORTED',
+    })
+
+    const statResolvedAbort = new AbortController()
+    hooks.onStat = () => {
+      delete hooks.onStat
+      statResolvedAbort.abort(new Error('after stat'))
+    }
+    await expect(reader.read(meta.id, { signal: statResolvedAbort.signal })).rejects.toMatchObject({
+      code: 'SESSION_QUERY_ABORTED',
+    })
+
+    const readAbort = new AbortController()
+    hooks.onRead = () => {
+      delete hooks.onRead
+      readAbort.abort(new Error('read deadline'))
+      throw new Error('read interrupted')
+    }
+    await expect(reader.read(meta.id, { signal: readAbort.signal })).rejects.toMatchObject({
+      code: 'SESSION_QUERY_ABORTED',
+    })
+
+    const readResolvedAbort = new AbortController()
+    hooks.onRead = () => {
+      delete hooks.onRead
+      readResolvedAbort.abort(new Error('after read'))
+    }
+    await expect(reader.read(meta.id, { signal: readResolvedAbort.signal })).rejects.toMatchObject({
+      code: 'SESSION_QUERY_ABORTED',
+    })
+    await ctx.fiber.dispose()
+  })
+
+  it('surfaces a read failure that is neither corruption nor absence as a persistence failure', async () => {
+    const ctx = await readerContext()
+    const meta = header('read-failed')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'x')], revision: 'r1' }]])
+    ctx.provide('sessionPersistence', stubPersistence(store, { stat: 0, open: 0, read: 0 }, {
+      readFailure: new Error('disk detached'),
+    }))
+
+    await expect(new SessionObservationReader(ctx).read(meta.id)).rejects.toMatchObject({
+      code: 'SESSION_QUERY_PERSISTENCE_FAILED',
+      message: expect.stringContaining('disk detached') as string,
+    })
+    await ctx.fiber.dispose()
+  })
+})
+
+describe('SessionObservationReader cold projections', () => {
+  it('hydrates prepared projections through the registry when no projection cache is mounted', async () => {
+    const ctx = await readerContext()
+    await ctx.plugin(SessionProjectionRegistry)
+    const meta = header('cold-registry')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'projected')], revision: 'r1' }]])
+    ctx.provide('sessionPersistence', stubPersistence(store, { stat: 0, open: 0, read: 0 }))
+
+    using observed = await new SessionObservationReader(ctx).read(meta.id)
+
+    expect(observed.source).toBe('prepared')
+    expect(observed.projections).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('hydrates prepared projections through a mounted projection cache', async () => {
+    const ctx = await readerContext()
+    await ctx.plugin(SessionProjectionRegistry)
+    const meta = header('cold-cache')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'cached')], revision: 'r1' }]])
+    ctx.provide('sessionPersistence', stubPersistence(store, { stat: 0, open: 0, read: 0 }))
+    const snapshot = { asOfSeq: 0, values: {} }
+    const hydratePrepared = vi.fn().mockReturnValue(snapshot)
+    ctx.provide('sessionProjectionCache', { hydratePrepared } as never)
+
+    using observed = await new SessionObservationReader(ctx).read(meta.id)
+
+    expect(observed.projections).toBe(snapshot)
+    expect(hydratePrepared).toHaveBeenCalledOnce()
+    await ctx.fiber.dispose()
+  })
+
+  it('wraps a prepared projection failure as a corrupt-session failure', async () => {
+    const ctx = await readerContext()
+    await ctx.plugin(SessionProjectionRegistry)
+    const meta = header('cold-projection-failure')
+    const store = new Map([[meta.id, { header: meta, events: [messageEvent(0, 'broken')], revision: 'r1' }]])
+    ctx.provide('sessionPersistence', stubPersistence(store, { stat: 0, open: 0, read: 0 }))
+    vi.spyOn(ctx.sessionProjections, 'hydrate').mockImplementation(() => {
+      throw new Error('hydration failed')
+    })
+
+    await expect(new SessionObservationReader(ctx).read(meta.id)).rejects.toMatchObject({
+      code: 'SESSION_QUERY_CORRUPT_SESSION',
+      message: expect.stringContaining('failed to project') as string,
+    })
+    await ctx.fiber.dispose()
+  })
 })
diff --git a/packages/session-query/session-query/tests/session-query.spec.ts b/packages/session-query/session-query/tests/session-query.spec.ts
index f011df923d..10e30ec2ba 100644
--- a/packages/session-query/session-query/tests/session-query.spec.ts
+++ b/packages/session-query/session-query/tests/session-query.spec.ts
@@ -1,16 +1,21 @@
 import { createUserMessage, createMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it, vi } from 'vitest'
 import { Context, type Fiber } from '@deepseek-ai/cordis'
-import SessionStore, {
-  SESSION_FORMAT_VERSION,
-  SessionId,
-  SessionLogOffset,
-  SessionSeq,
-} from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionLogOffset, SessionSeq, SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
-import SessionPersistence, { SessionPersistenceCorruptionError, SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
-import type { SessionEventSuffix, SessionInspection } from '@deepseek-ai/dsh-session-persistence'
+import SessionPersistence, {
+  SessionPersistenceCorruptionError,
+  SessionPersistenceNotFoundError,
+  SessionPersistenceRevision,
+  SessionReadOnlyError,
+} from '@deepseek-ai/dsh-session-persistence'
+import type {
+  SessionAccess,
+  SessionHandle,
+  SessionHandleReadOptions,
+  SessionPersistenceSnapshot,
+} from '@deepseek-ai/dsh-session-persistence'
 import SessionQueryEngine, {
   SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
   type SessionEventSurface,
@@ -25,7 +30,7 @@ function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}):
   return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, isSeeded: false, ...extra }
 }
 
-function eventLog(text = 'hello'): SessionEvent<'user/message'>[] {
+function eventLog(text = 'hello'): SessionEvent[] {
   return [{
     type: 'user/message',
     seq: SessionSeq(0),
@@ -37,108 +42,121 @@ function eventLog(text = 'hello'): SessionEvent<'user/message'>[] {
   }]
 }
 
-class TestPersistence extends SessionPersistence {
-  override readonly supportsRawArtifacts = false
+class TestHandle implements SessionHandle {
+  readonly inheritedEventCount = SessionLogOffset(0)
 
+  constructor(
+    readonly id: SessionIdType,
+    readonly header: SessionHeader,
+    readonly access: SessionAccess,
+  ) {}
+
+  read(offset = 0, length?: number, options?: SessionHandleReadOptions): Promise<readonly SessionEvent[]> {
+    TestPersistence.readCalls.push(this.id)
+    TestPersistence.readSignals.push(options?.signal)
+    const slice = (events: SessionEvent[]): SessionEvent[] => {
+      const from = events.filter(event => event.seq >= offset)
+      return length === undefined ? from : from.slice(0, length)
+    }
+    if (TestPersistence.readOverride !== undefined) {
+      return TestPersistence.readOverride(this.id, options?.signal).then(loaded => slice(loaded.events))
+    }
+    if (TestPersistence.readFailure !== undefined) return rejectUnknown(TestPersistence.readFailure)
+    const entry = TestPersistence.entries.get(this.id)
+    if (entry === undefined) return Promise.reject(new SessionPersistenceNotFoundError(this.id))
+    const result = structuredClone(entry.events)
+    TestPersistence.readEffect?.()
+    TestPersistence.readEffect = undefined
+    return Promise.resolve(slice(result))
+  }
+
+  append(events: readonly SessionEvent[]): Promise<void> {
+    if (this.access === 'read') return Promise.reject(new SessionReadOnlyError(this.id, 'append'))
+    const entry = TestPersistence.entries.get(this.id)
+    if (entry === undefined) return Promise.reject(new SessionPersistenceNotFoundError(this.id))
+    entry.events.push(...structuredClone(events))
+    return Promise.resolve()
+  }
+
+  flush(): Promise<void> {
+    if (this.access === 'read') return Promise.reject(new SessionReadOnlyError(this.id, 'flush'))
+    return Promise.resolve()
+  }
+
+  close(): Promise<void> {
+    return Promise.resolve()
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close()
+  }
+}
+
+function entryRevision(entry: { events: SessionEvent[] }): SessionPersistenceRevision {
+  return SessionPersistenceRevision(`events:${entry.events.length}`)
+}
+
+class TestPersistence extends SessionPersistence {
   static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
   static listFailure: unknown
-  static listOverride: ((signal?: AbortSignal) => Promise<SessionHeader[]>) | undefined
-  static inspectFailure: unknown
-  static inspectEffect: (() => void) | undefined
-  static inspectOverride: ((
+  static listOverride: ((signal?: AbortSignal) => Promise<SessionPersistenceSnapshot[]>) | undefined
+  static readFailure: unknown
+  static readEffect: (() => void) | undefined
+  static readOverride: ((
     id: SessionIdType,
     signal?: AbortSignal,
-  ) => Promise<SessionInspection>) | undefined
+  ) => Promise<{ meta: SessionHeader; events: SessionEvent[] }>) | undefined
   static afterList: (() => void) | undefined
   static listCalls = 0
-  static inspectCalls: SessionIdType[] = []
+  static readCalls: SessionIdType[] = []
   static listSignals: Array<AbortSignal | undefined> = []
-  static inspectSignals: Array<AbortSignal | undefined> = []
+  static readSignals: Array<AbortSignal | undefined> = []
 
   static reset(entries: readonly { meta: SessionHeader; events: SessionEvent[] }[] = []): void {
     this.entries = new Map(entries.map(entry => [entry.meta.id, structuredClone(entry)]))
     this.listFailure = undefined
     this.listOverride = undefined
-    this.inspectFailure = undefined
-    this.inspectEffect = undefined
-    this.inspectOverride = undefined
+    this.readFailure = undefined
+    this.readEffect = undefined
+    this.readOverride = undefined
     this.afterList = undefined
     this.listCalls = 0
-    this.inspectCalls = []
+    this.readCalls = []
     this.listSignals = []
-    this.inspectSignals = []
+    this.readSignals = []
   }
 
-  locate(_meta: SessionHeader): undefined {
-    return undefined
+  create(header: SessionHeader): Promise<SessionHandle> {
+    TestPersistence.entries.set(header.id, { meta: structuredClone(header), events: [] })
+    return Promise.resolve(new TestHandle(header.id, structuredClone(header), 'write'))
   }
 
-  borrowSession(_id: SessionIdType, _signal?: AbortSignal): ReturnType<SessionPersistence['borrowSession']> {
-    return Promise.reject(new Error('not used'))
-  }
+  // Appends are durable on resolution here; nothing buffers, so the service-wide flush is a no-op.
+  async flush(): Promise<void> {}
 
-  create(meta: SessionHeader): Promise<void> {
-    TestPersistence.entries.set(meta.id, { meta: structuredClone(meta), events: [] })
-    return Promise.resolve()
-  }
-
-  append(id: SessionIdType, events: readonly SessionEvent[]): Promise<void> {
+  open(id: SessionIdType, access: SessionAccess): Promise<SessionHandle> {
     const entry = TestPersistence.entries.get(id)
-    if (entry === undefined) return Promise.reject(new Error('missing test session'))
-    entry.events.push(...structuredClone(events))
-    return Promise.resolve()
+    if (entry === undefined) return Promise.reject(new SessionPersistenceNotFoundError(id))
+    return Promise.resolve(new TestHandle(id, structuredClone(entry.meta), access))
   }
 
-  load(id: SessionIdType): Promise<SessionInspection> {
-    return this.inspect(id)
-  }
-
-  inspect(
-    id: SessionIdType,
-    signal?: AbortSignal,
-  ): Promise<SessionInspection> {
-    TestPersistence.inspectCalls.push(id)
-    TestPersistence.inspectSignals.push(signal)
-    if (TestPersistence.inspectOverride !== undefined) {
-      return TestPersistence.inspectOverride(id, signal)
-    }
-    if (TestPersistence.inspectFailure !== undefined) return rejectUnknown(TestPersistence.inspectFailure)
+  stat(id: SessionIdType): Promise<SessionPersistenceSnapshot | undefined> {
     const entry = TestPersistence.entries.get(id)
-    if (entry === undefined) return Promise.reject(new Error('missing test session'))
-    const result: SessionInspection = {
-      ...structuredClone(entry),
-      inheritedEventCount: SessionLogOffset(0),
-    }
-    TestPersistence.inspectEffect?.()
-    TestPersistence.inspectEffect = undefined
-    return Promise.resolve(result)
+    if (entry === undefined) return Promise.resolve(undefined)
+    return Promise.resolve({ header: structuredClone(entry.meta), revision: entryRevision(entry) })
   }
 
-  async readFrom(
-    id: SessionIdType,
-    fromSeq: SessionLogOffset,
-    signal?: AbortSignal,
-  ): Promise<SessionEventSuffix> {
-    const whole = await this.inspect(id, signal)
-    return { ...whole, fromSeq, events: whole.events.filter(event => event.seq >= fromSeq) }
-  }
-
-  list(signal?: AbortSignal): Promise<SessionHeader[]> {
+  list(options?: { signal?: AbortSignal }): Promise<readonly SessionPersistenceSnapshot[]> {
     TestPersistence.listCalls += 1
-    TestPersistence.listSignals.push(signal)
-    if (TestPersistence.listOverride !== undefined) return TestPersistence.listOverride(signal)
+    TestPersistence.listSignals.push(options?.signal)
+    if (TestPersistence.listOverride !== undefined) return TestPersistence.listOverride(options?.signal)
     if (TestPersistence.listFailure !== undefined) return rejectUnknown(TestPersistence.listFailure)
-    const headers = [...TestPersistence.entries.values()].map(entry => structuredClone(entry.meta))
-    TestPersistence.afterList?.()
-    return Promise.resolve(headers)
-  }
-
-
-  async listSnapshots() {
-    return [...TestPersistence.entries.values()].map(entry => ({
+    const snapshots = [...TestPersistence.entries.values()].map(entry => ({
       header: structuredClone(entry.meta),
-      revision: SessionPersistenceRevision(`events:${entry.events.length}`),
+      revision: entryRevision(entry),
     }))
+    TestPersistence.afterList?.()
+    return Promise.resolve(snapshots)
   }
 }
 
@@ -263,7 +281,7 @@ describe.each(cancellableSessionListings)('$name cancellation', ({ run }) => {
     const controller = new AbortController()
     const reason = new Error('session listing cancelled before persistence returned')
     const started = Promise.withResolvers<undefined>()
-    const listing = Promise.withResolvers<SessionHeader[]>()
+    const listing = Promise.withResolvers<SessionPersistenceSnapshot[]>()
     TestPersistence.listOverride = (_signal) => {
       started.resolve(undefined)
       return listing.promise
@@ -291,7 +309,7 @@ describe.each(cancellableExactReads)('$name cancellation', ({ inspects, run }) =
 
     await expect(run(ctx, persisted.id, controller.signal)).rejects.toBe(reason)
     expect(TestPersistence.listCalls).toBe(0)
-    expect(TestPersistence.inspectCalls).toEqual([])
+    expect(TestPersistence.readCalls).toEqual([])
   })
 
   it('forwards in-flight list cancellation and waits for cleanup before rejecting', async () => {
@@ -333,7 +351,7 @@ describe.each(cancellableExactReads)('$name cancellation', ({ inspects, run }) =
     expect(settled).toBe(false)
     expect(active).toBe(true)
     expect(TestPersistence.listSignals).toEqual([controller.signal])
-    expect(TestPersistence.inspectCalls).toEqual([])
+    expect(TestPersistence.readCalls).toEqual([])
 
     cleanup.resolve(undefined)
     await expect(pending).rejects.toBe(reason)
@@ -352,15 +370,12 @@ describe.each(cancellableExactReads)('$name cancellation', ({ inspects, run }) =
     const release = Promise.withResolvers<undefined>()
     let active = false
     if (inspects) {
-      TestPersistence.inspectOverride = async () => {
+      TestPersistence.readOverride = async () => {
         active = true
         started.resolve(undefined)
         await release.promise
         active = false
-        return {
-          ...structuredClone(entry),
-          inheritedEventCount: SessionLogOffset(0),
-        }
+        return structuredClone(entry)
       }
     } else {
       TestPersistence.listOverride = async () => {
@@ -368,7 +383,7 @@ describe.each(cancellableExactReads)('$name cancellation', ({ inspects, run }) =
         started.resolve(undefined)
         await release.promise
         active = false
-        return [structuredClone(persisted)]
+        return [{ header: structuredClone(persisted), revision: SessionPersistenceRevision('override:0') }]
       }
     }
 
@@ -384,7 +399,7 @@ describe.each(cancellableExactReads)('$name cancellation', ({ inspects, run }) =
     expect(settled).toBe(false)
     expect(active).toBe(true)
     expect(TestPersistence.listSignals).toEqual([controller.signal])
-    expect(TestPersistence.inspectSignals).toEqual(inspects ? [controller.signal] : [])
+    expect(TestPersistence.readSignals).toEqual(inspects ? [controller.signal] : [])
 
     release.resolve(undefined)
     await expect(pending).rejects.toBe(reason)
@@ -406,7 +421,7 @@ describe.each(cancellableExactReads.filter(read => read.inspects))(
       const abortObserved = Promise.withResolvers<undefined>()
       const cleanup = Promise.withResolvers<undefined>()
       let active = false
-      TestPersistence.inspectOverride = async (_sessionId, signal) => {
+      TestPersistence.readOverride = async (_sessionId, signal) => {
         if (signal === undefined) throw new Error('expected exact-read inspection signal')
         active = true
         const aborted = new Promise<void>((resolve) => {
@@ -434,7 +449,7 @@ describe.each(cancellableExactReads.filter(read => read.inspects))(
       expect(settled).toBe(false)
       expect(active).toBe(true)
       expect(TestPersistence.listSignals).toEqual([controller.signal])
-      expect(TestPersistence.inspectSignals).toEqual([controller.signal])
+      expect(TestPersistence.readSignals).toEqual([controller.signal])
 
       cleanup.resolve(undefined)
       await expect(pending).rejects.toBe(reason)
@@ -472,7 +487,7 @@ describe('session-query exact reads', () => {
     TestPersistence.reset([{ meta: shared, events: eventLog('persisted') }])
     const ctx = await liveContext()
     await ctx.plugin(TestPersistence)
-    TestPersistence.inspectEffect = () => {
+    TestPersistence.readEffect = () => {
       ctx.sessions.create(shared.id, {
         seed: eventLog('live'),
         meta: { createdAt: shared.createdAt },
@@ -572,9 +587,9 @@ describe('session-query exact reads', () => {
     expect(results[0]).toMatchObject({ value: { session: second, title: { title: 'Second title' } } })
     expect(results[1]).toMatchObject({ value: { session: first, title: { title: 'First title' } } })
     expect(TestPersistence.listCalls).toBe(1)
-    expect(TestPersistence.inspectCalls).toEqual([second.id, first.id])
+    expect(TestPersistence.readCalls).toEqual([second.id, first.id])
     expect(TestPersistence.listSignals).toEqual([signal])
-    expect(TestPersistence.inspectSignals).toEqual([signal, signal])
+    expect(TestPersistence.readSignals).toEqual([signal, signal])
   })
 
   it('bounds persisted title inspection concurrency while preserving ordered results', async () => {
@@ -587,24 +602,21 @@ describe('session-query exact reads', () => {
     await ctx.plugin(TestPersistence)
     let active = 0
     let maximum = 0
-    TestPersistence.inspectOverride = async (id) => {
+    TestPersistence.readOverride = async (id) => {
       active += 1
       maximum = Math.max(maximum, active)
       await new Promise<void>(resolve => setImmediate(resolve))
       active -= 1
       const entry = TestPersistence.entries.get(id)
       if (entry === undefined) throw new Error('missing bounded test session')
-      return {
-        ...structuredClone(entry),
-        inheritedEventCount: SessionLogOffset(0),
-      }
+      return structuredClone(entry)
     }
 
     const results = await ctx.sessionQuery.readTitleSnapshots(entries.map(entry => entry.meta.id))
 
     expect(maximum).toBe(SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY)
     expect(TestPersistence.listCalls).toBe(1)
-    expect(TestPersistence.inspectCalls).toEqual(entries.map(entry => entry.meta.id))
+    expect(TestPersistence.readCalls).toEqual(entries.map(entry => entry.meta.id))
     expect(results.map(result => result.sessionId)).toEqual(entries.map(entry => entry.meta.id))
     expect(results.every(result => result.status === 'fulfilled')).toBe(true)
   })
@@ -619,7 +631,7 @@ describe('session-query exact reads', () => {
     await ctx.plugin(TestPersistence)
     const timeline: string[] = []
     const releases = new Map<SessionIdType, () => void>()
-    TestPersistence.inspectOverride = id => new Promise((resolve) => {
+    TestPersistence.readOverride = id => new Promise((resolve) => {
       timeline.push(`inspect:${id}`)
       releases.set(id, () => {
         const marker = `full-log-marker:${id}`
@@ -638,7 +650,6 @@ describe('session-query exact reads', () => {
         } as unknown as SessionEvent
         resolve({
           meta: entries.find(entry => entry.meta.id === id)!.meta,
-          inheritedEventCount: SessionLogOffset(0),
           events: [...eventLog(marker), titleEvent],
         })
       })
@@ -651,9 +662,9 @@ describe('session-query exact reads', () => {
     const ids = entries.map(entry => entry.meta.id)
 
     const pending = ctx.sessionQuery.readTitleSnapshots(ids)
-    await vi.waitFor(() => { expect(TestPersistence.inspectCalls).toHaveLength(4) })
+    await vi.waitFor(() => { expect(TestPersistence.readCalls).toHaveLength(4) })
     release(ids[0]!)
-    await vi.waitFor(() => { expect(TestPersistence.inspectCalls).toHaveLength(5) })
+    await vi.waitFor(() => { expect(TestPersistence.readCalls).toHaveLength(5) })
 
     // Heap-retention assertions would depend on nondeterministic GC. This ordering
     // is the deterministic guard: a retain-all implementation cannot touch the
@@ -677,7 +688,7 @@ describe('session-query exact reads', () => {
     const reason = new Error('title deadline')
     let started!: () => void
     const inspectStarted = new Promise<void>((resolve) => { started = resolve })
-    TestPersistence.inspectOverride = (_id, signal) => new Promise((_resolve, reject) => {
+    TestPersistence.readOverride = (_id, signal) => new Promise((_resolve, reject) => {
       started()
       signal?.addEventListener('abort', () => { reject(reason) }, { once: true })
     })
@@ -688,7 +699,7 @@ describe('session-query exact reads', () => {
 
     await expect(pending).rejects.toBe(reason)
     expect(TestPersistence.listSignals).toEqual([controller.signal])
-    expect(TestPersistence.inspectSignals).toEqual([controller.signal])
+    expect(TestPersistence.readSignals).toEqual([controller.signal])
   })
 
   it('drains started title inspections after cancellation without starting queued ids', async () => {
@@ -697,15 +708,15 @@ describe('session-query exact reads', () => {
       events: eventLog(`queued-${index}`),
     }))
     TestPersistence.reset(entries)
-    const persistedInspectConcurrency = 2
-    const ctx = await liveContext({ persistedInspectConcurrency })
+    const persistedReadConcurrency = 2
+    const ctx = await liveContext({ persistedReadConcurrency })
     await ctx.plugin(TestPersistence)
     const controller = new AbortController()
     const reason = new Error('cancel queued title batch')
     const releases: Array<() => void> = []
     let abortsObserved = 0
     let inspectionsSettled = 0
-    TestPersistence.inspectOverride = (_id, signal) => new Promise((_resolve, reject) => {
+    TestPersistence.readOverride = (_id, signal) => new Promise((_resolve, reject) => {
       signal?.addEventListener('abort', () => { abortsObserved += 1 }, { once: true })
       releases.push(() => {
         inspectionsSettled += 1
@@ -723,20 +734,20 @@ describe('session-query exact reads', () => {
       () => { batchSettled = true },
     )
     await vi.waitFor(() => {
-      expect(TestPersistence.inspectCalls).toHaveLength(persistedInspectConcurrency)
+      expect(TestPersistence.readCalls).toHaveLength(persistedReadConcurrency)
     })
     controller.abort(reason)
-    await vi.waitFor(() => { expect(abortsObserved).toBe(persistedInspectConcurrency) })
+    await vi.waitFor(() => { expect(abortsObserved).toBe(persistedReadConcurrency) })
 
     expect(batchSettled).toBe(false)
-    expect(TestPersistence.inspectCalls)
-      .toEqual(entries.slice(0, persistedInspectConcurrency).map(entry => entry.meta.id))
+    expect(TestPersistence.readCalls)
+      .toEqual(entries.slice(0, persistedReadConcurrency).map(entry => entry.meta.id))
     for (const release of releases) release()
 
     await expect(pending).rejects.toBe(reason)
-    expect(inspectionsSettled).toBe(persistedInspectConcurrency)
-    expect(TestPersistence.inspectCalls)
-      .toEqual(entries.slice(0, persistedInspectConcurrency).map(entry => entry.meta.id))
+    expect(inspectionsSettled).toBe(persistedReadConcurrency)
+    expect(TestPersistence.readCalls)
+      .toEqual(entries.slice(0, persistedReadConcurrency).map(entry => entry.meta.id))
   })
 
   it('passes cancellation into a stalled persisted title listing and rejects with its reason', async () => {
@@ -759,7 +770,7 @@ describe('session-query exact reads', () => {
 
     await expect(pending).rejects.toBe(reason)
     expect(TestPersistence.listSignals).toEqual([controller.signal])
-    expect(TestPersistence.inspectCalls).toEqual([])
+    expect(TestPersistence.readCalls).toEqual([])
   })
 
   it('isolates title read and fold failures while preferring a live owner attached during inspection', async () => {
@@ -784,7 +795,7 @@ describe('session-query exact reads', () => {
     const ctx = await liveContext()
     await ctx.plugin(SessionTitleService, TITLE_SERVICE_CONFIG)
     await ctx.plugin(TestPersistence)
-    TestPersistence.inspectOverride = (id) => {
+    TestPersistence.readOverride = (id) => {
       if (id === failed.id) return Promise.reject(inspectFailure)
       const entry = TestPersistence.entries.get(id)
       if (entry === undefined) return Promise.reject(new Error('missing test session'))
@@ -796,10 +807,7 @@ describe('session-query exact reads', () => {
           source: { kind: 'fallback' },
         })
       }
-      return Promise.resolve({
-        ...structuredClone(entry),
-        inheritedEventCount: SessionLogOffset(0),
-      })
+      return Promise.resolve(structuredClone(entry))
     }
 
     const results = await ctx.sessionQuery.readTitleSnapshots([
@@ -998,10 +1006,7 @@ describe('session-query exact reads', () => {
       createUserMessage({
         content: [{ type: 'text', text: 'latest checkpoint' }], source: { kind: 'plugin', plugin: 'compact' },
       }),
-      {
-        surfaceOp: { op: 'replace', start: SessionSeq(2), end: retained.seq },
-        sourceEventSeqs: [SessionSeq(2), retained.seq],
-      },
+      { surfaceOp: { op: 'replace', start: SessionSeq(2), end: retained.seq }, sourceEventSeqs: [SessionSeq(2), retained.seq] },
     )
     session.append(
       'assistant/message',
@@ -1060,12 +1065,7 @@ describe('session-query exact reads', () => {
       )
     }
 
-    const result = await ctx.sessionQuery.readEvent({
-      sessionId: session.id,
-      seq: SessionSeq(2),
-      before: 1,
-      after: 1,
-    })
+    const result = await ctx.sessionQuery.readEvent({ sessionId: session.id, seq: SessionSeq(2), before: 1, after: 1 })
     expect([result.startSeq, result.endSeq, result.target.seq]).toEqual([1, 3, 2])
     expect(result.session).toEqual(session.header)
     Object.assign(result.session, { createdAt: -1 })
@@ -1147,16 +1147,16 @@ describe('session-query exact reads', () => {
     )
     await ctx.plugin(TestPersistence)
     TestPersistence.listFailure = new Error('list unavailable')
-    TestPersistence.inspectFailure = new Error('inspect unavailable')
+    TestPersistence.readFailure = new Error('inspect unavailable')
     const signal = new AbortController().signal
 
     await expect(ctx.sessionQuery.listEvents(live.id)).resolves.toHaveLength(2)
     await expect(ctx.sessionQuery.traceEvent({ sessionId: live.id, seq: SessionSeq(1) }, signal))
-      .resolves.toMatchObject({ session: { id: live.id }, target: { seq: 1 } })
+      .resolves.toMatchObject({ session: { id: live.id }, target: { seq: SessionSeq(1) } })
     await expect(ctx.sessionQuery.readEvent({ sessionId: live.id, seq: SessionSeq(1) }, signal))
-      .resolves.toMatchObject({ target: { seq: 1 } })
+      .resolves.toMatchObject({ target: { seq: SessionSeq(1) } })
     expect(TestPersistence.listSignals).toEqual([])
-    expect(TestPersistence.inspectSignals).toEqual([])
+    expect(TestPersistence.readSignals).toEqual([])
     await expect(ctx.sessionQuery.listSessions()).rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
     await expect(ctx.sessionQuery.listEvents(SessionId('durable'))).rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
   })
@@ -1170,7 +1170,7 @@ describe('session-query exact reads', () => {
       'stored prefix failed validation',
       { cause: new Error('torn final record') },
     )
-    TestPersistence.inspectFailure = corruption
+    TestPersistence.readFailure = corruption
 
     await expect(ctx.sessionQuery.readSession(durable.id)).rejects.toMatchObject({
       code: 'SESSION_QUERY_CORRUPT_SESSION',
@@ -1189,10 +1189,10 @@ describe('session-query exact reads', () => {
     await expect(ctx.sessionQuery.listEvents(SessionId('absent')))
       .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
 
-    TestPersistence.inspectFailure = 'raw failure'
+    TestPersistence.readFailure = 'raw failure'
     await expect(ctx.sessionQuery.listEvents(durable.id))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
-    TestPersistence.inspectFailure = undefined
+    TestPersistence.readFailure = undefined
     const durableEntry = TestPersistence.entries.get(durable.id)!
     durableEntry.meta = { ...durableEntry.meta, cwd: '/changed-after-list' }
     TestPersistence.afterList = () => {
@@ -1227,8 +1227,10 @@ describe('session-query exact reads', () => {
     expect(new TestSessionQueryEngine(direct)).toBeInstanceOf(SessionQueryEngine)
     for (const config of [
       { readWindowMax: -1 },
-      { persistedInspectConcurrency: 0 },
-      { persistedInspectConcurrency: Number.MAX_SAFE_INTEGER + 1 },
+      { persistedReadConcurrency: 0 },
+      { persistedReadConcurrency: Number.MAX_SAFE_INTEGER + 1 },
+      { preparedSessionCacheSize: 0 },
+      { preparedSessionCacheSize: Number.MAX_SAFE_INTEGER + 1 },
     ]) {
       const invalid = new Context()
       await invalid.plugin(SessionStore)
@@ -1237,6 +1239,16 @@ describe('session-query exact reads', () => {
     }
   })
 
+  it('exposes caller-owned observation leases through observeSession', async () => {
+    const ctx = await liveContext()
+    const live = ctx.sessions.create(SessionId('observe-live'))
+
+    using observed = await ctx.sessionQuery.observeSession(live.id)
+
+    expect(observed.source).toBe('live')
+    expect(observed.header.id).toBe(live.id)
+  })
+
   it('leaves the optional persistence dependency optional', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/session-query/session-query/tests/tracing.spec.ts b/packages/session-query/session-query/tests/tracing.spec.ts
index e40af94f68..fbc29998b3 100644
--- a/packages/session-query/session-query/tests/tracing.spec.ts
+++ b/packages/session-query/session-query/tests/tracing.spec.ts
@@ -1,16 +1,19 @@
 import { createUserMessage, createMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import SessionStore, {
-  SESSION_FORMAT_VERSION,
-  SessionId,
-  SessionLogOffset,
-  SessionSeq,
-} from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionLogOffset, SessionSeq, SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { Session, SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
-import SessionPersistence from '@deepseek-ai/dsh-session-persistence'
-import type { SessionEventSuffix, SessionInspection } from '@deepseek-ai/dsh-session-persistence'
+import SessionPersistence, {
+  SessionPersistenceNotFoundError,
+  SessionPersistenceRevision,
+  SessionReadOnlyError,
+} from '@deepseek-ai/dsh-session-persistence'
+import type {
+  SessionAccess,
+  SessionHandle,
+  SessionPersistenceSnapshot,
+} from '@deepseek-ai/dsh-session-persistence'
 import { type SessionQueryErrorCode } from '@deepseek-ai/dsh-session-query'
 import { TestSessionQueryEngine } from './test-service.ts'
 
@@ -25,89 +28,102 @@ function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}):
   return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, isSeeded: false, ...extra }
 }
 
-function appendEvent(seq: SessionSeq, sources?: number[]): SessionEvent {
+function appendEvent(seq: number, sources?: readonly number[]): SessionEvent {
   return {
     type: 'user/message',
-    seq,
+    seq: SessionSeq(seq),
     time: seq + 1,
     data: createUserMessage({
       content: [{ type: 'text', text: `event ${seq}` }], source: { kind: 'user' },
     }),
     surfaceOp: 'append',
-    ...sources === undefined ? {} : { sourceEventSeqs: sources.map(SessionSeq) },
+    ...sources === undefined ? {} : { sourceEventSeqs: sources as unknown as SessionSeq[] },
+  }
+}
+
+class TraceHandle implements SessionHandle {
+  readonly inheritedEventCount = SessionLogOffset(0)
+  constructor(
+    readonly id: SessionIdType,
+    readonly header: SessionHeader,
+    readonly access: SessionAccess,
+  ) {}
+
+  read(): Promise<readonly SessionEvent[]> {
+    TracePersistence.readCalls += 1
+    if (TracePersistence.readFailure !== undefined) return Promise.reject(TracePersistence.readFailure)
+    const entry = TracePersistence.entries.get(this.id)
+    if (entry === undefined) return Promise.reject(new SessionPersistenceNotFoundError(this.id))
+    return Promise.resolve(structuredClone(entry.events))
+  }
+
+  append(): Promise<void> {
+    return Promise.reject(new SessionReadOnlyError(this.id, 'append'))
+  }
+
+  flush(): Promise<void> {
+    return Promise.reject(new SessionReadOnlyError(this.id, 'flush'))
+  }
+
+  close(): Promise<void> {
+    return Promise.resolve()
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close()
   }
 }
 
 class TracePersistence extends SessionPersistence {
-  override readonly supportsRawArtifacts = false
-
   static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
   static listCalls = 0
-  static inspectCalls = 0
+  static readCalls = 0
   static listFailure: Error | undefined
-  static inspectFailure: Error | undefined
+  static readFailure: Error | undefined
   static afterList: (() => void) | undefined
 
   static reset(entries: readonly { meta: SessionHeader; events: SessionEvent[] }[] = []): void {
     this.entries = new Map(entries.map(entry => [entry.meta.id, structuredClone(entry)]))
     this.listCalls = 0
-    this.inspectCalls = 0
+    this.readCalls = 0
     this.listFailure = undefined
-    this.inspectFailure = undefined
+    this.readFailure = undefined
     this.afterList = undefined
   }
 
-  locate(_meta: SessionHeader): undefined {
-    return undefined
+  create(header: SessionHeader): Promise<SessionHandle> {
+    TracePersistence.entries.set(header.id, { meta: structuredClone(header), events: [] })
+    return Promise.resolve(new TraceHandle(header.id, structuredClone(header), 'write'))
   }
 
-  borrowSession(_id: SessionIdType, _signal?: AbortSignal): ReturnType<SessionPersistence['borrowSession']> {
-    return Promise.reject(new Error('not used'))
-  }
+  // Appends are durable on resolution here; nothing buffers, so the service-wide flush is a no-op.
+  async flush(): Promise<void> {}
 
-  create(meta: SessionHeader): Promise<void> {
-    TracePersistence.entries.set(meta.id, { meta: structuredClone(meta), events: [] })
-    return Promise.resolve()
-  }
-
-  append(id: SessionIdType, events: readonly SessionEvent[]): Promise<void> {
+  open(id: SessionIdType, access: SessionAccess): Promise<SessionHandle> {
     const entry = TracePersistence.entries.get(id)
-    if (entry === undefined) return Promise.reject(new Error('missing test session'))
-    entry.events.push(...structuredClone(events))
-    return Promise.resolve()
+    if (entry === undefined) return Promise.reject(new SessionPersistenceNotFoundError(id))
+    return Promise.resolve(new TraceHandle(id, structuredClone(entry.meta), access))
   }
 
-  load(id: SessionIdType): Promise<SessionInspection> {
-    return this.inspect(id)
-  }
-
-  inspect(id: SessionIdType): Promise<SessionInspection> {
-    TracePersistence.inspectCalls += 1
-    if (TracePersistence.inspectFailure !== undefined) return Promise.reject(TracePersistence.inspectFailure)
+  stat(id: SessionIdType): Promise<SessionPersistenceSnapshot | undefined> {
     const entry = TracePersistence.entries.get(id)
-    if (entry === undefined) return Promise.reject(new Error('missing test session'))
+    if (entry === undefined) return Promise.resolve(undefined)
     return Promise.resolve({
-      ...structuredClone(entry),
-      inheritedEventCount: SessionLogOffset(0),
+      header: structuredClone(entry.meta),
+      revision: SessionPersistenceRevision(`events:${entry.events.length}`),
     })
   }
 
-  async readFrom(id: SessionIdType, fromSeq: SessionLogOffset): Promise<SessionEventSuffix> {
-    const whole = await this.inspect(id)
-    return { ...whole, fromSeq, events: whole.events.filter(event => event.seq >= fromSeq) }
-  }
-
-  list(): Promise<SessionHeader[]> {
+  list(): Promise<readonly SessionPersistenceSnapshot[]> {
     TracePersistence.listCalls += 1
     if (TracePersistence.listFailure !== undefined) return Promise.reject(TracePersistence.listFailure)
-    const result = [...TracePersistence.entries.values()].map(entry => structuredClone(entry.meta))
+    const result = [...TracePersistence.entries.values()].map(entry => ({
+      header: structuredClone(entry.meta),
+      revision: SessionPersistenceRevision(`events:${entry.events.length}`),
+    }))
     TracePersistence.afterList?.()
     return Promise.resolve(result)
   }
-
-  listSnapshots(): Promise<never[]> {
-    return Promise.resolve([])
-  }
 }
 
 async function queryContext(): Promise<Context> {
@@ -150,10 +166,7 @@ function appendTraceEvents(session: Session): void {
         },
       }),
     },
-    {
-      surfaceOp: { op: 'replace', start: SessionSeq(3), end: SessionSeq(3) },
-      sourceEventSeqs: [SessionSeq(3), SessionSeq(2)],
-    },
+    { surfaceOp: { op: 'replace', start: SessionSeq(3), end: SessionSeq(3) }, sourceEventSeqs: [SessionSeq(3), SessionSeq(2)] },
   )
   session.append(
     'user/message',
@@ -177,10 +190,7 @@ function appendTraceEvents(session: Session): void {
         },
       }),
     },
-    {
-      surfaceOp: { op: 'replace', start: SessionSeq(4), end: SessionSeq(4) },
-      sourceEventSeqs: [SessionSeq(2), SessionSeq(4)],
-    },
+    { surfaceOp: { op: 'replace', start: SessionSeq(4), end: SessionSeq(4) }, sourceEventSeqs: [SessionSeq(2), SessionSeq(4)] },
   )
 }
 
@@ -259,7 +269,7 @@ describe('session lineage tracing', () => {
 
   it('uses one cross-corpus observation and preserves persistence failure semantics', async () => {
     const durable = header('durable')
-    TracePersistence.reset([{ meta: durable, events: [appendEvent(SessionSeq(0))] }])
+    TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
@@ -268,7 +278,7 @@ describe('session lineage tracing', () => {
       complete: true,
     })
     expect(TracePersistence.listCalls).toBe(1)
-    expect(TracePersistence.inspectCalls).toBe(0)
+    expect(TracePersistence.readCalls).toBe(0)
 
     TracePersistence.listFailure = new Error('unavailable')
     await expect(ctx.sessionQuery.traceSession(durable.id))
@@ -306,7 +316,7 @@ describe('session event tracing', () => {
     const original = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: SessionSeq(3) })
     expect(original.target).toMatchObject({
       sessionId: session.id,
-      seq: 3,
+      seq: SessionSeq(3),
       type: 'user/message',
       surface: 'shadowed',
     })
@@ -362,13 +372,13 @@ describe('session event tracing', () => {
 
   it('inspects persisted logs once, prefers live logs, and preserves failures and conflicts', async () => {
     const durable = header('shared', 1, { cwd: '/same' })
-    TracePersistence.reset([{ meta: durable, events: [appendEvent(SessionSeq(0))] }])
+    TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
     await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .resolves.toMatchObject({ target: { type: 'user/message', surface: 'current' } })
-    expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1])
+    expect([TracePersistence.listCalls, TracePersistence.readCalls]).toEqual([1, 1])
 
     const live = ctx.sessions.create(durable.id, { meta: { createdAt: 1, cwd: '/same' } })
     live.append('turn/start', { turn: 1 })
@@ -380,22 +390,22 @@ describe('session event tracing', () => {
       { surfaceOp: 'append' },
     )
     TracePersistence.listFailure = new Error('list unavailable')
-    TracePersistence.inspectFailure = new Error('inspect unavailable')
+    TracePersistence.readFailure = new Error('inspect unavailable')
     await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(1) }))
       .resolves.toMatchObject({ target: { type: 'user/message' } })
-    expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1])
+    expect([TracePersistence.listCalls, TracePersistence.readCalls]).toEqual([1, 1])
 
-    TracePersistence.reset([{ meta: durable, events: [appendEvent(SessionSeq(0))] }])
+    TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
     const failedCtx = await queryContext()
     await failedCtx.plugin(TracePersistence)
     TracePersistence.listFailure = new Error('list unavailable')
     await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
     TracePersistence.listFailure = undefined
-    TracePersistence.inspectFailure = new Error('inspect unavailable')
+    TracePersistence.readFailure = new Error('inspect unavailable')
     await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: SessionSeq(0) }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
-    TracePersistence.inspectFailure = undefined
+    TracePersistence.readFailure = undefined
     TracePersistence.afterList = () => {
       mutableHeader(TracePersistence.entries.get(durable.id)!.meta).cwd = '/changed'
     }
@@ -405,7 +415,7 @@ describe('session event tracing', () => {
 
   it('checks target existence before surface or source-event analysis', async () => {
     const bad = header('bad-target')
-    const malformed: SessionEvent[] = [appendEvent(SessionSeq(0)), {
+    const malformed: SessionEvent[] = [appendEvent(0), {
       type: 'assistant/message',
       seq: SessionSeq(1),
       time: 2,
@@ -435,37 +445,37 @@ describe('session event tracing', () => {
 
   it.each([
     ['non-surface sources', [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 }, sourceEventSeqs: [0] },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 }, sourceEventSeqs: [0] },
     ]],
     ['invalid source array', [
-      { ...appendEvent(SessionSeq(0)), sourceEventSeqs: 'invalid' },
+      { ...appendEvent(0), sourceEventSeqs: 'invalid' },
     ]],
     ['empty sources', [
-      appendEvent(SessionSeq(0), []),
+      appendEvent(0, []),
     ]],
     ['sparse sources', [
-      appendEvent(SessionSeq(0), Array<number>(1)),
+      appendEvent(0, Array<number>(1)),
     ]],
     ['duplicate sources', [
-      appendEvent(SessionSeq(0)),
-      appendEvent(SessionSeq(1), [0, 0]),
+      appendEvent(0),
+      appendEvent(1, [0, 0]),
     ]],
     ['missing earlier source', [
-      appendEvent(SessionSeq(0)),
-      { ...appendEvent(SessionSeq(1)), sourceEventSeqs: [-1] } as unknown as SessionEvent,
+      appendEvent(0),
+      appendEvent(1, [-1]),
     ]],
     ['future source', [
-      appendEvent(SessionSeq(0), [1]),
-      appendEvent(SessionSeq(1)),
+      appendEvent(0, [1]),
+      appendEvent(1),
     ]],
     ['replacement without sources', [
-      appendEvent(SessionSeq(0)),
-      { ...appendEvent(SessionSeq(1)), surfaceOp: { op: 'replace', start: 0, end: 0 } },
+      appendEvent(0),
+      { ...appendEvent(1), surfaceOp: { op: 'replace', start: 0, end: 0 } },
     ]],
     ['replacement missing a shadowed source', [
-      { type: 'assistant/chunk', seq: 0, time: 1, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'draft' } } },
-      appendEvent(SessionSeq(1)),
-      { ...appendEvent(SessionSeq(2), [0]), surfaceOp: { op: 'replace', start: 1, end: 1 } },
+      { type: 'assistant/chunk', seq: SessionSeq(0), time: 1, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'draft' } } },
+      appendEvent(1),
+      { ...appendEvent(2, [0]), surfaceOp: { op: 'replace', start: 1, end: 1 } },
     ]],
   ] as const)('rejects an invalid surface log: %s', async (_name, rawEvents) => {
     const durable = header('invalid-provenance')
@@ -482,7 +492,7 @@ describe('session event tracing', () => {
     const durable = header('invalid-non-surface-op')
     const events = [{
       type: 'turn/start',
-      seq: 0,
+      seq: SessionSeq(0),
       time: 1,
       data: { turn: 1 },
       surfaceOp: 'append',
@@ -497,7 +507,7 @@ describe('session event tracing', () => {
 
   it('applies the same surface contract to listEvents', async () => {
     const durable = header('list-regression')
-    TracePersistence.reset([{ meta: durable, events: [appendEvent(SessionSeq(0)), appendEvent(SessionSeq(1), [0, 0])] }])
+    TracePersistence.reset([{ meta: durable, events: [appendEvent(0), appendEvent(1, [0, 0])] }])
     const ctx = await queryContext()
     await ctx.plugin(TracePersistence)
 
diff --git a/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts b/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts
index 5e60ac5118..ed6402865f 100644
--- a/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts
+++ b/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts
@@ -53,14 +53,14 @@ describe('tool-session-query with the real SQLite provider', () => {
     await ctx.plugin(ToolSessionQuery)
 
     const persisted = SessionId('persisted')
-    await ctx.sessionPersistence.create({
+    const writer = await ctx.sessionPersistence.create({
       version: SESSION_FORMAT_VERSION,
       id: persisted,
       createdAt: 1,
       cwd: '/work',
       isSeeded: false,
     })
-    await ctx.sessionPersistence.append(persisted, [{
+    await writer.append([{
       type: 'user/message',
       seq: SessionSeq(0),
       time: 2,
@@ -70,6 +70,7 @@ describe('tool-session-query with the real SQLite provider', () => {
       }),
       surfaceOp: 'append',
     }])
+    await writer.close()
 
     const caller = ctx.sessions.create(SessionId('caller'), {
       meta: { createdAt: 10, cwd: '/work' },
@@ -126,14 +127,14 @@ describe('tool-session-query with the real SQLite provider', () => {
 
     const base = Date.parse('2026-07-24T00:00:00.000Z')
     const persisted = SessionId('fractional-persisted')
-    await ctx.sessionPersistence.create({
+    const writer = await ctx.sessionPersistence.create({
       version: SESSION_FORMAT_VERSION,
       id: persisted,
       createdAt: base,
       cwd: '/work',
       isSeeded: false,
     })
-    await ctx.sessionPersistence.append(persisted, [
+    await writer.append([
       {
         type: 'user/message',
         seq: SessionSeq(0),
@@ -175,6 +176,7 @@ describe('tool-session-query with the real SQLite provider', () => {
         surfaceOp: 'append',
       },
     ])
+    await writer.close()
 
     const caller = ctx.sessions.create(SessionId('fractional-caller'), {
       meta: { createdAt: base + 1_000, cwd: '/work' },
diff --git a/packages/session/session-checkpoint-policy/tests/crash-recovery.e2e.ts b/packages/session/session-checkpoint-policy/tests/crash-recovery.e2e.ts
index fb09802203..cf5552ec54 100644
--- a/packages/session/session-checkpoint-policy/tests/crash-recovery.e2e.ts
+++ b/packages/session/session-checkpoint-policy/tests/crash-recovery.e2e.ts
@@ -6,7 +6,7 @@ import { execa } from 'execa'
 import { Context } from '@deepseek-ai/cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import SessionStore, {
-  SessionId, TOOL_OUTCOME_UNKNOWN,
+  SessionId, TOOL_OUTCOME_UNKNOWN, interruptedTurnClosers,
   type SessionEvent,
 } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
@@ -64,12 +64,21 @@ async function crashAt(mode: 'request' | 'tool'): Promise<{ root: string; marker
   }
 }
 
+// Read the crashed durable log and balance it the way a resuming reader does:
+// the stored events stay untouched; `interruptedTurnClosers` supplies the
+// in-memory closers for the interrupted tail turn.
 async function load(root: string): Promise<SessionEvent[]> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
   await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   try {
-    return [...(await ctx.sessionPersistence.load(sessionId)).events]
+    const handle = await ctx.sessionPersistence.open(sessionId, 'read')
+    try {
+      const events = await handle.read()
+      return [...events, ...interruptedTurnClosers(events)]
+    } finally {
+      await handle.close()
+    }
   } finally {
     await ctx.fiber.dispose()
   }
diff --git a/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts b/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
index 670d410ee3..654b1ab18f 100644
--- a/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
+++ b/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
@@ -4,34 +4,21 @@ import Loader from '@deepseek-ai/cordis-plugin-loader'
 import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import LlmRuntime, { ToolCallId, type GenerateOptions, LlmAdapter, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionHeader, SessionLogOffset } from '@deepseek-ai/dsh-session'
-import SessionPersistence, { type SessionEventSuffix, type SessionInspection } from '@deepseek-ai/dsh-session-persistence'
+import SessionPersistence, { type SessionHandle, type SessionPersistenceSnapshot } from '@deepseek-ai/dsh-session-persistence'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime, { TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
 import * as checkpointPolicy from '../src/index.ts'
 
 const contexts: Context[] = []
 
+// The policy only requires the service's presence; it flushes through
+// `ctx.sessions`, so no handle is ever opened in these tests.
 class TestPersistence extends SessionPersistence {
-  override readonly supportsRawArtifacts = false
-
-  locate(_meta: SessionHeader): undefined { return undefined }
-  create(_meta: SessionHeader): Promise<void> { return Promise.resolve() }
-  append(_id: SessionId, _events: readonly SessionEvent[]): Promise<void> { return Promise.resolve() }
-  load(_id: SessionId): Promise<SessionInspection> {
-    return Promise.reject(new Error('not used'))
-  }
-  inspect(_id: SessionId): Promise<SessionInspection> {
-    return Promise.reject(new Error('not used'))
-  }
-  borrowSession(_id: SessionId, _signal?: AbortSignal): ReturnType<SessionPersistence['borrowSession']> {
-    return Promise.reject(new Error('not used'))
-  }
-  readFrom(_id: SessionId, _fromSeq: SessionLogOffset): Promise<SessionEventSuffix> {
-    return Promise.reject(new Error('not used'))
-  }
-  list(): Promise<SessionHeader[]> { return Promise.resolve([]) }
-  listSnapshots(): Promise<never[]> { return Promise.resolve([]) }
+  create(): Promise<SessionHandle> { return Promise.reject(new Error('not used')) }
+  open(): Promise<SessionHandle> { return Promise.reject(new Error('not used')) }
+  flush(): Promise<void> { return Promise.resolve() }
+  stat(): Promise<SessionPersistenceSnapshot | undefined> { return Promise.resolve(undefined) }
+  list(): Promise<readonly SessionPersistenceSnapshot[]> { return Promise.resolve([]) }
 }
 
 class RecordingAdapter extends LlmAdapter {
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 0a44d29f0c..a443c9871e 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/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/session/session-persistence-jsonl/README.md
-README.md: d3dfaf8affb142979ede69d86bbf0b1587e8c39c
-README.zh.md: 15fc815523355674a1f325b604dd2655f56f7f58
+README.md: 9d2175df1536943d56ac150135fcf4018f645256
+README.zh.md: 9de71107687837b4833f15edb9ba033be50d7a81
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index d3dfaf8aff..9d2175df15 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-session-persistence-jsonl` stores each session in its own append-only JSONL log — checksummed Zstandard frames by default, raw newline-delimited lines when compression is disabled. It serves the same logical `SessionEvent` stream as any persistence backend, so choosing it changes nothing for the agent loop, the model, or replay; compression, packing, and crash recovery are storage-internal details. Choose it when consumers need a per-session artifact on disk: `locate(meta)` returns the transcript path, and the logs are readable as plain lines when `compression: 'none'` is selected. A root directory is the one required configuration; durability, lazy materialization, and interrupted-turn recovery come with the backend.
+`dsh-session-persistence-jsonl` stores each session in its own append-only JSONL log — checksummed Zstandard frames by default, raw newline-delimited lines when compression is disabled. It serves the same logical `SessionEvent` stream as any persistence backend, so choosing it changes nothing for the agent loop, the model, or replay; compression, packing, and crash recovery are storage-internal details. Choose it when consumers need a per-session file on disk; the logs are readable as plain lines when `compression: 'none'` is selected. A root directory is the one required configuration; durability, lazy materialization, and torn-tail crash recovery come with the backend.
 
 ## Table of Contents
 
@@ -47,8 +47,8 @@ Choose this backend when consumers benefit from one artifact per session — nav
 | `root` | required | Root directory for all session files |
 | `packChunks` | `true` | Write eligible `assistant/chunk` runs as packed rows; `false` keeps one event per line for diagnostics |
 | `compression` | `'zstd'` | Physical encoding: `'zstd'` checksummed frames, or `'none'` newline-delimited UTF-8 text |
-| `preparedSessionCacheSize` | `5` | Cold session preparations retained for resume reuse |
-| `writeBatchMaxDelayMs` | `200` | Fixed live-event coalescing window, in milliseconds |
+
+Live-event write batching is not configuration: the batching window is the seam's internal scheduling policy inside each write handle.
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-session-persistence-jsonl) is the exhaustive source for every accepted field and its JSDoc.
 
@@ -64,15 +64,15 @@ Each session gets a session-owned directory under a readable project directory;
       session.jsonl              # only with compression: 'none'
 ```
 
-Session ids are injectively escaped to one safe path segment before use (no traversal, no collision). The normalized cwd keeps the project directory readable for navigation; cwd strings that normalize alike share a project directory while session ids still select distinct session directories. `locate(meta)` returns `{ kind: 'jsonl', path }` for the fixed transcript inside the resolved directories, performing no filesystem I/O.
+Session ids are injectively escaped to one safe path segment before use (no traversal, no collision). The normalized cwd keeps the project directory readable for navigation; cwd strings that normalize alike share a project directory while session ids still select distinct session directories. Format-refusal diagnostics name the absolute path of the fixed transcript inside the resolved directories, so an operator can find the raw log a build refused to interpret.
 
 ### Durability and crash semantics
 
-A session is materialized lazily: `create(meta)` writes nothing, and the first `append` writes and `fsync`s the encoded header and first batch through a no-overwrite publish — so a created-but-never-appended session leaves nothing on disk unless a lifecycle consumer calls `ensureMaterialized`, which publishes one header frame without an event. Flushed events are never rewritten; each subsequent batch appends lines or one compressed frame, and a caught write or sync failure rolls the file back to its prior length. After a crash, `load` preserves an interrupted final turn: it keeps the complete decoded records of an incomplete last frame, truncates from that frame's start, and re-encodes the records with the synthetic tool, step, and turn closers required by the shared persistence contract. Only a never-fully-written torn tail is discarded; checksum, decompression, or structural failure in the committed prefix rejects as corruption.
+A session is materialized lazily: `create(header)` writes nothing and returns the owned write handle, and the handle's first `append` writes and `fsync`s the encoded header and first batch through a no-overwrite publish — so a created-but-never-appended session leaves nothing on disk unless its owner calls `handle.flush()`, which publishes one header frame without an event. Each subsequent batch appends lines or one compressed frame and `fsync`s before the append resolves; a caught write or sync failure rolls the file back to its prior length. Committed events are never rewritten. After a crash, the stored log keeps its interrupted final turn — every record in the committed prefix survives, and the resuming reader appends synthetic closers through its write handle. A torn tail — an incomplete final line, or a torn final frame — is never returned to a reader and is discarded whole, truncated durably before the write handle's first new append, because its own append never resolved and nothing in it was acknowledged durable; checksum, decompression, or structural failure in the committed prefix rejects as corruption.
 
 ### Reading the logs
 
-`inspect(id)` returns an immutable balanced view with its exact inherited cut without committing recovery. `readFrom(id, fromOffset)` accepts a `SessionLogOffset`, returns stored events at or past that offset, and retains the same cut beside the suffix; sequential media like JSONL parse the whole artifact and skip forward. Header-only listing exposes `isSeeded` without reading event bodies. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
+`open(id, 'read')` returns a handle whose `read(offset?, length?)` serves validated contiguous slices; the artifact is re-scanned on demand under a bounded stable read, so a slice never contains a torn tail. A torn final Zstandard frame is partially decoded: complete JSONL records already flushed into it are recovered into the logical log, and the write handle's first mutation truncates the torn bytes and durably rewrites the recovered records ahead of its own batch. `open(id, 'write')` primes the handle with the validated stored prefix, so resume's whole-log read costs no second parse before the first append. A bounded memo keyed by session id and the stat-derived revision lets an immediately following open reuse the parsed log — the cold observe-then-resume handoff parses once — and every local mutation invalidates its id. `stat(id)` and `list()` read only the header line and one `fs.stat`, carrying `sizeBytes` and a best-effort stat-derived revision (device, inode, size, nanosecond timestamps) without parsing the log. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
 -----
 
@@ -86,7 +86,7 @@ This section explains the physical encoding and write path; the observable contr
 
 ### Design concept
 
-The backend is a thin storage layer over the shared [PersistenceCoordinator](../session-persistence/README.md#understand-the-implementation): it loads stored records, appends batches, commits repairs, and delegates lifecycle orchestration to the coordinator. Its physical identity is a file revision: device, inode, size, and nanosecond timestamps identify one log and change after append or repair, which is what `listSnapshots` and retained-preparation validation use.
+The backend owns its complete storage runtime (`src/storage.ts`): `JsonlSessionHandle` carries the per-handle mutation chain, the routed live-event buffer with its fixed batching window and single-flight drain, monotonic reads, and idempotent close; a tracker holds the in-process single-writer claims, the open-handle set teardown sweeps, and the created-but-unmaterialized pending sessions the backend's own session listeners route into. The package deliberately exposes only its default plugin export plus configuration types — the concrete class is not a named export, so consumers couple to `ctx.sessionPersistence`, and the shared seam suites (`runPersistenceContract`/`runLiveWritePathContract`) pin its observable behavior. Its change token is a best-effort file revision: device, inode, size, and nanosecond timestamps identify one log for `stat`/`list` and for the stable-read loop that retries a read torn by a concurrent append.
 
 ### Physical encoding
 
@@ -96,7 +96,8 @@ The default artifact is a standard concatenation of independent [Zstandard frame
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: `Config` schema, backend class, coordinator wiring |
+| [`src/index.ts`](src/index.ts) | Plugin entry: `Config` schema, the backend service class, and file storage primitives |
+| [`src/storage.ts`](src/storage.ts) | The JSONL handle, routed live-event buffer, in-process writer bookkeeping, listeners, teardown |
 | [`src/format.ts`](src/format.ts) | Log path derivation, header encoding, record scanning, packed-row layout |
 | [`src/zstd.ts`](src/zstd.ts) | Zstandard frame compression, decoding, and frame scanning |
 | [`src/win32.ts`](src/win32.ts) | Windows write-through publish and directory creation |
@@ -146,7 +147,7 @@ These limits define when this backend is a poor fit or needs special operational
 - **The flat-file storage layout does not load** — use a separate root or move pre-release artifacts into the project/session directory layout before loading.
 - **Compressed files are not directly line-readable** — use the backend to load them, or select `compression: 'none'` before writing a fresh root when external line readers are required.
 - **Nothing deletes session files** — logs accumulate under `root` until removed externally; the seam has no deletion API.
-- **One live writer per session** — append and repair are coordinated only inside the owning backend instance; another instance or process must not write the same session until that owner reaches quiescent disposal.
+- **One live writer per session, in-process only** — the write-handle claim excludes a second writer inside the owning backend instance; another instance or process must not write the same session until that handle closes (the durable cross-process lease is the seam's planned next layer).
 - **POSIX materialization requires hard-link support** — first append uses `link()` so same-id races fail instead of overwriting a committed log; Windows uses write-through rename without replacement.
 
 <a id="dev-note"></a>
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 15fc815523..9de7110768 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-session-persistence-jsonl` 把每个会话存为一份仅追加 JSONL 日志——默认以带校验和的 Zstandard 帧存储，禁用压缩时以换行分隔的原始文本行存储。它提供与任何持久化后端相同的逻辑 `SessionEvent` 流，因此选择它不会改变 agent loop、模型或回放的任何行为；压缩、打包与崩溃恢复都是存储内部细节。当消费方需要按会话的磁盘产物时选择它：`locate(meta)` 返回 transcript 路径，选择 `compression: 'none'` 后日志可作为纯文本按行读取。根目录是唯一必填配置；持久性、延迟实体化与中断轮次恢复都随后端提供。
+`dsh-session-persistence-jsonl` 把每个会话存为一份仅追加 JSONL 日志——默认以带校验和的 Zstandard 帧存储，禁用压缩时以换行分隔的原始文本行存储。它提供与任何持久化后端相同的逻辑 `SessionEvent` 流，因此选择它不会改变 agent loop、模型或回放的任何行为；压缩、打包与崩溃恢复都是存储内部细节。当消费方需要按会话的磁盘文件时选择它；选择 `compression: 'none'` 后日志可作为纯文本按行读取。根目录是唯一必填配置；持久性、延迟实体化与撕裂尾部崩溃恢复都随后端提供。
 
 ## 目录
 
@@ -47,8 +47,8 @@ kind: "package-reference"
 | `root` | 必填 | 所有会话文件的根目录 |
 | `packChunks` | `true` | 把符合条件的 `assistant/chunk` 连续段写为打包行；`false` 为诊断保留每事件一行 |
 | `compression` | `'zstd'` | 物理编码：`'zstd'` 带校验和帧，或 `'none'` 换行分隔 UTF-8 文本 |
-| `preparedSessionCacheSize` | `5` | 为恢复复用而保留的冷会话准备结果数量 |
-| `writeBatchMaxDelayMs` | `200` | 实时事件的固定聚合窗口，单位为毫秒 |
+
+实时事件的写入批处理不是配置：批处理窗口是该 seam 在每个写句柄内部的调度策略。
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-session-persistence-jsonl)是每个受支持字段及其 JSDoc 的穷尽式真源。
 
@@ -64,15 +64,15 @@ kind: "package-reference"
       session.jsonl              # only with compression: 'none'
 ```
 
-会话 id 在使用前被单射转义为一个安全路径段（无遍历、无冲突）。规范化 cwd 让项目目录保持可读、便于导航；规范化相同的 cwd 字符串共享项目目录，而会话 id 仍选择不同会话目录。`locate(meta)` 返回已解析目录内固定 transcript 的 `{ kind: 'jsonl', path }`，不执行任何文件系统 I/O。
+会话 id 在使用前被单射转义为一个安全路径段（无遍历、无冲突）。规范化 cwd 让项目目录保持可读、便于导航；规范化相同的 cwd 字符串共享项目目录，而会话 id 仍选择不同会话目录。格式拒绝诊断会点名已解析目录内固定 transcript 的绝对路径，让操作者能找到构建拒绝解读的原始日志。
 
 ### 持久性与崩溃语义
 
-会话延迟实体化：`create(meta)` 不写入任何内容，第一次 `append` 通过无覆盖发布写入并 `fsync` 编码后的 header 与第一批——因此已创建但从未 append 的会话不留下任何磁盘内容，除非生命周期消费方调用 `ensureMaterialized`，以无事件的单个 header 帧发布它。已 flush 事件绝不重写；后续每个批次追加行或一个压缩帧，捕获到写入或同步失败时把文件回滚到之前的字节长度。崩溃后，`load` 保留被中断的最终轮次：保留不完整最后帧中完整解码的记录，从该帧开头截断，并按共享持久化约定的要求，用合成工具、步骤与轮次 closer 重新编码这些记录。只有从未完整写入的撕裂尾部被丢弃；已提交前缀中的校验和、解压或结构失败以损坏拒绝。
+会话延迟实体化：`create(header)` 不写入任何内容并返回持有的写句柄，句柄的第一次 `append` 通过无覆盖发布写入并 `fsync` 编码后的 header 与第一批——因此已创建但从未 append 的会话不留下任何磁盘内容，除非其所有者调用 `handle.flush()`，以无事件的单个 header 帧发布它。后续每个批次追加行或一个压缩帧，并在 append 完成前 `fsync`；捕获到写入或同步失败时把文件回滚到之前的字节长度。已提交事件绝不重写。崩溃后，已存储日志保留被中断的最终轮次——已提交前缀中的每条记录都保留下来，由执行恢复的读方通过其写句柄追加合成 closer。撕裂尾部——不完整的最后一行，或撕裂的最后一帧——绝不返回给读取方并被整体丢弃，在写句柄的第一次新 append 之前被持久截断，因为其自身的 append 从未成功返回，其中没有任何内容被确认为已持久；已提交前缀中的校验和、解压或结构失败以损坏拒绝。
 
 ### 读取日志
 
-`inspect(id)` 返回带精确继承切点的不可变平衡视图，不提交恢复。`readFrom(id, fromOffset)` 接受 `SessionLogOffset`，返回该偏移及之后的已存储事件，并在后缀旁保留同一切点；JSONL 这类顺序介质解析整个产物并向前跳过。仅 header 的列表读取不读事件正文即可公开 `isSeeded`。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
+`open(id, 'read')` 返回一个句柄，其 `read(offset?, length?)` 提供经过验证的连续切片；产物在有界稳定读取下按需重新扫描，因此切片绝不包含撕裂尾部。撕裂的最终 Zstandard 帧会被部分解码：其中已刷入的完整 JSONL 记录被恢复进逻辑日志，写句柄的第一次修改会截掉撕裂字节并在自己的批次之前持久重写这些恢复的记录。`open(id, 'write')` 会用已验证的存储前缀预热句柄，因此恢复的全日志读取无需在第一次 append 之前再解析一遍。一个按会话 id 与 stat 派生修订号作键的有界 memo 让紧随其后的 open 复用已解析日志——冷的观察后恢复交接只解析一次——任何本地修改都会使该 id 失效。`stat(id)` 与 `list()` 只读取 header 行并执行一次 `fs.stat`，携带 `sizeBytes` 与尽力而为的、由 stat 派生的修订号（device、inode、size、纳秒时间戳），而不解析日志。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
 -----
 
@@ -86,7 +86,7 @@ kind: "package-reference"
 
 ### 设计理念
 
-该后端是共享 [PersistenceCoordinator](../session-persistence/README.zh.md#understand-the-implementation) 之上的一层薄存储：它加载已存储记录、追加批次、提交修复，并把生命周期编排委托给协调器。其物理身份是文件修订值：device、inode、size 与纳秒时间戳标识一份日志，并在追加或修复后改变，这正是 `listSnapshots` 与保留准备结果校验所使用的身份。
+该后端拥有自己完整的存储运行时（`src/storage.ts`）：`JsonlSessionHandle` 承载逐句柄修改链、带固定批处理窗口与 single-flight 排空的已路由实时事件缓冲、单调读取与幂等 close；一个 tracker 持有进程内单写者认领、teardown 清扫所遍历的打开句柄集合，以及后端自己的会话监听器所路由进的已创建但未实体化待定会话。本包有意只暴露默认插件导出与配置类型——具体类不是具名导出，因此消费方只耦合 `ctx.sessionPersistence`，其可观察行为由共享 seam 测试套件（`runPersistenceContract`/`runLiveWritePathContract`）钉住。其变更令牌是尽力而为的文件修订值：device、inode、size 与纳秒时间戳标识一份日志，供 `stat`/`list` 以及在并发 append 撕裂读取时重试的稳定读取循环使用。
 
 ### 物理编码
 
@@ -96,7 +96,8 @@ kind: "package-reference"
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：`Config` schema、后端类、协调器接线 |
+| [`src/index.ts`](src/index.ts) | 插件入口：`Config` schema、后端服务类与文件存储原语 |
+| [`src/storage.ts`](src/storage.ts) | JSONL 句柄、已路由实时事件缓冲、进程内写入者记账、监听器、teardown |
 | [`src/format.ts`](src/format.ts) | 日志路径派生、header 编码、记录扫描、打包行布局 |
 | [`src/zstd.ts`](src/zstd.ts) | Zstandard 帧压缩、解码与帧扫描 |
 | [`src/win32.ts`](src/win32.ts) | Windows write-through 发布与目录创建 |
@@ -146,7 +147,7 @@ JSONL 存储不修改实时请求前缀。只有重建历史、当前 envelope 
 - **平铺文件存储布局不加载**——加载前使用独立根，或将预发布产物移入项目/会话目录布局。
 - **压缩文件不能直接按行读取**——使用后端加载；或在写入新根前选择 `compression: 'none'`，供外部行读取方使用。
 - **不删除会话文件**——日志在 `root` 下累积，直到外部移除；seam 无删除接口。
-- **每会话一个活动写入方**——append 与修复只在所属后端实例内协调；在该所有者达到完全停稳的 dispose 前，另一实例或进程不得写入同一会话。
+- **每会话一个活动写入方，仅限进程内**——写句柄认领只在所属后端实例内排除第二个写入方；在该句柄关闭前，另一实例或进程不得写入同一会话（持久的跨进程租约是该 seam 计划中的下一层）。
 - **POSIX 实体化需要硬链接支持**——第一次 append 使用 `link()`，使同 id 竞态失败而不覆盖已提交日志；Windows 使用无替换 write-through rename。
 
 <a id="dev-note"></a>
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 8ccebf0be0..32b6b01295 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -1,8 +1,8 @@
 /**
  * JSONL durable session-persistence backend. It stores a header and contiguous
- * events in one append-only file per session, and delegates orchestration to
- * {@link PersistenceCoordinator}. Its side-effect-free locator returns the
- * absolute per-session log target before materialization.
+ * events in one append-only file per session and serves the handle-based
+ * `SessionPersistence` API: `create`/`open` return per-session handles, and
+ * every read validates the same fail-closed storage contract.
  * @module @deepseek-ai/dsh-session-persistence-jsonl
  */
 
@@ -15,23 +15,19 @@ import { performance } from 'node:perf_hooks'
 import { scheduler } from 'node:timers/promises'
 import { randomBytes } from 'node:crypto'
 import {
-  DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS,
-  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator, SessionFormatUnsupportedError,
-  type BorrowedSessionSource,
-  type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
-  type SessionEventSuffix, type SessionInspection,
-  type SessionPersistenceRevision as PersistenceRevision, type SessionRawArtifact,
-  type SessionStorageMetadata,
-  type StoredPrefix,
+  SessionPersistence, SessionPersistenceRevision, SessionFormatUnsupportedError,
+  SessionPersistenceCorruptionError,
+  SessionAlreadyExistsError, SessionPersistenceNotFoundError,
+  assertStoredId, assertVersion, materializeCreateHeader, validateStoredEvents,
+  type SessionAccess, type SessionHandle,
+  type SessionLocation, type SessionPersistenceCreateOptions,
+  type SessionPersistenceListOptions, type SessionPersistenceOpenOptions,
+  type SessionPersistenceSnapshot, type SessionPersistenceStatOptions,
+  type SessionPersistenceRevision as PersistenceRevision,
 } from '@deepseek-ai/dsh-session-persistence'
-import type {
-  Session,
-  SessionEvent,
-  SessionId,
-  SessionHeader,
-  SessionLogOffset,
-  SessionPreparation,
-} from '@deepseek-ai/dsh-session'
+import { JsonlBackendTracker, JsonlSessionHandle } from './storage.ts'
+import { SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId, SessionHeader, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
 import {
   encodeSegment, eventLines, logPath, logSuffix, parseHeader, parseHeaderMeta, projectDir, scanLog, sessionDir,
   SessionLogScanner, toHeaderLine,
@@ -44,6 +40,13 @@ import { ensureDurableDirectoryWin32, publishNewFileWin32 } from './win32.ts'
 
 export type { JsonlCompression } from './format.ts'
 
+/**
+ * Internal handoff-reuse policy, not deployment configuration: a cold
+ * observation and the resume that immediately follows it reuse one parsed
+ * log, so the memo only needs the sessions in flight between those steps.
+ */
+const COLD_LOG_MEMO_MAX_ENTRIES = 2
+
 const DEFAULT_PACK_CHUNKS = true
 const DEFAULT_COMPRESSION: JsonlCompression = 'zstd'
 /**
@@ -86,16 +89,19 @@ export interface Config {
   packChunks?: boolean
   /** Physical encoding; defaults to checksummed Zstandard frames. */
   compression?: JsonlCompression
-  /** Maximum cold Session preparations retained for history-to-resume reuse. */
-  preparedSessionCacheSize?: number
-  /** Fixed live-event coalescing window; not a backend completion deadline. */
-  writeBatchMaxDelayMs?: number
 }
 
-/** Opaque coordinator token for replacing bytes recovered from a torn frame. */
-interface JsonlTornMarker {
-  truncateTo: number
-  recoveredEvents: SessionEvent[]
+/** A parsed, validated stored log: header, logical events, and any torn-tail repair state. */
+interface StoredLog {
+  readonly meta: SessionHeader
+  /** The logical log, including any events recovered from a torn final frame. */
+  readonly events: SessionEvent[]
+  readonly tornTruncateTo: number | undefined
+  /** Complete events recovered from the torn final frame; the write path rewrites them durably. */
+  readonly recoveredTail: SessionEvent[]
+  /** Exact fork-inherited prefix length stored in the header line. */
+  readonly inheritedEventCount: SessionLogOffsetType
+  readonly revision: PersistenceRevision
 }
 
 interface FileRevisionIdentity {
@@ -106,7 +112,7 @@ interface FileRevisionIdentity {
   readonly ctimeNs: bigint
 }
 
-/** Build the source-qualified revision shared by full and lightweight reads. */
+/** Build the stat-derived best-effort change token shared by full and lightweight reads. */
 function fileRevision(identity: FileRevisionIdentity): PersistenceRevision {
   return SessionPersistenceRevision([
     identity.dev,
@@ -124,250 +130,438 @@ function isENOENT(error: unknown): boolean {
 
 /**
  * The JSONL persistence backend. Load as a plugin; it registers as
- * `ctx.sessionPersistence` and (via the coordinator) installs the write-path
- * listeners. Its torn-tail marker carries the byte offset and any events
- * recovered from an incomplete final Zstandard frame.
+ * `ctx.sessionPersistence`. Sessions materialize lazily: a created session is
+ * visible to this process immediately, reaches disk on its first append or
+ * flush, and never existed if the process crashes before that.
  */
-export class JsonlSessionPersistence extends SessionPersistence implements PersistenceBackend<JsonlTornMarker> {
-  override readonly supportsRawArtifacts = true
-
-  static inject = ['sessions']
-
+class JsonlSessionPersistence extends SessionPersistence {
   static Config: z<Config> = z.object({
     root: z.string().required(),
     packChunks: z.boolean().default(DEFAULT_PACK_CHUNKS),
     compression: JsonlCompressionSchema,
-    preparedSessionCacheSize: z.number().step(1).min(1).default(DEFAULT_PREPARED_SESSION_CACHE_SIZE),
-    writeBatchMaxDelayMs: z.number().step(1).min(1).max(MAX_WRITE_BATCH_DELAY_MS)
-      .default(DEFAULT_WRITE_BATCH_MAX_DELAY_MS),
   })
 
-  /**
-   * Backend label for coordinator diagnostics and effects. It shadows
-   * `Service.name` without changing the service key captured by the base
-   * constructor.
-   */
+  /** Backend label for diagnostics and effects; shadows `Service.name` without changing the service key. */
   override readonly name = 'session-persistence-jsonl'
 
   private root: string
   private packChunks: boolean
   private compression: JsonlCompression
-  private coordinator: PersistenceCoordinator<JsonlTornMarker>
   private rootEncodingCheck: Promise<void> | undefined
+  private readonly tracker = new JsonlBackendTracker(this.name)
+  /**
+   * Bounded LRU of parsed, validated stored logs keyed by session id and
+   * guarded by the stat-derived revision, so an immediate cold-read handoff
+   * (observation then resume) parses the artifact once. Every local mutation
+   * for an id invalidates its entry; a foreign write misses through the
+   * revision guard.
+   */
+  private readonly coldLogMemo = new Map<SessionId, StoredLog>()
 
   constructor(ctx: Context, public config: Config) {
     super(ctx)
     // Resolve once so later process.cwd() changes cannot split one backend across roots.
     this.root = resolve(config.root)
-    // Programmatic wrappers may construct the backend without Schemastery normalization.
-    const preparedSessionCacheSize = config.preparedSessionCacheSize
-      ?? DEFAULT_PREPARED_SESSION_CACHE_SIZE
-    const writeBatchMaxDelayMs = config.writeBatchMaxDelayMs
-      ?? DEFAULT_WRITE_BATCH_MAX_DELAY_MS
     this.packChunks = config.packChunks ?? DEFAULT_PACK_CHUNKS
     this.compression = config.compression ?? DEFAULT_COMPRESSION
     this.assertUsableRoot()
-    this.coordinator = new PersistenceCoordinator<JsonlTornMarker>(this.ctx, this, {
-      preparedSessionCacheSize,
-      writeBatchMaxDelayMs,
-    })
-  }
-
-  // Each backend keeps the typed service API beside its storage hooks;
-  // extracting these trivial forwards would add an inheritance layer.
-  /* jscpd:ignore-start */
-  // --- SessionPersistence service API (delegated to the coordinator) ---
-
-  /** Resolve the absolute target path without touching the filesystem. */
-  locate(meta: SessionHeader): SessionLocation {
-    return { kind: 'jsonl', path: logPath(this.root, meta.cwd, meta.id, this.compression) }
-  }
-
-  create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void> {
-    return this.coordinator.create(meta, inheritedEventCount)
-  }
-
-  override ensureMaterialized(session: Session): Promise<void> {
-    return this.coordinator.ensureMaterialized(session)
-  }
-
-  append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
-    return this.coordinator.append(id, events)
-  }
-
-  override prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation> {
-    return this.coordinator.prepare(id, signal)
-  }
-
-  load(id: SessionId): Promise<SessionInspection> {
-    return this.coordinator.load(id)
-  }
-
-  inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection> {
-    return this.coordinator.inspect(id, signal)
-  }
-
-  override borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource> {
-    return this.coordinator.borrowSession(id, signal)
-  }
-
-  // JSONL is sequential media: no loadStoredFrom hook, so the coordinator
-  // parses the stored prefix (both encodings) and skips forward to fromSeq.
-  readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix> {
-    return this.coordinator.readFrom(id, fromSeq, signal)
-  }
-
-  // One method serves both public `list` and the backend hook; delegating it to
-  // the coordinator would call this hook recursively.
-
-  /* jscpd:ignore-end */
-  // --- PersistenceBackend hooks (the file-bytes storage primitives) ---
-
-  /** Read a stored prefix by id across all project directories when cwd is unknown. */
-  async loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<JsonlTornMarker> | undefined> {
-    signal?.throwIfAborted()
-    await this.ensureRootEncoding()
-    signal?.throwIfAborted()
-    const path = await this.findLog(id, signal)
-    if (path === undefined) return undefined
-    return this.readPrefix(path, id, signal)
+    this.tracker.install(ctx)
   }
 
   /**
-   * Read one log's stat-derived revision without loading its event bytes.
-   * Resolving an id with unknown cwd still scans the project directories.
+   * Refusal-diagnostics hook: the absolute target path, without touching the filesystem.
+   * @param meta - the stored header naming the session and its cwd.
+   * @returns the artifact kind and absolute path.
    */
-  async readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<PersistenceRevision | undefined> {
-    signal?.throwIfAborted()
+  private locate(meta: SessionHeader): SessionLocation {
+    return { kind: 'jsonl', path: logPath(this.root, meta.cwd, meta.id, this.compression) }
+  }
+
+  // --- SessionPersistence service API ---
+
+  /**
+   * Create a new stored session and take its write ownership. The session is
+   * visible to this process immediately; the physical artifact appears on the
+   * first append or flush.
+   * @param header - the immutable header to store; must be losslessly
+   *   JSON-serializable with a non-negative safe-integer `createdAt`.
+   * @param options - optional cancellation.
+   * @returns the owned write handle.
+   */
+  async create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle> {
+    options?.signal?.throwIfAborted()
+    const snapshot = materializeCreateHeader(header)
+    // Fail fast on a seeded/cut mismatch with the exact refusal the header
+    // line encoder enforces at materialization.
+    toHeaderLine(snapshot, options?.inheritedEventCount)
+    const inheritedEventCount = SessionLogOffset(options?.inheritedEventCount ?? 0)
     await this.ensureRootEncoding()
-    signal?.throwIfAborted()
-    const path = await this.findLog(id, signal)
+    options?.signal?.throwIfAborted()
+    if (this.tracker.hasPending(snapshot.id) || await this.findLog(snapshot.id, options?.signal) !== undefined) {
+      throw new SessionAlreadyExistsError(snapshot.id)
+    }
+    options?.signal?.throwIfAborted()
+    this.tracker.registerCreated(snapshot, inheritedEventCount)
+    return this.tracker.adopt(new JsonlSessionHandle(this, snapshot.id, snapshot, 'write', { cursor: 0, materialized: false, inheritedEventCount }))
+  }
+
+  /**
+   * Open an existing stored session for `read` or single-writer `write`.
+   * @param id - the stored session to open.
+   * @param access - `read` (no ownership) or `write` (atomic in-process claim).
+   * @param options - optional cancellation.
+   * @returns the open handle.
+   */
+  async open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle> {
+    options?.signal?.throwIfAborted()
+    await this.ensureRootEncoding()
+    options?.signal?.throwIfAborted()
+    const pending = this.tracker.pendingOf(id)
+    if (access === 'read') {
+      if (pending !== undefined) {
+        return this.tracker.adopt(new JsonlSessionHandle(this, id, pending.header, 'read', { cursor: 0, materialized: false, inheritedEventCount: pending.inheritedEventCount }))
+      }
+      // Header-only existence and identity check: reads scan the log on demand.
+      const snapshot = await this.stat(id, options)
+      if (snapshot === undefined) {
+        // stat() reports an artifact whose header it cannot parse as absent so
+        // listing can skip foreign junk, but a physically present log must
+        // refuse loudly here — a newer-format log's user must see "upgrade the
+        // harness", never "not found".
+        const stored = await this.requireStoredLog(id, options?.signal)
+        // The full read succeeded after the header-only read failed (a writer
+        // completed the header in between): serve the session.
+        return this.tracker.adopt(new JsonlSessionHandle(this, id, stored.meta, 'read', { cursor: 0, materialized: true, inheritedEventCount: stored.inheritedEventCount }))
+      }
+      // A stored foreign format version is refused at open, matching the
+      // refusal every read of this handle would produce.
+      assertVersion(snapshot.header, this.locate(snapshot.header))
+      return this.tracker.adopt(new JsonlSessionHandle(this, id, snapshot.header, 'read', { cursor: 0, materialized: true, inheritedEventCount: snapshot.inheritedEventCount }))
+    }
+    // A pending entry always belongs to an ACTIVE creator handle (close erases
+    // it), so the claim below rejects that case as already owned.
+    this.tracker.claimWrite(id)
+    try {
+      const stored = await this.requireStoredLog(id, options?.signal)
+      return this.tracker.adopt(new JsonlSessionHandle(this, id, stored.meta, 'write', {
+        cursor: stored.events.length,
+        materialized: true,
+        tornTruncateTo: stored.tornTruncateTo,
+        recoveredTail: stored.recoveredTail,
+        inheritedEventCount: stored.inheritedEventCount,
+        primed: stored.events,
+      }))
+    } catch (error) {
+      this.tracker.releaseClaim(id)
+      throw error
+    }
+  }
+
+  /**
+   * Flush every active write handle in one durability barrier; see the seam
+   * contract.
+   * @returns resolution once every write handle active at the call has flushed.
+   */
+  flush(): Promise<void> {
+    return this.tracker.flushAll()
+  }
+
+  /**
+   * Observe one stored session without reading its event log.
+   * @param id - the stored session to observe.
+   * @param options - optional cancellation.
+   * @returns the snapshot (`sizeBytes` carries the physical artifact size), or
+   *   `undefined` when the session does not exist.
+   */
+  async stat(
+    id: SessionId,
+    options?: SessionPersistenceStatOptions,
+  ): Promise<(SessionPersistenceSnapshot & { inheritedEventCount: SessionLogOffsetType }) | undefined> {
+    options?.signal?.throwIfAborted()
+    await this.ensureRootEncoding()
+    options?.signal?.throwIfAborted()
+    const pending = this.tracker.pendingOf(id)
+    if (pending !== undefined) {
+      return { header: pending.header, revision: pending.revision, inheritedEventCount: pending.inheritedEventCount }
+    }
+    const path = await this.findLog(id, options?.signal)
     if (path === undefined) return undefined
+    let first: string | undefined
+    try {
+      first = this.compression === 'zstd'
+        ? await this.readFirstZstdLine(path, options?.signal)
+        : await this.readFirstLine(path, options?.signal)
+    } catch (error: unknown) {
+      options?.signal?.throwIfAborted()
+      // The artifact vanished between discovery and the header read: absent.
+      if (isENOENT(error)) return undefined
+      throw error
+    }
+    options?.signal?.throwIfAborted()
+    if (first === undefined) return undefined // empty/half-written file
+    let stored
+    try {
+      stored = parseHeader(first)
+    } catch (error: unknown) {
+      // A foreign-version refusal from the raw header line names the artifact
+      // it refused, matching the refusal a full read would produce.
+      if (error instanceof SessionFormatUnsupportedError) {
+        throw new SessionFormatUnsupportedError(`${error.message} (raw log: ${path})`, { kind: 'jsonl', path })
+      }
+      throw error
+    }
+    if (stored === undefined) return undefined
+    const meta = stored.meta
+    await this.assertStoredIdentity(path, meta, id, options?.signal)
     try {
       const identity = await stat(path, { bigint: true })
-      signal?.throwIfAborted()
-      return fileRevision(identity)
+      options?.signal?.throwIfAborted()
+      return {
+        header: meta,
+        revision: fileRevision(identity),
+        sizeBytes: Number(identity.size),
+        inheritedEventCount: stored.inheritedEventCount,
+      }
     } catch (error: unknown) {
-      signal?.throwIfAborted()
+      options?.signal?.throwIfAborted()
       if (isENOENT(error)) return undefined
       throw error
     }
   }
 
   /**
-   * Read a session's stored artifact text verbatim: the durable file bytes
-   * decoded from this backend's physical encoding (complete zstd frames
-   * concatenated, or UTF-8 plaintext). The content is the exact JSONL text the
-   * backend wrote — never a reconstruction from parsed events — so packed-
-   * chunk rows, key order, and line breaks survive byte-for-byte. A torn
-   * final frame is omitted, matching the committed-prefix semantics of every
-   * other read.
-   * @param id - the persisted session to read.
-   * @param signal - optional cancellation for the stat/read/decode work.
-   * @returns the raw artifact text plus the header parsed from its own first
-   * line, or `undefined` when the session has no stored artifact.
+   * List every stored session visible to this process: materialized artifacts
+   * plus this process's created-but-unmaterialized sessions.
+   * @param options - optional cancellation.
+   * @returns one snapshot per session, in no promised order.
    */
-  override async readRaw(id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined> {
-    signal?.throwIfAborted()
-    await this.ensureRootEncoding()
-    signal?.throwIfAborted()
-    const path = await this.findLog(id, signal)
-    if (path === undefined) return undefined
-    const { buffer } = await this.readStableFile(path, signal)
-    let content: string
-    if (this.compression === 'zstd') {
-      const { frames } = scanZstdFrames(buffer)
-      if (frames.length === 0) throw new Error('empty or header-less Zstandard session log')
-      const decoder = createZstdFrameDecoder()
-      const plaintexts: Buffer[] = []
-      // The decoder yields views into a reused buffer; copy each frame's
-      // plaintext immediately so a later concat cannot read overwritten memory.
-      for (const plaintext of decoder.decode(buffer, frames)) {
+  async list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]> {
+    const signal = options?.signal
+    const snapshots: SessionPersistenceSnapshot[] = []
+    const listed = new Set<SessionId>()
+    // Snapshot pending entries BEFORE scanning storage: a session whose first
+    // append lands mid-scan is then still in this snapshot (its artifact may
+    // predate the scan), so create-to-list visibility never has a hole.
+    const pending = [...this.tracker.pendingEntries()]
+    for (const artifact of await this.listArtifacts(signal)) {
+      signal?.throwIfAborted()
+      try {
+        const identity = await stat(artifact.path, { bigint: true })
         signal?.throwIfAborted()
-        plaintexts.push(Buffer.from(plaintext))
+        listed.add(artifact.header.id)
+        snapshots.push({
+          header: artifact.header,
+          revision: fileRevision(identity),
+          sizeBytes: Number(identity.size),
+        })
+      } catch (error: unknown) {
+        signal?.throwIfAborted()
+        if (!isENOENT(error)) throw error
       }
-      content = Buffer.concat(plaintexts).toString('utf8')
-    } else {
-      content = buffer.toString('utf8')
     }
-    const storage = parseHeader(content.split('\n', 1)[0] as string)
-    if (storage === undefined || storage.meta.id !== id) {
-      throw new Error(`corrupt session log: invalid header line in "${path}"`)
+    for (const [id, entry] of pending) {
+      if (!listed.has(id)) snapshots.push({ header: entry.header, revision: entry.revision })
     }
-    // The logical artifact name is `session.jsonl` regardless of the physical
-    // encoding suffix (`.jsonl.zstd` marks compression only).
-    return { ...storage, filename: 'session.jsonl', content }
+    signal?.throwIfAborted()
+    return snapshots
+  }
+
+  // --- handle-facing storage internals (package-private via the handle class below) ---
+
+  /** Resolve and read one stored log, refusing loudly when the artifact is absent. */
+  private async requireStoredLog(id: SessionId, signal?: AbortSignal): Promise<StoredLog> {
+    const path = await this.findLog(id, signal)
+    if (path === undefined) throw new SessionPersistenceNotFoundError(id)
+    return this.readStoredLog(path, id, signal)
   }
 
   /**
-   * Read a file's bytes under a revision-stable loop: a writer appending
-   * between stat and readFile would yield a torn physical file, so retry
-   * while the stat revision changes.
+   * Read, parse, and validate one stored log as the current logical prefix.
+   * @param path - the artifact file to read.
+   * @param expectedId - the session identity the artifact must carry.
+   * @param signal - optional cancellation for the stat/read/decode work.
+   * @returns the validated stored log with any torn-tail truncation point.
+   */
+  async readStoredLog(path: string, expectedId: SessionId, signal?: AbortSignal): Promise<StoredLog> {
+    signal?.throwIfAborted()
+    const probe = fileRevision(await stat(path, { bigint: true }))
+    const memoized = this.coldLogMemo.get(expectedId)
+    if (memoized !== undefined && memoized.revision === probe) {
+      this.coldLogMemo.delete(expectedId)
+      this.coldLogMemo.set(expectedId, memoized)
+      return memoized
+    }
+    const { buffer, revision } = await this.readStableFile(path, signal)
+    let parsed: {
+      meta: SessionHeader
+      inheritedEventCount: SessionLogOffsetType
+      events: SessionEvent[]
+      tornTruncateTo: number | undefined
+      recoveredTail: SessionEvent[]
+    }
+    try {
+      if (this.compression === 'zstd') {
+        parsed = await this.readZstdPrefix(buffer, signal)
+      } else {
+        signal?.throwIfAborted()
+        const { meta, inheritedEventCount, events, committedBytes } = scanLog(buffer)
+        signal?.throwIfAborted()
+        parsed = {
+          meta,
+          inheritedEventCount,
+          events,
+          tornTruncateTo: committedBytes < buffer.byteLength ? committedBytes : undefined,
+          // A torn raw tail is one incomplete JSONL line; it holds no complete
+          // record to recover.
+          recoveredTail: [],
+        }
+      }
+    } catch (error: unknown) {
+      signal?.throwIfAborted()
+      // A parse-time format refusal predates any SessionHeader, so attach the
+      // artifact this read actually refused; every other parse failure is
+      // committed bytes the decoder cannot interpret — damage, classified for
+      // the seam's stable error vocabulary.
+      if (error instanceof SessionFormatUnsupportedError) {
+        throw new SessionFormatUnsupportedError(`${error.message} (raw log: ${path})`, { kind: 'jsonl', path })
+      }
+      throw new SessionPersistenceCorruptionError(`session "${expectedId}": stored log is corrupt: ${String(error)} (raw log: ${path})`, { cause: error })
+    }
+    signal?.throwIfAborted()
+    await this.assertStoredIdentity(path, parsed.meta, expectedId, signal)
+    signal?.throwIfAborted()
+    assertStoredId(expectedId, parsed.meta)
+    const location = this.locate(parsed.meta)
+    assertVersion(parsed.meta, location)
+    validateStoredEvents(parsed.meta, parsed.events, location)
+    const stored: StoredLog = { ...parsed, revision }
+    this.coldLogMemo.delete(expectedId)
+    this.coldLogMemo.set(expectedId, stored)
+    for (const oldest of this.coldLogMemo.keys()) {
+      if (this.coldLogMemo.size <= COLD_LOG_MEMO_MAX_ENTRIES) break
+      this.coldLogMemo.delete(oldest)
+    }
+    return stored
+  }
+
+  /**
+   * Resolve a session's unique log path.
+   * @param id - the stored session to locate.
+   * @param signal - optional cancellation for the directory scans.
+   * @returns the artifact path, or `undefined` when absent.
+   */
+  async resolveLog(id: SessionId, signal?: AbortSignal): Promise<string | undefined> {
+    await this.ensureRootEncoding()
+    signal?.throwIfAborted()
+    return this.findLog(id, signal)
+  }
+
+  /**
+   * Durably append one validated batch; lazily materializes on the first write.
+   * @param header - the session's stored header.
+   * @param events - the validated contiguous batch, in seq order.
+   * @param isMaterialized - whether the session already has a durable artifact.
+   * @param inheritedEventCount - the exact fork-inherited prefix length written into a materializing header line.
+   */
+  async persistBatch(
+    header: SessionHeader,
+    events: readonly SessionEvent[],
+    isMaterialized: boolean,
+    inheritedEventCount: SessionLogOffsetType,
+  ): Promise<void> {
+    this.coldLogMemo.delete(header.id)
+    await this.ensureRootEncoding()
+    if (isMaterialized) {
+      await this.appendLines(header, events)
+    } else {
+      await this.materialize(header, inheritedEventCount, events)
+      this.tracker.materialized(header.id)
+    }
+  }
+
+  /**
+   * Materialize a header-only artifact for an explicitly durable empty session.
+   * @param header - the session's stored header.
+   * @param inheritedEventCount - the exact fork-inherited prefix length written into the header line.
+   */
+  async persistHeader(header: SessionHeader, inheritedEventCount: SessionLogOffsetType): Promise<void> {
+    this.coldLogMemo.delete(header.id)
+    await this.ensureRootEncoding()
+    await this.materialize(header, inheritedEventCount, [])
+    this.tracker.materialized(header.id)
+  }
+
+  /**
+   * Truncate a torn physical tail durably before this session's first new append.
+   * @param header - the session's stored header.
+   * @param truncateTo - the byte offset the artifact is truncated to.
+   */
+  async truncateTornTail(header: SessionHeader, truncateTo: number): Promise<void> {
+    this.coldLogMemo.delete(header.id)
+    await this.repair(header, truncateTo)
+    this.ctx.logger.warn(`${this.name}: session "${header.id}" recovered from a torn tail; incomplete tail bytes were discarded`)
+  }
+
+  /**
+   * Whether this process still tracks a created-but-unmaterialized session.
+   * @param id - the session to test.
+   * @returns true while the pending entry exists.
+   */
+  hasPendingSession(id: SessionId): boolean {
+    return this.tracker.hasPending(id)
+  }
+
+  /**
+   * Release one handle's backend bookkeeping on close.
+   * @param handle - the closing handle.
+   * @param materialized - whether the session reached durable storage.
+   */
+  releaseHandle(handle: JsonlSessionHandle, materialized: boolean): void {
+    this.tracker.release(handle, materialized)
+  }
+
+  /**
+   * Read a file's bytes with one bounded stability retry: a writer appending
+   * between stat and readFile yields a torn read, so a changed revision
+   * triggers exactly one re-read. A second change does not loop — the log is
+   * append-only, so the bytes at the retry's own pre-read stat size are a
+   * committed prefix, and the decoders treat anything past a torn cut as
+   * unwritten. A continuous writer therefore delays a read by at most one
+   * extra whole-file read instead of starving it.
    * @param path - the artifact file to read.
    * @param signal - optional cancellation for the stat/read work.
-   * @returns the stable bytes and the revision that matched both stats.
+   * @returns the stable bytes (or the committed prefix) and their revision.
    */
   private async readStableFile(
     path: string,
     signal?: AbortSignal,
   ): Promise<{ buffer: Buffer; revision: PersistenceRevision }> {
-    for (;;) {
-      signal?.throwIfAborted()
-      const before = fileRevision(await stat(path, { bigint: true }))
+    signal?.throwIfAborted()
+    let identity = await stat(path, { bigint: true })
+    for (let attempt = 0; ; attempt += 1) {
+      const before = fileRevision(identity)
       const buffer = await readFile(path, { signal })
       signal?.throwIfAborted()
-      const after = fileRevision(await stat(path, { bigint: true }))
-      if (before === after) return { buffer, revision: after }
-    }
-  }
-
-  /**
-   * Read a stored prefix and convert torn-tail state to the opaque marker the
-   * coordinator can round-trip without knowing the physical encoding.
-   */
-  private async readPrefix(
-    path: string,
-    expectedId?: SessionId,
-    signal?: AbortSignal,
-  ): Promise<StoredPrefix<JsonlTornMarker>> {
-    const { buffer, revision } = await this.readStableFile(path, signal)
-    let prefix: Omit<StoredPrefix<JsonlTornMarker>, 'revision'>
-    try {
-      if (this.compression === 'zstd') {
-        prefix = await this.readZstdPrefix(buffer, signal)
-      } else {
-        signal?.throwIfAborted()
-        const { meta, inheritedEventCount, events, committedBytes } = scanLog(buffer)
-        signal?.throwIfAborted()
-        prefix = {
-          meta,
-          inheritedEventCount,
-          events,
-          ...committedBytes < buffer.byteLength
-            ? { tornMarker: { truncateTo: committedBytes, recoveredEvents: [] } }
-            : {},
-        }
+      const after = await stat(path, { bigint: true })
+      if (before === fileRevision(after)) return { buffer, revision: before }
+      if (attempt === 1) {
+        return { buffer: buffer.subarray(0, Number(identity.size)), revision: before }
       }
-    } catch (error: unknown) {
-      // A parse-time format refusal predates any SessionHeader, so the
-      // coordinator's locate-based enrichment cannot run; attach the artifact
-      // this read actually refused.
-      if (error instanceof SessionFormatUnsupportedError && error.location === undefined) {
-        throw new SessionFormatUnsupportedError(`${error.message} (raw log: ${path})`, { kind: 'jsonl', path })
-      }
-      throw error
+      identity = after
     }
-    signal?.throwIfAborted()
-    await this.assertStoredIdentity(path, prefix.meta, expectedId, signal)
-    signal?.throwIfAborted()
-    return { ...prefix, revision }
   }
 
   /** Decode complete frames and retain complete JSONL records from a torn final frame. */
   private async readZstdPrefix(
     buffer: Buffer,
     signal?: AbortSignal,
-  ): Promise<Omit<StoredPrefix<JsonlTornMarker>, 'revision'>> {
+  ): Promise<{
+    meta: SessionHeader
+    inheritedEventCount: SessionLogOffsetType
+    events: SessionEvent[]
+    tornTruncateTo: number | undefined
+    recoveredTail: SessionEvent[]
+  }> {
     signal?.throwIfAborted()
     const { frames, tornStart } = scanZstdFrames(buffer)
     signal?.throwIfAborted()
@@ -407,9 +601,13 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
           meta: prefix.meta,
           inheritedEventCount: prefix.inheritedEventCount,
           events: prefix.events,
+          tornTruncateTo: undefined,
+          recoveredTail: [],
         }
       }
-
+      // A torn final frame's append never resolved, but complete JSONL records
+      // already flushed into it are real emitted events: recover them, and let
+      // the write path truncate the torn bytes and rewrite them durably.
       let recoveredPlaintext: Buffer = Buffer.alloc(0)
       try {
         signal?.throwIfAborted()
@@ -417,21 +615,18 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
       } catch {
         /* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
         if (signal?.aborted) signal.throwIfAborted()
-        // A structurally incomplete final frame may end before Node's decoder can
-        // emit any plaintext; the complete prior frames remain recoverable.
+        // A structurally incomplete final frame may end before Node's decoder
+        // can emit any plaintext; the complete prior frames remain recoverable.
       }
       signal?.throwIfAborted()
       scanner.write(recoveredPlaintext)
-      const recoveredPrefix = scanner.finish()
-      signal?.throwIfAborted()
+      const prefix = scanner.finish()
       return {
-        meta: recoveredPrefix.meta,
-        inheritedEventCount: recoveredPrefix.inheritedEventCount,
-        events: recoveredPrefix.events,
-        tornMarker: {
-          truncateTo: tornStart,
-          recoveredEvents: recoveredPrefix.events.slice(complete.eventCount),
-        },
+        meta: prefix.meta,
+        inheritedEventCount: prefix.inheritedEventCount,
+        events: prefix.events,
+        tornTruncateTo: tornStart,
+        recoveredTail: prefix.events.slice(complete.eventCount),
       }
     } catch (error) {
       /* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
@@ -442,68 +637,6 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
     }
   }
 
-  /** Durably append a batch, lazily materializing the file when not yet present. */
-  async appendBatch(
-    storage: SessionStorageMetadata,
-    events: readonly SessionEvent[],
-    isMaterialized: boolean,
-  ): Promise<void> {
-    await this.ensureRootEncoding()
-    if (isMaterialized) {
-      await this.appendLines(storage.meta, events)
-    } else {
-      await this.materialize(storage, events)
-    }
-  }
-
-  /** Materialize a header-only JSONL artifact for an explicitly durable empty session. */
-  async materializeHeader(storage: SessionStorageMetadata): Promise<void> {
-    await this.materialize(storage, [])
-  }
-
-  /**
-   * Make a crash repair durable: truncate a torn tail, restore complete events
-   * decoded from it, then append synthetic closers. Two fsync'd steps — the seam
-   * does not require this to be atomic.
-   */
-  async commitRepair(
-    storage: SessionStorageMetadata,
-    tornMarker: JsonlTornMarker | undefined,
-    closers: readonly SessionEvent[],
-  ): Promise<void> {
-    const { meta } = storage
-    if (tornMarker !== undefined) await this.repair(meta, tornMarker.truncateTo)
-    const repairedEvents = [...(tornMarker?.recoveredEvents ?? []), ...closers]
-    if (repairedEvents.length > 0) await this.appendLines(meta, repairedEvents)
-    if (tornMarker !== undefined) this.ctx.logger.warn(`${this.name}: session "${meta.id}" recovered from a torn tail; incomplete tail bytes were discarded`)
-  }
-
-  /** List valid unique stored sessions' metadata (header line only — no full-log parse). */
-  async list(signal?: AbortSignal): Promise<SessionHeader[]> {
-    return (await this.listArtifacts(signal)).map(artifact => artifact.header)
-  }
-
-  /** List metadata plus a stat-derived identity for each append-only log. */
-  async listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]> {
-    const snapshots: SessionPersistenceSnapshot[] = []
-    for (const artifact of await this.listArtifacts(signal)) {
-      signal?.throwIfAborted()
-      try {
-        const identity = await stat(artifact.path, { bigint: true })
-        signal?.throwIfAborted()
-        snapshots.push({
-          header: artifact.header,
-          revision: fileRevision(identity),
-        })
-      } catch (error: unknown) {
-        signal?.throwIfAborted()
-        if (!isENOENT(error)) throw error
-      }
-    }
-    signal?.throwIfAborted()
-    return snapshots
-  }
-
   private async listArtifacts(signal?: AbortSignal): Promise<Array<{ header: SessionHeader; path: string }>> {
     signal?.throwIfAborted()
     await this.ensureRootEncoding()
@@ -528,7 +661,15 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
           : await this.readFirstLine(path, signal)
         signal?.throwIfAborted()
         if (first === undefined) continue // empty/half-written file
-        const meta = parseHeaderMeta(first)
+        let meta: SessionHeader | undefined
+        try {
+          meta = parseHeaderMeta(first)
+        } catch (error: unknown) {
+          // Listing skips an unreadable (foreign-version) header instead of
+          // failing the whole list; opening that id still refuses loudly.
+          if (error instanceof SessionFormatUnsupportedError) continue
+          throw error
+        }
         if (meta === undefined) continue // not a session header
         await this.assertStoredIdentity(path, meta, undefined, signal)
         signal?.throwIfAborted()
@@ -546,13 +687,16 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
   // --- materialization / append / repair (file mechanics) ---
 
   /** Atomically write the header line + first batch (temp-write, fsync, publish). */
-  private async materialize(storage: SessionStorageMetadata, events: readonly SessionEvent[]): Promise<void> {
-    const { meta } = storage
+  private async materialize(
+    meta: SessionHeader,
+    inheritedEventCount: SessionLogOffsetType,
+    events: readonly SessionEvent[],
+  ): Promise<void> {
     const project = projectDir(this.root, meta.cwd)
     const dir = sessionDir(this.root, meta.cwd, meta.id)
     const finalPath = logPath(this.root, meta.cwd, meta.id, this.compression)
     await this.rejectOppositeArtifact(meta.cwd, meta.id)
-    const content = await this.encodeMaterialization(storage, events)
+    const content = await this.encodeMaterialization(meta, inheritedEventCount, events)
     /* v8 ignore next -- native Windows coverage exercises this platform dispatch; Linux covers the POSIX peer */
     if (process.platform === 'win32') {
       await this.materializeWin32(project, dir, finalPath, meta.id, content)
@@ -630,12 +774,12 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
   private async rejectExistingLog(finalPath: string, id: SessionId): Promise<void> {
     // Never publish over an existing committed log: materialize is the first
     // write of a session the backend believes is new. A file here means a
-    // different session shares this id on disk — reject loudly. (createCore
-    // already guards the create path, so this is unreachable-in-practice TOCTOU
+    // different session shares this id on disk — reject loudly. (create already
+    // guards the create path, so this is unreachable-in-practice TOCTOU
     // defense.)
-    /* v8 ignore next 3 -- createCore guards collisions before materialize; this is a TOCTOU backstop */
+    /* v8 ignore next 3 -- create guards collisions before materialize; this is a TOCTOU backstop */
     if (await this.exists(finalPath)) {
-      throw new Error(`refusing to materialize "${id}": a log already exists on disk (load/resume it instead)`)
+      throw new Error(`refusing to materialize "${id}": a log already exists on disk (open it instead)`)
     }
   }
 
@@ -653,10 +797,11 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
 
   /** Encode the header and first batch without combining their frame boundaries. */
   private async encodeMaterialization(
-    storage: SessionStorageMetadata,
+    meta: SessionHeader,
+    inheritedEventCount: SessionLogOffsetType,
     events: readonly SessionEvent[],
   ): Promise<Buffer | string> {
-    const header = JSON.stringify(toHeaderLine(storage.meta, storage.inheritedEventCount)) + '\n'
+    const header = JSON.stringify(toHeaderLine(meta, meta.isSeeded ? inheritedEventCount : undefined)) + '\n'
     if (events.length === 0) {
       return this.compression === 'none' ? header : compressZstdFrame(header)
     }
@@ -1009,4 +1154,10 @@ export class JsonlSessionPersistence extends SessionPersistence implements Persi
   /* v8 ignore stop */
 }
 
+/**
+ * One open channel onto a JSONL-stored session: the shared storage-handle
+ * scaffolding over this backend's file primitives. Reads re-scan the artifact
+ * under the stable-read loop.
+ */
+
 export default JsonlSessionPersistence
diff --git a/packages/session/session-persistence-jsonl/src/storage.ts b/packages/session/session-persistence-jsonl/src/storage.ts
new file mode 100644
index 0000000000..936355260f
--- /dev/null
+++ b/packages/session/session-persistence-jsonl/src/storage.ts
@@ -0,0 +1,497 @@
+/**
+ * The JSONL provider's session storage runtime: its concrete write/read
+ * handle with a per-handle mutation chain and a routed live write-behind
+ * buffer, the in-process bookkeeping that enforces one active writer per
+ * session id, and the backend's live event routing and teardown. Deliberately
+ * provider-local: the persistence seam exposes only the service and handle
+ * contracts, and the shared contract suites pin equivalent observable
+ * behavior across providers.
+ * @module
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { errorChain } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import {
+  assertContiguous,
+  materializeAppendBatch,
+  SessionAlreadyExistsError,
+  SessionAlreadyOwnedError,
+  SessionHandleClosedError,
+  SessionPersistenceNotFoundError,
+  SessionPersistenceRevision,
+  SessionReadOnlyError,
+} from '@deepseek-ai/dsh-session-persistence'
+import type {
+  SessionAccess,
+  SessionHandle,
+  SessionHandleAppendOptions,
+  SessionHandleFlushOptions,
+  SessionHandleReadOptions,
+} from '@deepseek-ai/dsh-session-persistence'
+
+/** Maximum intentional wait before a routed live session batch starts writing. */
+export const LIVE_WRITE_BATCH_MAX_DELAY_MS = 200
+
+/** The file-storage primitives the handle drives on its owning service. */
+export interface JsonlHandleStorage {
+  /** Append encoded lines; `isMaterialized` selects create-vs-extend publication. */
+  persistBatch(
+    header: SessionHeader,
+    events: readonly SessionEvent[],
+    isMaterialized: boolean,
+    inheritedEventCount: SessionLogOffset,
+  ): Promise<void>
+  /** Materialize the header-only artifact for an explicitly flushed empty session. */
+  persistHeader(header: SessionHeader, inheritedEventCount: SessionLogOffset): Promise<void>
+  /** Truncate a torn physical tail before the first new append lands. */
+  truncateTornTail(header: SessionHeader, truncateTo: number): Promise<void>
+  /** Resolve the session's artifact path, or `undefined` before materialization. */
+  resolveLog(id: SessionId, signal?: AbortSignal): Promise<string | undefined>
+  /** Read and validate the stored log at `path`. */
+  readStoredLog(path: string, expectedId: SessionId, signal?: AbortSignal): Promise<{ events: SessionEvent[] }>
+  /** Whether the id is still a created-but-unmaterialized session here. */
+  hasPendingSession(id: SessionId): boolean
+  /** Drop the handle's bookkeeping on close. */
+  releaseHandle(handle: JsonlSessionHandle, materialized: boolean): void
+}
+
+/** Mutable per-handle log state; a write handle is its session's single mutator. */
+export interface StorageHandleState {
+  /** The stored next-seq (the logical end this handle knows). */
+  cursor: number
+  /** Whether the session has a durable artifact yet. */
+  materialized: boolean
+  /** Torn-tail truncation point, consumed by the first new append. */
+  tornTruncateTo?: number | undefined
+  /** Complete events recovered from the torn final frame; the first mutation rewrites them durably. */
+  recoveredTail?: SessionEvent[] | undefined
+  /** Exact fork-inherited prefix length stored with the log; `0` when unseeded. */
+  inheritedEventCount: SessionLogOffset
+  /** The validated stored prefix from a write open, served to reads until the first append. */
+  primed?: SessionEvent[] | undefined
+}
+
+/**
+ * The JSONL session handle. Mutations serialize on a per-handle promise
+ * chain; reads re-scan the artifact on demand and never observe a shorter log
+ * than a prior read on this handle. Routed live events buffer in a bounded
+ * window and drain through the same chain as explicit appends.
+ */
+export class JsonlSessionHandle implements SessionHandle {
+  private chain: Promise<unknown> = Promise.resolve()
+  private closing: Promise<void> | undefined
+  private observedLength = 0
+  /** Routed live events awaiting their batching deadline (persistence-owned copies). */
+  private buffered: SessionEvent[] = []
+  private batchTimer: ReturnType<typeof setTimeout> | undefined
+  /** Set when a drain failed; the automatic timer stays quiet until the next drain. */
+  private drainPaused = false
+  private draining: Promise<void> | undefined
+
+  constructor(
+    private readonly storage: JsonlHandleStorage,
+    readonly id: SessionId,
+    readonly header: SessionHeader,
+    readonly access: SessionAccess,
+    private readonly state: StorageHandleState,
+  ) {}
+
+  /** Exact fork-inherited prefix length stored with this session's log. */
+  get inheritedEventCount(): SessionLogOffset {
+    return this.state.inheritedEventCount
+  }
+
+  /**
+   * Read a slice of the valid contiguous logical log; see the seam contract.
+   * @param offset - first logical seq to include (default 0).
+   * @param length - maximum events returned (default: the rest).
+   * @param options - optional cancellation.
+   * @returns the requested slice.
+   */
+  async read(offset = 0, length = Number.MAX_SAFE_INTEGER, options?: SessionHandleReadOptions): Promise<readonly SessionEvent[]> {
+    // Closed-handle refusal precedes argument validation: a closed handle
+    // rejects SessionHandleClosedError regardless of the arguments.
+    this.assertOpen('read')
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+      throw new TypeError(`read offset must be a non-negative safe integer, got ${String(offset)}`)
+    }
+    if (!Number.isSafeInteger(length) || length < 0) {
+      throw new TypeError(`read length must be a non-negative safe integer, got ${String(length)}`)
+    }
+    options?.signal?.throwIfAborted()
+    if (this.state.primed !== undefined) {
+      this.observedLength = Math.max(this.observedLength, this.state.primed.length)
+      return this.state.primed.slice(offset, offset + length)
+    }
+    // A write handle knows its own materialization; a read handle asks the
+    // backend so a writer's later materialization becomes visible here.
+    if (this.access === 'write' && !this.state.materialized) return []
+    const path = await this.storage.resolveLog(this.id, options?.signal)
+    if (path === undefined) {
+      if (this.storage.hasPendingSession(this.id)) return []
+      throw new SessionPersistenceNotFoundError(this.id)
+    }
+    const { events } = await this.storage.readStoredLog(path, this.id, options?.signal)
+    if (events.length < this.observedLength) {
+      throw new Error(`session "${this.id}": stored log shrank below a previously observed prefix (${events.length} < ${this.observedLength})`)
+    }
+    this.observedLength = events.length
+    return events.slice(offset, offset + length)
+  }
+
+  /**
+   * Durably append a contiguous batch; see the seam contract.
+   * @param events - the contiguous batch in seq order.
+   * @param options - optional cancellation observed before the write starts.
+   */
+  async append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void> {
+    this.assertOpen('append')
+    // Validate and deep-snapshot the batch HERE, before queueing behind the
+    // chain, so the checked value is exactly the value persisted.
+    const batch = materializeAppendBatch(events)
+    return this.run('append', async () => {
+      options?.signal?.throwIfAborted()
+      await this.persistContiguous(batch)
+    })
+  }
+
+  /**
+   * Durability barrier; materializes the artifact when nothing has been
+   * appended yet, so an explicitly flushed empty session survives this process.
+   * @param options - optional cancellation observed before the barrier starts.
+   */
+  flush(options?: SessionHandleFlushOptions): Promise<void> {
+    return this.run('flush', async () => {
+      options?.signal?.throwIfAborted()
+      if (this.access !== 'write') throw new SessionReadOnlyError(this.id, 'flush')
+      if (this.state.materialized) return // appends are durable on resolution
+      await this.storage.persistHeader(this.header, this.state.inheritedEventCount)
+      this.state.materialized = true
+    })
+  }
+
+  /**
+   * Release the handle; see the seam contract. Idempotent and uncancellable.
+   * A write handle first drains its routed live buffer through the still-open
+   * storage, so backend teardown loses nothing regardless of which fiber
+   * unwinds first; a drain failure still releases ownership, then rejects.
+   * @returns settlement of the release.
+   */
+  close(): Promise<void> {
+    return this.closing ??= (async () => {
+      let drainFailure: unknown
+      // Producers on other fibers may still publish while close waits for
+      // in-flight mutations (root disposal is concurrent), so drain again
+      // until a full pass leaves the routed buffer empty. The chain never
+      // rejects because run() swallows each operation's rejection after its
+      // caller observed it.
+      for (;;) {
+        try {
+          await this.drainLive()
+        } catch (error: unknown) {
+          drainFailure = error
+          break
+        }
+        await this.chain
+        if (this.buffered.length === 0) break
+      }
+      // After a drain failure the chain may still hold in-flight mutations.
+      await this.chain
+      this.storage.releaseHandle(this, this.state.materialized)
+      if (drainFailure !== undefined) {
+        throw drainFailure instanceof Error ? drainFailure : new Error(errorChain(drainFailure))
+      }
+    })()
+  }
+
+  /** `await using` support: delegates to {@link close}. */
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close()
+  }
+
+  /**
+   * Buffer one published live session event and arm the bounded batching
+   * window when it is idle. The routing installer is the only caller.
+   * @param event - the live event, retained as a persistence-owned copy.
+   * @param reportBackgroundFailure - observes a deadline-driven drain failure
+   *   (the events stay buffered; the next {@link drainLive} retries loudly).
+   */
+  enqueueLive(event: SessionEvent, reportBackgroundFailure: (error: unknown) => void): void {
+    this.buffered.push(structuredClone(event))
+    if (this.batchTimer !== undefined || this.drainPaused) return
+    this.batchTimer = setTimeout(() => {
+      this.batchTimer = undefined
+      this.drainLive().catch(reportBackgroundFailure)
+    }, LIVE_WRITE_BATCH_MAX_DELAY_MS)
+  }
+
+  /**
+   * Durably drain the routed live buffer through the mutation chain;
+   * concurrent callers join one drain, and a failure retains the batch in
+   * order so `session/flush` can retry and reject loudly.
+   */
+  drainLive(): Promise<void> {
+    return this.draining ??= this.drainBuffered().finally(() => {
+      this.draining = undefined
+    })
+  }
+
+  private async drainBuffered(): Promise<void> {
+    if (this.batchTimer !== undefined) {
+      clearTimeout(this.batchTimer)
+      this.batchTimer = undefined
+    }
+    this.drainPaused = false
+    while (this.buffered.length > 0) {
+      // Capture inside the chained turn so events landing while an earlier
+      // batch writes coalesce into the next one, in order.
+      await this.enqueueChain(async () => {
+        // Only this single-flight drain splices the buffer, so the batch the
+        // while-guard saw is still here when the chained turn runs.
+        const batch = this.buffered.splice(0)
+        try {
+          await this.persistContiguous(materializeAppendBatch(batch))
+        } catch (error: unknown) {
+          this.buffered = batch.concat(this.buffered)
+          this.drainPaused = true
+          throw error
+        }
+      })
+    }
+  }
+
+  /** The shared durable-append body: contiguity, torn-tail repair, storage write, state advance. */
+  private async persistContiguous(batch: readonly SessionEvent[]): Promise<void> {
+    if (this.access !== 'write') throw new SessionReadOnlyError(this.id, 'append')
+    if (batch.length === 0) return
+    assertContiguous(this.id, batch, this.state.cursor)
+    // Commit any pending torn-tail repair first, clearing each step's state
+    // only once it lands so a failed step retries on the next mutation:
+    // truncate the torn bytes, then durably rewrite the complete events
+    // recovered from them (already counted in the primed cursor).
+    if (this.state.tornTruncateTo !== undefined) {
+      await this.storage.truncateTornTail(this.header, this.state.tornTruncateTo)
+      this.state.tornTruncateTo = undefined
+    }
+    if (this.state.recoveredTail !== undefined) {
+      if (this.state.recoveredTail.length > 0) {
+        await this.storage.persistBatch(this.header, this.state.recoveredTail, this.state.materialized, this.state.inheritedEventCount)
+      }
+      this.state.recoveredTail = undefined
+    }
+    await this.storage.persistBatch(this.header, batch, this.state.materialized, this.state.inheritedEventCount)
+    this.state.materialized = true
+    this.state.cursor += batch.length
+    this.state.primed = undefined
+    this.observedLength = this.state.cursor
+  }
+
+  /** Serialize one operation onto the chain without the closed-handle refusal (drain-from-close). */
+  private enqueueChain(op: () => Promise<void>): Promise<void> {
+    const next = this.chain.then(op)
+    this.chain = next.catch(() => {})
+    return next
+  }
+
+  /** Serialize one public mutating operation onto this handle's chain. */
+  private async run(operation: string, op: () => Promise<void>): Promise<void> {
+    this.assertOpen(operation)
+    return this.enqueueChain(async () => {
+      this.assertOpen(operation)
+      return op()
+    })
+  }
+
+  private assertOpen(operation: string): void {
+    if (this.closing !== undefined) throw new SessionHandleClosedError(this.id, operation)
+  }
+}
+
+/** One created-but-unmaterialized session tracked in this process only. */
+export interface PendingSession {
+  readonly header: SessionHeader
+  readonly revision: SessionPersistenceRevision
+  /** Exact fork-inherited prefix length supplied at create. */
+  readonly inheritedEventCount: SessionLogOffset
+}
+
+/**
+ * The JSONL backend's in-process bookkeeping: the single active writer per
+ * session id (doubling as the live event router), the open-handle set the
+ * teardown sweep closes, and the created-but-unmaterialized sessions this
+ * process can already observe.
+ */
+export class JsonlBackendTracker {
+  /** Every open handle; teardown closes what remains. */
+  readonly openHandles = new Set<SessionHandle>()
+  /** `null` marks a claim whose handle is still being constructed. */
+  private readonly writers = new Map<SessionId, JsonlSessionHandle | null>()
+  private readonly pending = new Map<SessionId, PendingSession>()
+  private counter = 0
+
+  /** @param name - backend label used in in-memory revision tokens and teardown errors. */
+  constructor(private readonly name: string) {}
+
+  /**
+   * Claim write ownership and record the created session as pending, making
+   * it observable to this process before it materializes.
+   * @param header - the validated detached header.
+   * @param inheritedEventCount - the exact fork-inherited prefix length.
+   * @throws {SessionAlreadyExistsError} when a concurrent create or an open
+   *   write handle holds the id — for create, the duplicate is the fact.
+   */
+  registerCreated(header: SessionHeader, inheritedEventCount: SessionLogOffset): void {
+    if (this.writers.has(header.id)) throw new SessionAlreadyExistsError(header.id)
+    this.writers.set(header.id, null)
+    this.pending.set(header.id, {
+      header,
+      revision: SessionPersistenceRevision(`memory:${this.name}:${++this.counter}`),
+      inheritedEventCount,
+    })
+  }
+
+  /**
+   * Claim write ownership for an existing session.
+   * @param id - the session to claim.
+   * @throws {SessionAlreadyOwnedError} when an active write handle exists.
+   */
+  claimWrite(id: SessionId): void {
+    if (this.writers.has(id)) throw new SessionAlreadyOwnedError(id)
+    this.writers.set(id, null)
+  }
+
+  /**
+   * Roll a failed write open back.
+   * @param id - the session whose claim is dropped.
+   */
+  releaseClaim(id: SessionId): void {
+    this.writers.delete(id)
+  }
+
+  /**
+   * The pending entry for a created-but-unmaterialized session, if any.
+   * @param id - the session to look up.
+   * @returns the pending header and in-memory revision.
+   */
+  pendingOf(id: SessionId): PendingSession | undefined {
+    return this.pending.get(id)
+  }
+
+  /**
+   * Whether this process still tracks a created-but-unmaterialized session.
+   * @param id - the session to test.
+   * @returns true while the pending entry exists.
+   */
+  hasPending(id: SessionId): boolean {
+    return this.pending.has(id)
+  }
+
+  /**
+   * Iterate the pending sessions for listing.
+   * @returns the pending entries, keyed by session id.
+   */
+  pendingEntries(): IterableIterator<[SessionId, PendingSession]> {
+    return this.pending.entries()
+  }
+
+  /**
+   * Drop a pending entry once the session materialized durably.
+   * @param id - the session that reached durable storage.
+   */
+  materialized(id: SessionId): void {
+    this.pending.delete(id)
+  }
+
+  /**
+   * Track one open handle for teardown and, for a write handle, bind it as
+   * the session's live event route.
+   * @param handle - the just-constructed handle.
+   * @returns the same handle, for construction-site chaining.
+   */
+  adopt(handle: JsonlSessionHandle): JsonlSessionHandle {
+    this.openHandles.add(handle)
+    if (handle.access === 'write') this.writers.set(handle.id, handle)
+    return handle
+  }
+
+  /**
+   * Release one handle's bookkeeping on close. A write handle drops its
+   * ownership claim; a creator that never materialized leaves nothing behind —
+   * the session never existed.
+   * @param handle - the closing handle.
+   * @param materialized - whether the session reached durable storage.
+   */
+  release(handle: JsonlSessionHandle, materialized: boolean): void {
+    this.openHandles.delete(handle)
+    if (handle.access !== 'write') return
+    this.writers.delete(handle.id)
+    if (!materialized) this.pending.delete(handle.id)
+  }
+
+  /**
+   * Drain and flush every active write handle — the service-wide durability
+   * barrier behind `SessionPersistence.flush`.
+   * @throws {AggregateError} naming each session whose flush failed; the
+   *   remaining handles still flush.
+   */
+  async flushAll(): Promise<void> {
+    const errors: unknown[] = []
+    for (const writer of [...this.writers.values()]) {
+      if (writer === null) continue // a claim mid-construction routes nothing yet
+      try {
+        await writer.drainLive()
+        await writer.flush()
+      } catch (error: unknown) {
+        // A handle closed during the sweep counts as flushed: close itself
+        // drained the routed buffer durably before refusing this flush.
+        if (error instanceof SessionHandleClosedError) continue
+        errors.push(error)
+      }
+    }
+    if (errors.length > 0) throw new AggregateError(errors, `${this.name} flush failed`)
+  }
+
+  /**
+   * Install the backend's live session routing and teardown. Persistence
+   * enforces one active write handle per id, so the listeners route published
+   * sessions' events by id; the teardown effect closes every open handle —
+   * close drains the routed buffer — and aggregates failures. This provider
+   * owns no separate storage connection, so closing handles is the complete
+   * teardown. Registrations are effects of the current fiber.
+   * @param ctx - the backend's context.
+   */
+  install(ctx: Context): void {
+    ctx.on('session/event', (session: Session, event) => {
+      this.writers.get(session.id)?.enqueueLive(event, (error) => {
+        ctx.logger.warn(`session-persistence: background write for session "${session.id}" failed (buffered events retained): ${String(error)}`)
+      })
+    })
+    ctx.on('session/flush', (session: Session) => {
+      const writer = this.writers.get(session.id)
+      if (writer === null || writer === undefined) return undefined
+      return (async () => {
+        await writer.drainLive()
+        await writer.flush()
+      })()
+    })
+    ctx.on('session/disposed', (session: Session) => {
+      const writer = this.writers.get(session.id)
+      if (writer === null || writer === undefined) return
+      writer.close().catch((error: unknown) => {
+        ctx.logger.warn(`session-persistence: final drain for session "${session.id}" failed: ${String(error)}`)
+      })
+    })
+    ctx.effect(() => async () => {
+      const errors: unknown[] = []
+      for (const handle of [...this.openHandles]) {
+        try {
+          await handle.close()
+        } catch (error: unknown) {
+          errors.push(error)
+        }
+      }
+      if (errors.length > 0) throw new AggregateError(errors, `${this.name} dispose failed`)
+    }, `${this.name} open handles`)
+  }
+}
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index 363ec28212..e90b6474db 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -1,22 +1,37 @@
-import { MessageId, createUserMessage, createMessage } from '@deepseek-ai/dsh-llm'
+import { MessageId, createMessage } from '@deepseek-ai/dsh-llm'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { appendFile, mkdtemp, mkdir, rm, readFile, writeFile, readdir, stat, symlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
-import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import { dirname, join, relative, resolve } from 'node:path'
+import { SessionLogOffset, SessionSeq, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import {
-  encodeSegment, eventLines, logPath, parseHeader, projectDir, projectKey, scanLog, sessionDir, SessionLogScanner,
-  toHeaderLine,
+  encodeSegment, eventLines, logPath, projectDir, projectKey, scanLog, sessionDir, SessionLogScanner, toHeaderLine,
 } from '../src/format.ts'
-import { runPersistenceContract, meta, oneTurnLog, appendLog } from '../../session-persistence/tests/contract.ts'
-import { runCoordinatorContract, type CoordinatorFixture } from '../../session-persistence/tests/coordinator-contract.ts'
+import { runPersistenceContract, meta, oneTurnLog } from '../../session-persistence/tests/contract.ts'
+import { runLiveWritePathContract } from '../../session-persistence/tests/live-write-contract.ts'
+import { LIVE_WRITE_BATCH_MAX_DELAY_MS, type JsonlSessionHandle } from '../src/storage.ts'
+import SessionStore from '@deepseek-ai/dsh-session'
 
 const statRace = vi.hoisted(() => ({
   path: undefined as string | undefined,
   reads: 0,
+  /** 'settle': the revision changes once and then holds; 'churn': every stat differs. */
+  mode: 'settle' as 'settle' | 'churn',
+}))
+
+const statFailure = vi.hoisted(() => ({
+  path: undefined as string | undefined,
+  error: undefined as Error | undefined,
+}))
+
+const readTally = vi.hoisted(() => ({
+  /** Physical whole-file reads per path suffix; keyed by session id segment. */
+  bySuffix: new Map<string, number>(),
+  enabled: false,
 }))
 
 vi.mock('node:fs/promises', async (importOriginal) => {
@@ -24,12 +39,20 @@ vi.mock('node:fs/promises', async (importOriginal) => {
   return {
     ...actual,
     stat: (async (...args: Parameters<typeof actual.stat>) => {
+      if (String(args[0]) === statFailure.path && statFailure.error !== undefined) throw statFailure.error
       const identity = await actual.stat(...args)
       if (String(args[0]) !== statRace.path || !('mtimeNs' in identity)) return identity
       statRace.reads += 1
-      if (statRace.reads !== 2) return identity
+      if (statRace.mode === 'churn') return { ...identity, mtimeNs: identity.mtimeNs + BigInt(statRace.reads) }
+      if (statRace.reads < 3) return identity
       return { ...identity, mtimeNs: identity.mtimeNs + 1n }
     }) as typeof actual.stat,
+    readFile: (async (...args: Parameters<typeof actual.readFile>) => {
+      if (readTally.enabled && typeof args[0] === 'string') {
+        readTally.bySuffix.set(args[0], (readTally.bySuffix.get(args[0]) ?? 0) + 1)
+      }
+      return actual.readFile(...args)
+    }) as typeof actual.readFile,
   }
 })
 
@@ -38,7 +61,7 @@ const dirs: string[] = []
 
 type MutableSessionHeader = { -readonly [K in keyof SessionHeader]: SessionHeader[K] }
 
-/** Test-only mutable view used to verify that backends detach returned/caller metadata. */
+/** Test-only mutable view used to verify that backends detach caller metadata. */
 function mutableHeader(header: SessionHeader): MutableSessionHeader {
   return header
 }
@@ -52,18 +75,7 @@ async function rewriteHeader(path: string, update: (header: Record<string, unkno
   await writeFile(path, lines.join('\n'))
 }
 
-async function expectFlushError(promise: Promise<unknown>, message: RegExp): Promise<void> {
-  try {
-    await promise
-  } catch (error) {
-    expect(error).toBeInstanceOf(Error)
-    expect((error as Error).message).toMatch(message)
-    return
-  }
-  throw new Error('expected flush to reject')
-}
-
-async function expectFlushCode(promise: Promise<unknown>, codes: readonly string[]): Promise<void> {
+async function expectCode(promise: Promise<unknown>, codes: readonly string[]): Promise<void> {
   try {
     await promise
   } catch (error) {
@@ -71,7 +83,7 @@ async function expectFlushCode(promise: Promise<unknown>, codes: readonly string
     expect(codes).toContain((error as NodeJS.ErrnoException).code)
     return
   }
-  throw new Error('expected flush to reject')
+  throw new Error('expected the operation to reject')
 }
 
 async function freshRoot(): Promise<string> {
@@ -84,56 +96,130 @@ function rawLogPath(root: string, cwd: string | undefined, id: SessionId): strin
   return logPath(root, cwd, id, 'none')
 }
 
+/** Create + append + close: persist one whole log through the write handle. */
+async function writeLog(persistence: SessionPersistence, m: SessionHeader, events: readonly SessionEvent[]): Promise<void> {
+  const handle = await persistence.create(m)
+  try {
+    await handle.append(events)
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Open a read handle, read the whole log, and close. */
+async function readAll(persistence: SessionPersistence, id: SessionId): Promise<{ meta: SessionHeader; events: readonly SessionEvent[] }> {
+  const handle = await persistence.open(id, 'read')
+  try {
+    return { meta: handle.header, events: await handle.read() }
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Append one contiguous batch through a temporary write handle. */
+async function appendBatch(persistence: SessionPersistence, id: SessionId, events: readonly SessionEvent[]): Promise<void> {
+  const handle = await persistence.open(id, 'write')
+  try {
+    await handle.append(events)
+  } finally {
+    await handle.close()
+  }
+}
+
 afterEach(async () => {
   statRace.path = undefined
   statRace.reads = 0
+  statRace.mode = 'settle'
+  readTally.bySuffix.clear()
+  readTally.enabled = false
+  statFailure.path = undefined
+  statFailure.error = undefined
   vi.restoreAllMocks()
   for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true })
 })
 
-function appendClosedTurn(session: Session): void {
-  session.append('turn/start', { turn: 1 })
-  session.append('user/message', createUserMessage({
-    content: [{ type: 'text', text: 'hello' }],
-    source: { kind: 'user' },
-  }), { surfaceOp: 'append' })
-  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-}
-
 runPersistenceContract('jsonl-none', async () => {
   const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-'))
-  const ctx = new Context()
-  await ctx.plugin(SessionStore)
-  const fiber = await ctx.plugin(JsonlSessionPersistence, { root: dir, compression: 'none' })
+  const instance = async (): Promise<{ persistence: SessionPersistence; dispose: () => Promise<void> }> => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(JsonlSessionPersistence, { root: dir, compression: 'none' })
+    return {
+      persistence: ctx.sessionPersistence,
+      dispose: async () => { await fiber.dispose() },
+    }
+  }
+  const primary = await instance()
   return {
-    persistence: ctx.sessionPersistence,
+    persistence: primary.persistence,
     dispose: async () => {
-      await fiber.dispose()
+      await primary.dispose()
       await rm(dir, { recursive: true, force: true })
     },
+    reopen: instance,
+    // A half-written record with no trailing newline: scanLog treats it as an
+    // uncommitted crash fragment, so the write path sees a torn tail to truncate.
+    corruptTail: async (id, cwd) => {
+      await appendFile(rawLogPath(dir, cwd, id), '{"type":"assistant/chunk","seq":8,"ti')
+    },
   }
 })
 
-// Two mounts share this temp root to exercise reload. `corruptTail` appends a partial,
-// newline-less fragment past the committed region so coordinator repair runs on real file bytes.
-runCoordinatorContract('jsonl-none', async (): Promise<CoordinatorFixture> => {
-  const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-coord-'))
-  return {
-    mount: async (ctx) => {
-      const fiber = await ctx.plugin(JsonlSessionPersistence, { root: dir, compression: 'none' })
-      return fiber
-    },
-    corruptTail: async (id, cwd) => {
-      // A half-written record with no trailing newline: scanLog treats it as an
-      // uncommitted crash fragment and reports committedBytes < byteLength, so
-      // the coordinator sees a tornMarker to truncate.
-      await appendFile(rawLogPath(dir, cwd, id), '{"type":"assistant/chunk","seq":8,"ti')
-    },
-    cleanup: async () => { await rm(dir, { recursive: true, force: true }) },
+runLiveWritePathContract('jsonl', LIVE_WRITE_BATCH_MAX_DELAY_MS, async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-live-'))
+  dirs.push(dir)
+  const mount = async (): Promise<Context> => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(JsonlSessionPersistence, { root: dir, compression: 'none' })
+    return ctx
   }
+  return { ctx: await mount(), remount: mount }
 })
 
 describe('JsonlSessionPersistence: format helpers', () => {
+  it('encodeSegment neutralizes traversal, separators, and absolute paths', () => {
+    expect(encodeSegment('..')).toBe('~002E~002E')
+    expect(encodeSegment('.')).toBe('~002E')
+    expect(encodeSegment('a/b')).toBe('a~002Fb')
+    expect(encodeSegment('/etc/passwd')).toBe('~002Fetc~002Fpasswd')
+    expect(encodeSegment('a\u0000b')).toBe('a~0000b')
+    expect(encodeSegment('plain-ID_1.2')).toBe('plain-ID_1.2') // safe chars pass through
+    expect(encodeSegment('a~b')).toBe('a~007Eb') // ~ itself is escaped
+  })
+
+  it('encodeSegment is injective over UTF-16, incl. lone surrogates', () => {
+    // Distinct lone surrogates must NOT collide (Buffer.from would normalize
+    // both to U+FFFD; code-unit escaping keeps them distinct).
+    const hi = encodeSegment(String.fromCharCode(0xD800))
+    const lo = encodeSegment(String.fromCharCode(0xDC00))
+    expect(hi).toBe('~D800')
+    expect(lo).toBe('~DC00')
+    expect(hi).not.toBe(lo)
+    // A literal "~002F" input cannot collide with the encoding of "/".
+    expect(encodeSegment('~002F')).not.toBe(encodeSegment('/'))
+  })
+
+  it('encodeSegment rejects an empty id', () => {
+    expect(() => encodeSegment('')).toThrow(/empty/)
+  })
+
+  it('round-trips every optional header field through the header line', () => {
+    const full: SessionHeader = {
+      version: 0,
+      id: SessionId('full-header'),
+      createdAt: 5,
+      cwd: '/w',
+      parentSession: SessionId('parent'),
+      isSeeded: true,
+      origin: 'subagent',
+      delegationDepth: 2,
+      agentPreset: 'minimal',
+    }
+    const scan = scanLog(Buffer.from(`${JSON.stringify(toHeaderLine(full, SessionLogOffset(3)))}\n`))
+    expect(scan.meta).toEqual(full)
+    expect(scan.inheritedEventCount).toBe(3)
+  })
+
   it.each([
     ['absent', undefined, false, 0],
     ['zero', 0, true, 0],
@@ -169,39 +255,6 @@ describe('JsonlSessionPersistence: format helpers', () => {
       .toThrow('unseeded session header inherited event count must be 0')
   })
 
-  it('round-trips the subagent origin and rejects other physical values', () => {
-    const line = toHeaderLine({ ...meta('subagent-origin'), origin: 'subagent' })
-    expect(scanLog(Buffer.from(`${JSON.stringify(line)}\n`)).meta.origin).toBe('subagent')
-    expect(() => scanLog(Buffer.from(`${JSON.stringify({ ...line, origin: 'worker' })}\n`)))
-      .toThrow(/session header/)
-  })
-
-  it('encodeSegment neutralizes traversal, separators, and absolute paths', () => {
-    expect(encodeSegment('..')).toBe('~002E~002E')
-    expect(encodeSegment('.')).toBe('~002E')
-    expect(encodeSegment('a/b')).toBe('a~002Fb')
-    expect(encodeSegment('/etc/passwd')).toBe('~002Fetc~002Fpasswd')
-    expect(encodeSegment('a\u0000b')).toBe('a~0000b')
-    expect(encodeSegment('plain-ID_1.2')).toBe('plain-ID_1.2') // safe chars pass through
-    expect(encodeSegment('a~b')).toBe('a~007Eb') // ~ itself is escaped
-  })
-
-  it('encodeSegment is injective over UTF-16, incl. lone surrogates', () => {
-    // Distinct lone surrogates must NOT collide (Buffer.from would normalize
-    // both to U+FFFD; code-unit escaping keeps them distinct).
-    const hi = encodeSegment(String.fromCharCode(0xD800))
-    const lo = encodeSegment(String.fromCharCode(0xDC00))
-    expect(hi).toBe('~D800')
-    expect(lo).toBe('~DC00')
-    expect(hi).not.toBe(lo)
-    // A literal "~002F" input cannot collide with the encoding of "/".
-    expect(encodeSegment('~002F')).not.toBe(encodeSegment('/'))
-  })
-
-  it('encodeSegment rejects an empty id', () => {
-    expect(() => encodeSegment('')).toThrow(/empty/)
-  })
-
   it('projectKey normalizes project paths into bounded readable names', () => {
     expect(projectKey('/Users/qyj/work/deepseek-harness')).toBe('--Users-qyj-work-deepseek-harness--')
     expect(projectKey('/a/b-c')).toBe(projectKey('/a-b/c'))
@@ -212,96 +265,158 @@ describe('JsonlSessionPersistence: format helpers', () => {
     expect(() => projectKey('')).toThrow(/empty project path/)
   })
 
-  it('resolves a relative custom root before locating a session', async () => {
+  it('resolves a relative custom root before storing a session', async () => {
     const absoluteRoot = await freshRoot()
     const ctx = new Context()
-    await ctx.plugin(SessionStore)
     const fiber = await ctx.plugin(JsonlSessionPersistence, {
       root: relative(process.cwd(), absoluteRoot),
       compression: 'none',
-      writeBatchMaxDelayMs: 1,
     })
     const m = meta('relative-location', '/work')
-    expect(ctx.sessionPersistence.locate(m)).toEqual({
-      kind: 'jsonl',
-      path: rawLogPath(resolve(absoluteRoot), '/work', m.id),
-    })
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    expect((await stat(rawLogPath(resolve(absoluteRoot), '/work', m.id))).isFile()).toBe(true)
     await fiber.dispose()
   })
+})
 
-  it('refuses a structurally foreign future header as unsupported, not corrupt', async () => {
-    const absoluteRoot = await freshRoot()
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(JsonlSessionPersistence, { root: absoluteRoot, compression: 'none' })
+describe('JsonlSessionPersistence: stored-format refusals', () => {
+  let ctx: Context
+  beforeEach(async () => {
+    root = await freshRoot()
+    ctx = new Context()
+    await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
+  })
+  afterEach(async () => { await ctx.fiber.dispose() })
+
+  it('propagates a non-format header failure from stat and list unchanged', async () => {
+    // Only foreign-version refusals are enriched (stat) or skipped (list);
+    // any other header failure stays fail-loud on both paths.
+    const id = SessionId('retired-policy-header')
+    const path = rawLogPath(root, '/work', id)
+    await mkdir(dirname(path), { recursive: true })
+    const line = { type: 'session', version: 0, id, createdAt: 1, delegationDepth: 0, sandboxMode: 'strict' }
+    await writeFile(path, `${JSON.stringify(line)}\n`)
+    await expect(ctx.sessionPersistence.stat(id)).rejects.toThrow('retired policy baseline fields')
+    await expect(ctx.sessionPersistence.list()).rejects.toThrow('retired policy baseline fields')
+  })
+
+  it('refuses a structurally foreign future header as unsupported, not corrupt or absent', async () => {
     // A future format need not satisfy this build's header shape at all (no
     // createdAt, unknown fields): the version must be refused before shape
-    // validation, so the user sees the upgrade direction.
+    // validation, so the user sees the upgrade direction — never "not found".
     const id = SessionId('future-shape')
-    const path = rawLogPath(resolve(absoluteRoot), '/work', id)
+    const path = rawLogPath(root, '/work', id)
     await mkdir(dirname(path), { recursive: true })
     await writeFile(path, `${JSON.stringify({ type: 'session', version: 42, id, futureOnly: true })}\n{"future":"row"}\n`)
-    const failure = await ctx.sessionPersistence.load(id).then(() => undefined, (error: unknown) => error as Error)
+    for (const access of ['read', 'write'] as const) {
+      const failure = await ctx.sessionPersistence.open(id, access).then(() => undefined, (error: unknown) => error as Error)
+      expect(failure?.name).toBe('SessionFormatUnsupportedError')
+      expect(failure?.message).toMatch(/written by a newer harness.*upgrade the harness/)
+      expect(failure?.message).toContain(`(raw log: ${path})`)
+    }
+    // Listing skips the unreadable header instead of failing the whole root.
+    expect(await ctx.sessionPersistence.list()).toEqual([])
+  })
+
+  it('refuses a well-shaped newer-version header at read open with the upgrade direction', async () => {
+    // A header that satisfies the current shape but carries a future version:
+    // stat can parse it, and the open still refuses before handing out a
+    // handle whose every read would fail.
+    const id = SessionId('future-version')
+    const path = rawLogPath(root, '/work', id)
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(path, `${JSON.stringify({ type: 'session', version: 42, id, createdAt: 1, cwd: '/work', delegationDepth: 0 })}\n`)
+    const failure = await ctx.sessionPersistence.open(id, 'read').then(() => undefined, (error: unknown) => error as Error)
     expect(failure?.name).toBe('SessionFormatUnsupportedError')
-    expect(failure?.message).toMatch(/written by a newer harness.*upgrade the harness/)
+    expect(failure?.message).toMatch(/upgrade the harness/)
     expect(failure?.message).toContain(`(raw log: ${path})`)
-    await fiber.dispose()
   })
 
   it('keeps a non-object header line a corruption, not a format refusal', async () => {
-    const absoluteRoot = await freshRoot()
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(JsonlSessionPersistence, { root: absoluteRoot, compression: 'none' })
     // Valid JSON that is no object carries no version to compare, so the
     // version guard must pass it through to the corruption diagnostics.
     const id = SessionId('scalar-header')
-    const path = rawLogPath(resolve(absoluteRoot), '/work', id)
+    const path = rawLogPath(root, '/work', id)
     await mkdir(dirname(path), { recursive: true })
     await writeFile(path, '42\n')
-    const failure = await ctx.sessionPersistence.load(id).then(() => undefined, (error: unknown) => error as Error)
+    const failure = await ctx.sessionPersistence.open(id, 'read').then(() => undefined, (error: unknown) => error as Error)
     expect(failure?.name).not.toBe('SessionFormatUnsupportedError')
     expect(failure?.message).toContain('first line is not a session header')
-    await fiber.dispose()
   })
 
   it('names a foreign-version header by its stringified non-string id', async () => {
-    const absoluteRoot = await freshRoot()
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(JsonlSessionPersistence, { root: absoluteRoot, compression: 'none' })
     // A future header's id field is as untrusted as the rest of its shape:
     // the refusal must still name the session it read, not crash on the type.
     const id = SessionId('numeric-id')
-    const path = rawLogPath(resolve(absoluteRoot), '/work', id)
+    const path = rawLogPath(root, '/work', id)
     await mkdir(dirname(path), { recursive: true })
     await writeFile(path, `${JSON.stringify({ type: 'session', version: 42, id: 123 })}\n`)
-    const failure = await ctx.sessionPersistence.load(id).then(() => undefined, (error: unknown) => error as Error)
+    const failure = await ctx.sessionPersistence.open(id, 'read').then(() => undefined, (error: unknown) => error as Error)
     expect(failure?.name).toBe('SessionFormatUnsupportedError')
     expect(failure?.message).toContain('session "123" uses log format v42')
-    await fiber.dispose()
   })
 
-  it('refuses a foreign version on the header-only read path', () => {
-    expect(() => parseHeader(JSON.stringify({ version: 42, id: 'future', futureOnly: true })))
-      .toThrow(expect.objectContaining({ name: 'SessionFormatUnsupportedError' }))
-  })
-
-  it('points a format refusal at the raw log path', async () => {
-    const absoluteRoot = await freshRoot()
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(JsonlSessionPersistence, { root: absoluteRoot, compression: 'none' })
+  it('points a format refusal for a self-written foreign version at the raw log path', async () => {
+    // create() stores the caller's header verbatim, so a foreign version can
+    // reach disk through this build; reads then refuse it with the location.
     const m = { ...meta('newer-format', '/work'), version: 7 }
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, [
+    await writeLog(ctx.sessionPersistence, m, [
       { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
       { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
     ])
-    const failure = await ctx.sessionPersistence.load(m.id).then(() => undefined, (error: unknown) => error as Error)
+    const failure = await ctx.sessionPersistence.open(m.id, 'read').then(() => undefined, (error: unknown) => error as Error)
     expect(failure?.name).toBe('SessionFormatUnsupportedError')
-    expect(failure?.message).toContain(`(raw log: ${rawLogPath(resolve(absoluteRoot), '/work', m.id)})`)
-    await fiber.dispose()
+    expect(failure?.message).toContain(`(raw log: ${rawLogPath(root, '/work', m.id)})`)
+  })
+
+  it('serves a read open through the full log read when the header-only read races a writer', async () => {
+    const m = meta('stat-race-open', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    // Simulate the race: the header-only stat sees nothing although the full
+    // log is present and readable.
+    vi.spyOn(ctx.sessionPersistence, 'stat').mockResolvedValue(undefined)
+    const handle = await ctx.sessionPersistence.open(m.id, 'read')
+    try {
+      expect(handle.header).toMatchObject({ id: m.id, cwd: '/work' })
+      expect(await handle.read()).toEqual(oneTurnLog())
+    } finally {
+      await handle.close()
+    }
+  })
+
+  it('rejects a stored v0 log containing a legacy request/header-delta event', async () => {
+    const m = meta('legacy-header-delta', '/legacy')
+    const path = rawLogPath(root, m.cwd, m.id)
+    await mkdir(sessionDir(root, m.cwd, m.id), { recursive: true })
+    await writeFile(path, [
+      JSON.stringify(toHeaderLine(m)),
+      JSON.stringify({ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }),
+      JSON.stringify({ type: 'request/header-delta', seq: SessionSeq(1), time: 2, data: { config: { model: 'legacy' } } }),
+      JSON.stringify({ type: 'turn/end', seq: SessionSeq(2), time: 3, data: { turn: 1, reason: { kind: 'completed' } } }),
+      '',
+    ].join('\n'))
+
+    await expect(readAll(ctx.sessionPersistence, m.id))
+      .rejects.toThrow(/contains event type "request\/header-delta" \(seq 1\) unknown to this harness/)
+  })
+
+  it('rejects a stored v0 full header carrying the legacy fallback reason', async () => {
+    const m = meta('legacy-header-fallback', '/legacy')
+    const path = rawLogPath(root, m.cwd, m.id)
+    await mkdir(sessionDir(root, m.cwd, m.id), { recursive: true })
+    await writeFile(path, [
+      JSON.stringify(toHeaderLine(m)),
+      JSON.stringify({
+        type: 'request/header',
+        seq: SessionSeq(0),
+        time: 1,
+        data: { header: { config: { provider: 'mock', model: 'legacy' } }, reason: 'fallback' },
+      }),
+      '',
+    ].join('\n'))
+
+    await expect(readAll(ctx.sessionPersistence, m.id))
+      .rejects.toThrow(/unsupported legacy reason "fallback"/)
   })
 })
 
@@ -310,122 +425,244 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
   beforeEach(async () => {
     root = await freshRoot()
     ctx = new Context()
-    await ctx.plugin(SessionStore)
     await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   })
   afterEach(async () => { await ctx.fiber.dispose() })
 
   it('lazy materialization: create() writes no file until the first append', async () => {
     const m = meta('lazy', '/work')
-    const location = ctx.sessionPersistence.locate(m)
-    expect(location).toEqual({ kind: 'jsonl', path: rawLogPath(root, '/work', m.id) })
-    expect(isAbsolute(location!.path)).toBe(true)
-
-    await ctx.sessionPersistence.create(m)
-    // locate() is a pure target-path calculation: neither it nor create()
-    // materializes a file before the first append.
+    const handle = await ctx.sessionPersistence.create(m)
+    // create() materializes no file before the first append — while the
+    // created session is already visible to this process.
     const dir = sessionDir(root, '/work', m.id)
     await expect(stat(rawLogPath(root, '/work', m.id))).rejects.toThrow()
-    expect((await ctx.sessionPersistence.list()).map(h => h.id)).not.toContain(m.id)
+    expect((await ctx.sessionPersistence.list()).map(s => s.header.id)).toContain(m.id)
+    expect((await ctx.sessionPersistence.stat(m.id))?.sizeBytes).toBeUndefined()
 
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    await handle.append(oneTurnLog())
     expect((await stat(dir)).isDirectory()).toBe(true)
     expect((await stat(rawLogPath(root, '/work', m.id))).isFile()).toBe(true)
-    expect((await ctx.sessionPersistence.list()).map(h => h.id)).toContain(m.id)
+    expect((await ctx.sessionPersistence.list()).map(s => s.header.id)).toContain(m.id)
+    await handle.close()
   })
 
-  it('lists a seeded header without reading an event body', async () => {
-    const id = SessionId('header-only-seeded')
-    const path = rawLogPath(root, '/work', id)
-    await mkdir(dirname(path), { recursive: true })
-    await writeFile(path, `${JSON.stringify({
-      type: 'session',
-      version: 0,
-      id,
-      createdAt: 1000,
-      cwd: '/work',
-      seedLength: 0,
-      delegationDepth: 0,
-    })}\n{not-valid-json`)
+  it('flush materializes an explicitly durable empty session without an event row', async () => {
+    const m = meta('durable-empty', '/work')
+    const handle = await ctx.sessionPersistence.create(m)
+    await handle.flush()
+    await handle.close()
 
-    await expect(ctx.sessionPersistence.list()).resolves.toEqual([
-      expect.objectContaining({ id, isSeeded: true }),
-    ])
+    expect(await readFile(rawLogPath(root, '/work', m.id), 'utf8')).toBe(`${JSON.stringify(toHeaderLine(m))}\n`)
+    await expect(readAll(ctx.sessionPersistence, m.id)).resolves.toMatchObject({ events: [] })
   })
 
-  it('materializes an explicitly durable empty live session without an event row', async () => {
-    const id = SessionId('durable-empty')
-    const session = ctx.sessions.create(id, { meta: { cwd: '/work' } })
-
-    await ctx.sessionPersistence.ensureMaterialized(session)
-
-    expect(await readFile(rawLogPath(root, '/work', id), 'utf8')).toBe(`${JSON.stringify(toHeaderLine(session.header))}\n`)
-    await expect(ctx.sessionPersistence.load(id)).resolves.toEqual({
-      meta: session.header,
-      inheritedEventCount: SessionLogOffset(0),
-      events: [],
+  it('close drains a routed event that arrives while it waits for an in-flight append', async () => {
+    const m = meta('late-closer', '/work')
+    const handle = await ctx.sessionPersistence.create(m) as JsonlSessionHandle
+    const service = ctx.sessionPersistence as unknown as {
+      persistBatch: (...args: [SessionHeader, readonly SessionEvent[], boolean]) => Promise<void>
+    }
+    const original = service.persistBatch.bind(service)
+    const gate = Promise.withResolvers<undefined>()
+    const entered = Promise.withResolvers<undefined>()
+    vi.spyOn(service, 'persistBatch').mockImplementationOnce(async (...args) => {
+      entered.resolve(undefined)
+      await gate.promise
+      return original(...args)
     })
+
+    const [start, ...rest] = oneTurnLog()
+    const inflight = handle.append([start!])
+    // The append is in flight (inside the gated storage write) before close
+    // starts, so close waits on the chain rather than refusing the append.
+    await entered.promise
+    const closing = handle.close()
+    // A concurrently unwinding producer routes more events while close waits
+    // on the blocked chain; the close loop must still drain them.
+    for (const event of rest) handle.enqueueLive(event, () => {})
+    gate.resolve(undefined)
+    await inflight
+    await closing
+
+    const reopened = new Context()
+    await reopened.plugin(JsonlSessionPersistence, { root, compression: 'none' })
+    await expect(readAll(reopened.sessionPersistence, m.id))
+      .resolves.toMatchObject({ events: oneTurnLog() })
+    await reopened.fiber.dispose()
   })
 
-  it('delegates direct preparation through the JSONL provider', async () => {
-    const m = meta('direct-prepare', '/work')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+  it('service flush skips a write claim whose handle is still opening', async () => {
+    const m = meta('opening-claim', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const service = ctx.sessionPersistence as unknown as {
+      readStoredLog: (...args: [string, SessionId]) => Promise<unknown>
+    }
+    const original = service.readStoredLog.bind(service)
+    const gate = Promise.withResolvers<undefined>()
+    const entered = Promise.withResolvers<undefined>()
+    vi.spyOn(service, 'readStoredLog').mockImplementationOnce(async (...args) => {
+      entered.resolve(undefined)
+      await gate.promise
+      return original(...args)
+    })
 
-    const preparation = await ctx.sessionPersistence.prepare(m.id)
-
-    expect(preparation.session.header).toMatchObject(m)
-    preparation[Symbol.dispose]()
+    const opening = ctx.sessionPersistence.open(m.id, 'write')
+    await entered.promise
+    // The claim exists but its handle is still constructing: nothing routes
+    // to it yet, so the barrier has nothing to flush there.
+    await ctx.sessionPersistence.flush()
+    gate.resolve(undefined)
+    await (await opening).close()
   })
 
-  it('readRaw returns the stored artifact text verbatim with its original filename', async () => {
-    const m = meta('raw-read', '/work')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    const raw = await ctx.sessionPersistence.readRaw(m.id)
-    expect(raw).toBeDefined()
-    expect(raw!.filename).toBe('session.jsonl')
-    expect(raw!.meta.id).toBe(m.id)
-    // Byte-identical to the physical file — never a reconstruction.
-    expect(raw!.content).toBe(await readFile(rawLogPath(root, '/work', m.id), 'utf8'))
-    expect(raw!.content.split('\n')[0]).toBe(JSON.stringify(toHeaderLine(m)))
-    const scanned = scanLog(Buffer.from(raw!.content))
-    expect(scanned.events.map(event => event.type)).toEqual(oneTurnLog().map(event => event.type))
+  it('stat and list carry the physical artifact size once materialized', async () => {
+    const m = meta('sized', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const size = (await stat(rawLogPath(root, '/work', m.id))).size
+    expect((await ctx.sessionPersistence.stat(m.id))?.sizeBytes).toBe(size)
+    expect((await ctx.sessionPersistence.list()).find(s => s.header.id === m.id)?.sizeBytes).toBe(size)
   })
 
-  it('readRaw is undefined for an absent session', async () => {
-    const m = meta('raw-missing', '/work')
-    expect(await ctx.sessionPersistence.readRaw(m.id)).toBeUndefined()
+  it('binds revisions to the physical artifact identity', async () => {
+    const m = meta('revision-source')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const revision = (await ctx.sessionPersistence.stat(m.id))?.revision
+
+    // A fresh backend over the SAME root reports the same revision…
+    const reopenedCtx = new Context()
+    await reopenedCtx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
+    expect((await reopenedCtx.sessionPersistence.stat(m.id))?.revision).toBe(revision)
+
+    // …while an identical log in a DIFFERENT root is a different source.
+    const otherRoot = await freshRoot()
+    const otherCtx = new Context()
+    await otherCtx.plugin(JsonlSessionPersistence, { root: otherRoot, compression: 'none' })
+    await writeLog(otherCtx.sessionPersistence, m, oneTurnLog())
+    expect((await otherCtx.sessionPersistence.stat(m.id))?.revision).not.toBe(revision)
+
+    await reopenedCtx.fiber.dispose()
+    await otherCtx.fiber.dispose()
   })
 
-  it('readRaw rejects a corrupt header line instead of exporting it', async () => {
-    const m = meta('raw-corrupt', '/work')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    await writeFile(rawLogPath(root, '/work', m.id), 'not a header line\n{"type":"turn/start","seq":0}\n')
-    await expect(ctx.sessionPersistence.readRaw(m.id)).rejects.toThrow(/corrupt session log/)
+
+
+
+
+  it('an unchanged cold log parses once across an observe-then-resume handoff', async () => {
+    const m = meta('memo-handoff', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const path = rawLogPath(root, '/work', m.id)
+    readTally.enabled = true
+
+    // The observation's read parses the artifact...
+    expect((await readAll(ctx.sessionPersistence, m.id)).events).toEqual(oneTurnLog())
+    expect(readTally.bySuffix.get(path)).toBe(1)
+    // ...and the immediate write-open (resume) reuses the parsed log through
+    // the revision guard instead of re-reading the file.
+    const writer = await ctx.sessionPersistence.open(m.id, 'write')
+    expect((await writer.read()).length).toBe(oneTurnLog().length)
+    expect(readTally.bySuffix.get(path)).toBe(1)
+
+    // A local append invalidates the memo: the next cold read re-parses and
+    // observes the appended suffix.
+    await writer.append([
+      { type: 'turn/start', seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+      { type: 'turn/end', seq: SessionSeq(7), time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
+    ] as SessionEvent[])
+    await writer.close()
+    expect((await readAll(ctx.sessionPersistence, m.id)).events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+    expect(readTally.bySuffix.get(path)).toBe(2)
   })
 
-  it('readRaw retries when the file revision changes during the read', async () => {
-    const m = meta('raw-revision-race', '/work')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    statRace.path = rawLogPath(root, '/work', m.id)
+  it('a foreign write misses the memo through the revision guard', async () => {
+    const m = meta('memo-foreign', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const path = rawLogPath(root, '/work', m.id)
+    await readAll(ctx.sessionPersistence, m.id)
 
-    const raw = await ctx.sessionPersistence.readRaw(m.id)
-    expect(raw).toBeDefined()
-    // Two stat calls per iteration; the mocked revision change forces a retry.
-    expect(statRace.reads).toBe(4)
+    // Another backend instance over the same root appends behind this one's memo.
+    const foreign = new Context()
+    await foreign.plugin(JsonlSessionPersistence, { root, compression: 'none' })
+    const writer = await foreign.sessionPersistence.open(m.id, 'write')
+    await writer.append([
+      { type: 'turn/start', seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+      { type: 'turn/end', seq: SessionSeq(7), time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
+    ] as SessionEvent[])
+    await writer.close()
+    await foreign.fiber.dispose()
+
+    readTally.enabled = true
+    expect((await readAll(ctx.sessionPersistence, m.id)).events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+    expect(readTally.bySuffix.get(path)).toBe(1)
   })
 
-  it('keeps the same location on resume and gives a fork its own location', async () => {
+  it('the cold-log memo keeps only the handoff window and evicts the oldest id', async () => {
+    const first = meta('memo-evict-a', '/work')
+    const second = meta('memo-evict-b', '/work')
+    const third = meta('memo-evict-c', '/work')
+    for (const m of [first, second, third]) await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    readTally.enabled = true
+
+    await readAll(ctx.sessionPersistence, first.id)
+    await readAll(ctx.sessionPersistence, second.id)
+    await readAll(ctx.sessionPersistence, third.id) // evicts the first id
+    await readAll(ctx.sessionPersistence, third.id) // still memoized
+    await readAll(ctx.sessionPersistence, first.id) // re-parses after eviction
+    expect(readTally.bySuffix.get(rawLogPath(root, '/work', first.id))).toBe(2)
+    expect(readTally.bySuffix.get(rawLogPath(root, '/work', third.id))).toBe(1)
+  })
+
+  it('a handle read retries once when the file revision changes during the read', async () => {
+    const m = meta('read-revision-race', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const handle = await ctx.sessionPersistence.open(m.id, 'read')
+    try {
+      statRace.path = rawLogPath(root, '/work', m.id)
+      expect(await handle.read()).toEqual(oneTurnLog())
+      // The memo probe, the initial identity, the mismatching post-read stat
+      // (reused as the retry's pre-read identity), and the retry's matching
+      // post-read stat.
+      expect(statRace.reads).toBe(4)
+    } finally {
+      statRace.path = undefined
+      await handle.close()
+    }
+  })
+
+  it('a continuously churning revision yields the committed prefix instead of looping', async () => {
+    const m = meta('read-revision-churn', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const handle = await ctx.sessionPersistence.open(m.id, 'read')
+    try {
+      statRace.mode = 'churn'
+      statRace.path = rawLogPath(root, '/work', m.id)
+      // Every stat disagrees, so the bounded read stops after one retry and
+      // serves the retry's pre-read committed prefix — here the whole log.
+      // Four stats: the memo probe, the initial identity, and one mismatching
+      // post-read stat per bounded attempt.
+      expect(await handle.read()).toEqual(oneTurnLog())
+      expect(statRace.reads).toBe(4)
+    } finally {
+      statRace.path = undefined
+      await handle.close()
+    }
+  })
+
+  it('appends on reopen extend the same artifact and a fork materializes its own', async () => {
     const parent = meta('location-parent', '/work')
-    const parentLocation = ctx.sessionPersistence.locate(parent)
-    await ctx.sessionPersistence.create(parent)
-    await ctx.sessionPersistence.append(parent.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, parent, oneTurnLog())
+    const parentPath = rawLogPath(root, '/work', parent.id)
+    const sizeBefore = (await stat(parentPath)).size
 
-    const loaded = await ctx.sessionPersistence.load(parent.id)
-    expect(ctx.sessionPersistence.locate(loaded.meta)).toEqual(parentLocation)
+    const loaded = await readAll(ctx.sessionPersistence, parent.id)
+    const writer = await ctx.sessionPersistence.open(parent.id, 'write')
+    await writer.append([
+      { type: 'turn/start', seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+      { type: 'turn/end', seq: SessionSeq(7), time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
+    ] as SessionEvent[])
+    await writer.close()
+    // The resume-side append extended the same physical artifact.
+    expect((await stat(parentPath)).size).toBeGreaterThan(sizeBefore)
 
     const child = {
       ...loaded.meta,
@@ -433,9 +670,10 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
       parentSession: parent.id,
       seedLength: loaded.events.length,
     }
-    const childLocation = ctx.sessionPersistence.locate(child)
-    expect(childLocation?.path).not.toBe(parentLocation?.path)
-    expect(childLocation).toEqual({ kind: 'jsonl', path: rawLogPath(root, '/work', child.id) })
+    await writeLog(ctx.sessionPersistence, child, oneTurnLog())
+    const childPath = rawLogPath(root, '/work', child.id)
+    expect(childPath).not.toBe(parentPath)
+    expect((await stat(childPath)).isFile()).toBe(true)
   })
 
   it('round-trip is byte-identical (incl. assistant/chunk verbatim)', async () => {
@@ -459,61 +697,205 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
       { type: 'step/end', seq: SessionSeq(5), time: 6, data: { turn: 1, step: 1 } },
       { type: 'turn/end', seq: SessionSeq(6), time: 7, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, log)
-    const loaded = await ctx.sessionPersistence.load(m.id)
+    await writeLog(ctx.sessionPersistence, m, log)
+    const loaded = await readAll(ctx.sessionPersistence, m.id)
     expect(loaded.events).toEqual(log) // chunks preserved, contiguous seqs
   })
 
-  it('source-qualifies revisions across roots while preserving same-log reopen identity', async () => {
-    const m = meta('revision-source')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    const revision = (await ctx.sessionPersistence.listSnapshots())[0]?.revision
+  it('a torn crash tail is served as the committed prefix and repaired only by the write path', async () => {
+    const m = meta('crash', '/proj')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog()) // seqs 0..5
+    const path = rawLogPath(root, '/proj', m.id)
+    const committed = await readFile(path)
+    // A crash mid-second-turn: two complete uncommitted lines plus a torn
+    // fragment with no newline.
+    const tail = [
+      JSON.stringify({ type: 'turn/start', seq: SessionSeq(6), time: 8, data: { turn: 2 } }),
+      JSON.stringify({ type: 'step/start', seq: SessionSeq(7), time: 9, data: { turn: 2, step: 1 } }),
+      '{"type":"assistant/chunk","seq":8,"ti', // truncated partial line (no newline)
+    ].join('\n')
+    await writeFile(path, tail, { flag: 'a' })
 
-    const reopenedCtx = new Context()
-    await reopenedCtx.plugin(SessionStore)
-    await reopenedCtx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
-    expect((await reopenedCtx.sessionPersistence.listSnapshots())[0]?.revision).toBe(revision)
+    // A reader serves the valid contiguous prefix — the complete tail lines
+    // ARE committed reads, the torn fragment never is — without repairing.
+    const loaded = await readAll(ctx.sessionPersistence, m.id)
+    expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+    expect(await readFile(path)).toEqual(Buffer.concat([committed, Buffer.from(tail)]))
 
-    const otherRoot = await freshRoot()
-    const otherCtx = new Context()
-    await otherCtx.plugin(SessionStore)
-    await otherCtx.plugin(JsonlSessionPersistence, { root: otherRoot, compression: 'none' })
-    await otherCtx.sessionPersistence.create(m)
-    await otherCtx.sessionPersistence.append(m.id, oneTurnLog())
-    expect((await otherCtx.sessionPersistence.listSnapshots())[0]?.revision).not.toBe(revision)
-
-    await reopenedCtx.fiber.dispose()
-    await otherCtx.fiber.dispose()
+    // The write path truncates the torn fragment durably before its first
+    // append, preserving every committed byte before it.
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    await appendBatch(ctx.sessionPersistence, m.id, [
+      { type: 'step/end', seq: SessionSeq(8), time: 10, data: { turn: 2, step: 1 } },
+      { type: 'turn/end', seq: SessionSeq(9), time: 11, data: { turn: 2, reason: { kind: 'interrupted' } } },
+    ])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('recovered from a torn tail'))
+    const repaired = await readFile(path, 'utf8')
+    expect(repaired.startsWith(committed.toString('utf8'))).toBe(true)
+    expect(repaired).not.toContain('assistant/chunk')
+    const reloaded = await readAll(ctx.sessionPersistence, m.id)
+    expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
   })
 
-  it('binds a full stored prefix to the same revision as a lightweight read', async () => {
-    const m = meta('stored-prefix-revision')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    const persistence = ctx.sessionPersistence as JsonlSessionPersistence
-
-    const stored = await persistence.loadStored(m.id)
-    expect(stored?.revision).toBe(await persistence.readStoredRevision(m.id))
-    expect(await persistence.readStoredRevision(SessionId('missing-revision'))).toBeUndefined()
+  it('a stored open turn is served as stored, with no synthetic closers', async () => {
+    // Logical repair (closing an interrupted turn) is a resume concern; the
+    // storage seam returns exactly the committed events.
+    const m = meta('open-turn', '/h')
+    await writeLog(ctx.sessionPersistence, m, [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
+    ])
+    const { events } = await readAll(ctx.sessionPersistence, m.id)
+    expect(events.map(e => e.type)).toEqual(['turn/start'])
   })
 
-  it('retries a full-prefix read when the file revision changes during the read', async () => {
-    const m = meta('stored-prefix-revision-race')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    const persistence = ctx.sessionPersistence as JsonlSessionPersistence
-    statRace.path = rawLogPath(root, m.cwd, m.id)
+  it('a failed appendLines truncates partial bytes so a retry has no seq gap', async () => {
+    const m = meta('truncate-retry')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog()) // materialized, seqs 0..5
+    const sizeBefore = (await stat(rawLogPath(root, undefined, m.id))).size
 
-    await expect(persistence.loadStored(m.id)).resolves.toMatchObject({ events: oneTurnLog() })
-    expect(statRace.reads).toBe(4)
+    const handle = await ctx.sessionPersistence.open(m.id, 'write')
+    try {
+      // Force the NEXT fsync (inside appendLines) to fail once, AFTER writeFile
+      // has already put bytes on disk — simulating an ENOSPC/fsync error
+      // mid-append. The recovery truncate() also fsyncs, so allow that one.
+      const probe = await (await import('node:fs/promises')).open(rawLogPath(root, undefined, m.id), 'r')
+      const proto = Object.getPrototypeOf(probe) as { sync: () => Promise<void> }
+      await probe.close()
+      const realSync = proto.sync
+      let failed = false
+      const spy = vi.spyOn(proto, 'sync').mockImplementation(async function (this: unknown) {
+        if (!failed) { failed = true; throw new Error('simulated fsync ENOSPC') }
+        return realSync.call(this)
+      })
+
+      const turn2: SessionEvent[] = [
+        { type: 'turn/start', seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+        { type: 'turn/end', seq: SessionSeq(7), time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
+      ]
+      // The append rejects, but the partial bytes are truncated back: the file
+      // is its pre-append size and the handle cursor is unchanged.
+      await expect(handle.append(turn2)).rejects.toThrow(/ENOSPC/)
+      expect((await stat(rawLogPath(root, undefined, m.id))).size).toBe(sizeBefore)
+      spy.mockRestore()
+
+      // The retry now succeeds with NO seq gap — the log is contiguous 0..7.
+      await handle.append(turn2)
+      expect((await handle.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+    } finally {
+      await handle.close()
+    }
   })
 
-  it('handles revision-stat races and errors after log discovery', async () => {
+  it('reports both the append failure and a failed rollback', async () => {
+    const m = meta('rollback-failure')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+
+    const path = rawLogPath(root, undefined, m.id)
+    const probe = await (await import('node:fs/promises')).open(path, 'r')
+    const proto = Object.getPrototypeOf(probe) as { sync: () => Promise<void> }
+    await probe.close()
+    const realSync = proto.sync
+    let failed = false
+    const syncSpy = vi.spyOn(proto, 'sync').mockImplementation(async function (this: unknown) {
+      if (!failed) { failed = true; throw new Error('simulated append fsync failure') }
+      return realSync.call(this)
+    })
+    const backend = ctx.sessionPersistence as unknown as {
+      rollbackAppend: (path: string, size: number) => Promise<void>
+    }
+    const realRollback = backend.rollbackAppend.bind(backend)
+    backend.rollbackAppend = () => Promise.reject(new Error('simulated rollback failure'))
+
+    try {
+      await appendBatch(ctx.sessionPersistence, m.id, [
+        { type: 'turn/start', seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+      ])
+      throw new Error('expected append to reject')
+    } catch (error) {
+      expect(error).toBeInstanceOf(AggregateError)
+      const aggregate = error as AggregateError
+      expect(aggregate.message).toContain(`failed to roll back append to "${path}"`)
+      expect(aggregate.errors).toHaveLength(2)
+      expect(aggregate.errors[0]).toMatchObject({ message: 'simulated append fsync failure' })
+      expect(aggregate.errors[1]).toMatchObject({ message: 'simulated rollback failure' })
+    } finally {
+      backend.rollbackAppend = realRollback
+      syncSpy.mockRestore()
+    }
+  })
+
+  it('rejects a mismatched header id before serving either session log', async () => {
+    const a = meta('identity-a', '/same')
+    const b = meta('identity-b', '/same')
+    await writeLog(ctx.sessionPersistence, a, [{
+      type: 'turn/start',
+      seq: SessionSeq(0),
+      time: 1,
+      data: { turn: 1 },
+    }])
+    await writeLog(ctx.sessionPersistence, b, oneTurnLog())
+
+    const aPath = rawLogPath(root, a.cwd, a.id)
+    const bPath = rawLogPath(root, b.cwd, b.id)
+    await rewriteHeader(aPath, (header) => { header.id = b.id })
+    const beforeA = await readFile(aPath)
+    const beforeB = await readFile(bPath)
+
+    await expect(readAll(ctx.sessionPersistence, a.id))
+      .rejects.toThrow(/requested id "identity-a" does not match header id "identity-b"/)
+    expect(await readFile(aPath)).toEqual(beforeA)
+    expect(await readFile(bPath)).toEqual(beforeB)
+  })
+
+  it('path-traversal session ids are neutralized (no escape from root)', async () => {
+    const evil = SessionId('../../etc/pwn')
+    const m = { version: 0, id: evil, createdAt: 1, isSeeded: false }
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    // The file lives UNDER root, not at ../../etc.
+    const all: string[] = []
+    async function walk(dir: string): Promise<void> {
+      for (const e of await readdir(dir, { withFileTypes: true })) {
+        const p = join(dir, e.name)
+        if (e.isDirectory()) await walk(p)
+        else all.push(p)
+      }
+    }
+    await walk(root)
+    expect(all.length).toBeGreaterThan(0)
+    expect(all.every(p => p.startsWith(root))).toBe(true)
+  })
+
+  it('rejects pre-aborted operations with the exact cancellation reason', async () => {
+    const m = meta('pre-aborted')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const reason = new Error('persistence operation cancelled')
+    const controller = new AbortController()
+    controller.abort(reason)
+    const signal = controller.signal
+
+    await expect(ctx.sessionPersistence.create(meta('aborted-create'), { signal })).rejects.toBe(reason)
+    await expect(ctx.sessionPersistence.open(m.id, 'read', { signal })).rejects.toBe(reason)
+    await expect(ctx.sessionPersistence.open(m.id, 'write', { signal })).rejects.toBe(reason)
+    await expect(ctx.sessionPersistence.stat(m.id, { signal })).rejects.toBe(reason)
+    await expect(ctx.sessionPersistence.list({ signal })).rejects.toBe(reason)
+
+    const handle = await ctx.sessionPersistence.open(m.id, 'write')
+    try {
+      await expect(handle.read(0, undefined, { signal })).rejects.toBe(reason)
+      await expect(handle.append([
+        { type: 'turn/start', seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+      ], { signal })).rejects.toBe(reason)
+      await expect(handle.flush({ signal })).rejects.toBe(reason)
+      // The aborted mutations left the log untouched.
+      expect((await handle.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5])
+    } finally {
+      await handle.close()
+    }
+  })
+
+  it('stat handles artifact removal and non-ENOENT failures after log discovery', async () => {
     const m = meta('stored-revision-race')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
     const persistence = ctx.sessionPersistence as JsonlSessionPersistence
     const internals = persistence as unknown as {
       findLog(id: SessionId, signal?: AbortSignal): Promise<string | undefined>
@@ -522,27 +904,111 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
     const findLog = vi.spyOn(internals, 'findLog').mockResolvedValue(path)
 
     await rm(path)
-    expect(await persistence.readStoredRevision(m.id)).toBeUndefined()
+    expect(await persistence.stat(m.id)).toBeUndefined()
 
     const invalidPath = `${path}\0`
     findLog.mockResolvedValue(invalidPath)
-    await expect(persistence.readStoredRevision(m.id)).rejects.toMatchObject({
+    await expect(persistence.stat(m.id)).rejects.toMatchObject({
       code: 'ERR_INVALID_ARG_VALUE',
     })
 
-    const reason = new Error('revision read cancelled after discovery')
+    const reason = new Error('stat cancelled after discovery')
     const controller = new AbortController()
     findLog.mockImplementation(async () => {
       controller.abort(reason)
       return invalidPath
     })
-    await expect(persistence.readStoredRevision(m.id, controller.signal)).rejects.toBe(reason)
+    await expect(persistence.stat(m.id, { signal: controller.signal })).rejects.toBe(reason)
   })
 
-  it('omits a snapshot artifact removed after discovery', async () => {
+  it('stat reports absence for an artifact vanishing before its identity stat and surfaces other faults', async () => {
+    const m = meta('stat-fault', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    // The header read succeeds; the identity stat then loses the file (a
+    // concurrent removal) or hits a storage fault.
+    statFailure.path = rawLogPath(root, '/work', m.id)
+    statFailure.error = Object.assign(new Error('ENOENT: vanished'), { code: 'ENOENT' })
+    expect(await ctx.sessionPersistence.stat(m.id)).toBeUndefined()
+    statFailure.error = Object.assign(new Error('EACCES: denied'), { code: 'EACCES' })
+    await expect(ctx.sessionPersistence.stat(m.id)).rejects.toThrow(/EACCES/)
+  })
+
+  it('an empty append batch is a no-op that does not materialize', async () => {
+    const m = meta('empty-batch', '/work')
+    const handle = await ctx.sessionPersistence.create(m)
+    await handle.append([])
+    await expect(stat(rawLogPath(root, '/work', m.id))).rejects.toThrow()
+    await handle.append(oneTurnLog())
+    expect((await handle.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5])
+    await handle.close()
+  })
+
+  it('lists a pending id once when an artifact for the same id appears beneath it', async () => {
+    const m = meta('shadowed', '/w')
+    const creator = await ctx.sessionPersistence.create(m)
+    // An artifact materialized outside this instance's create/append path.
+    await mkdir(sessionDir(root, '/w', m.id), { recursive: true })
+    await writeFile(rawLogPath(root, '/w', m.id), [
+      JSON.stringify(toHeaderLine(m)),
+      ...oneTurnLog().map(e => JSON.stringify(e)),
+    ].join('\n') + '\n')
+
+    const entries = (await ctx.sessionPersistence.list()).filter(s => s.header.id === m.id)
+    expect(entries).toHaveLength(1)
+    // The artifact entry wins over the pending one.
+    expect(entries[0]!.sizeBytes).toBeDefined()
+    await creator.close()
+  })
+
+  it('a read handle over an erased pending session fails loudly', async () => {
+    const m = meta('erased-pending')
+    const creator = await ctx.sessionPersistence.create(m)
+    const reader = await ctx.sessionPersistence.open(m.id, 'read')
+    expect(await reader.read()).toEqual([])
+    // The creator closes without ever appending: the session never existed.
+    await creator.close()
+    await expect(reader.read()).rejects.toThrow(/not found/)
+    await reader.close()
+  })
+
+  it('a read handle rejects a stored log that shrank below an observed prefix', async () => {
+    const m = meta('shrunk', '/work')
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
+    const reader = await ctx.sessionPersistence.open(m.id, 'read')
+    try {
+      expect(await reader.read()).toHaveLength(6)
+      // Committed events are never rewritten; a shorter file is damage, not a
+      // legal state, and a handle must not silently backtrack.
+      await writeFile(rawLogPath(root, '/work', m.id), [
+        JSON.stringify(toHeaderLine(m)),
+        JSON.stringify(oneTurnLog()[0]),
+      ].join('\n') + '\n')
+      await expect(reader.read()).rejects.toThrow(/shrank below a previously observed prefix/)
+    } finally {
+      await reader.close()
+    }
+  })
+
+  it('backend dispose aggregates open-handle close failures into one reported error', async () => {
+    const ctx2 = new Context()
+    const fiber = await ctx2.plugin(JsonlSessionPersistence, { root, compression: 'none' })
+    const reported = vi.spyOn(ctx2.logger, 'error').mockImplementation(() => undefined)
+    const handle = await ctx2.sessionPersistence.create(meta('dispose-fail'))
+    const failure = new Error('close exploded')
+    vi.spyOn(handle, 'close').mockRejectedValue(failure)
+    await fiber.dispose()
+    // Cordis contains effect-disposal failures and reports them; the backend's
+    // teardown aggregate names every handle that refused to close.
+    const aggregate = reported.mock.calls
+      .map((call): unknown => call[0])
+      .find((value): value is AggregateError => value instanceof AggregateError)
+    expect(aggregate?.message).toContain('session-persistence-jsonl dispose failed')
+    expect(aggregate?.errors).toEqual([failure])
+  })
+
+  it('omits a listed artifact removed after discovery', async () => {
     const m = meta('vanishing-snapshot')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
     const persistence = ctx.sessionPersistence as unknown as {
       listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>>
     }
@@ -553,11 +1019,11 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
       return artifacts
     })
 
-    await expect(ctx.sessionPersistence.listSnapshots()).resolves.toEqual([])
+    await expect(ctx.sessionPersistence.list()).resolves.toEqual([])
     discovery.mockRestore()
   })
 
-  it('surfaces non-ENOENT snapshot stat failures after discovery', async () => {
+  it('surfaces non-ENOENT stat failures during listing', async () => {
     const persistence = ctx.sessionPersistence as unknown as {
       listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>>
     }
@@ -566,25 +1032,25 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
       path: `${root}\0snapshot-stat-failure`,
     }])
 
-    await expect(ctx.sessionPersistence.listSnapshots()).rejects.toThrow(/null bytes/)
+    await expect(ctx.sessionPersistence.list()).rejects.toThrow(/null bytes/)
     discovery.mockRestore()
   })
 
-  it('forwards snapshot-list cancellation and awaits in-flight discovery cleanup', async () => {
+  it('forwards list cancellation and awaits in-flight discovery cleanup', async () => {
     const persistence = ctx.sessionPersistence as unknown as {
       listArtifacts(signal?: AbortSignal): Promise<Array<{ header: SessionHeader; path: string }>>
     }
     const started = Promise.withResolvers<AbortSignal>()
     const cleanup = Promise.withResolvers<undefined>()
     vi.spyOn(persistence, 'listArtifacts').mockImplementation(async (signal) => {
-      if (signal === undefined) throw new Error('expected snapshot-list signal')
+      if (signal === undefined) throw new Error('expected list signal')
       started.resolve(signal)
       await cleanup.promise
       return []
     })
-    const reason = new Error('JSONL snapshot discovery cancelled')
+    const reason = new Error('JSONL list discovery cancelled')
     const controller = new AbortController()
-    const pending = ctx.sessionPersistence.listSnapshots(controller.signal)
+    const pending = ctx.sessionPersistence.list({ signal: controller.signal })
     expect(await started.promise).toBe(controller.signal)
     let settled = false
     void pending.then(
@@ -600,10 +1066,9 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
     await expect(pending).rejects.toBe(reason)
   })
 
-  it('checks cancellation after an uncancellable snapshot stat settles', async () => {
+  it('checks cancellation after an uncancellable list stat settles', async () => {
     const m = meta('snapshot-stat-cancellation')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
     const persistence = ctx.sessionPersistence as unknown as {
       listArtifacts(signal?: AbortSignal): Promise<Array<{ header: SessionHeader; path: string }>>
     }
@@ -611,305 +1076,16 @@ describe('JsonlSessionPersistence: durability and crash semantics', () => {
       header: m,
       path: rawLogPath(root, m.cwd, m.id),
     }])
-    const reason = new Error('JSONL snapshot stat cancelled')
+    const reason = new Error('JSONL list stat cancelled')
     const controller = new AbortController()
-    const pending = ctx.sessionPersistence.listSnapshots(controller.signal)
+    const pending = ctx.sessionPersistence.list({ signal: controller.signal })
     queueMicrotask(() => { controller.abort(reason) })
 
     await expect(pending).rejects.toBe(reason)
     expect(discovery).toHaveBeenCalledWith(controller.signal)
   })
-
-  it('rejects a stored v0 log containing a legacy request/header-delta event', async () => {
-    const m = meta('legacy-header-delta', '/legacy')
-    const path = rawLogPath(root, m.cwd, m.id)
-    await mkdir(sessionDir(root, m.cwd, m.id), { recursive: true })
-    await writeFile(path, [
-      JSON.stringify(toHeaderLine(m)),
-      JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }),
-      JSON.stringify({ type: 'request/header-delta', seq: 1, time: 2, data: { config: { model: 'legacy' } } }),
-      JSON.stringify({ type: 'turn/end', seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }),
-      '',
-    ].join('\n'))
-
-    await expect(ctx.sessionPersistence.load(m.id)).rejects.toThrow(/unsupported legacy request\/header-delta event at seq 1/)
-  })
-
-  it('rejects a stored v0 full header carrying the legacy fallback reason', async () => {
-    const m = meta('legacy-header-fallback', '/legacy')
-    const path = rawLogPath(root, m.cwd, m.id)
-    await mkdir(sessionDir(root, m.cwd, m.id), { recursive: true })
-    await writeFile(path, [
-      JSON.stringify(toHeaderLine(m)),
-      JSON.stringify({
-        type: 'request/header',
-        seq: 0,
-        time: 1,
-        data: { header: { config: { model: 'legacy' } }, reason: 'fallback' },
-      }),
-      '',
-    ].join('\n'))
-
-    await expect(ctx.sessionPersistence.load(m.id))
-      .rejects.toThrow(/unsupported legacy request\/header reason "fallback" at seq 0/)
-  })
-
-  it('persists a forked child seed through the existing session write path', async () => {
-    const source = ctx.sessions.create(SessionId('persist-parent'), { meta: { cwd: '/workspace' } })
-    appendClosedTurn(source)
-
-    const child = ctx.sessions.fork(source, undefined, SessionId('persist-child'))
-    await ctx.sessions.flush(child)
-    const loaded = await ctx.sessionPersistence.load(child.id)
-
-    // The constructor seed reaches disk verbatim, then the child's end-seed.
-    expect(loaded.events.slice(0, source.snapshotEvents().length)).toEqual(source.snapshotEvents())
-    expect(loaded.events.at(-1)).toMatchObject({ type: 'session/end-seed', seq: source.snapshotEvents().length })
-    expect(loaded.meta).toMatchObject({
-      id: SessionId('persist-child'),
-      cwd: '/workspace',
-      parentSession: SessionId('persist-parent'),
-      isSeeded: true,
-    })
-    expect(loaded.inheritedEventCount).toBe(source.seq)
-    await expect(ctx.sessionPersistence.readRaw(child.id)).resolves.toMatchObject({
-      meta: { isSeeded: true },
-      inheritedEventCount: source.seq,
-    })
-  })
-
-  it('crash recovery: load preserves the interrupted turn and closes it with a synthetic turn/end {interrupted}', async () => {
-    const m = meta('crash', '/proj')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog()) // seqs 0..5, turn/end at 5
-
-    // Simulate a crash mid-second-turn: append raw lines that are NOT closed by
-    // a turn/end (turn/start + step/start are fully written), plus a final
-    // partial line with no newline (a torn fragment never fully flushed).
-    const path = rawLogPath(root, '/proj', m.id)
-    await writeFile(path, [
-      JSON.stringify({ type: 'turn/start', seq: 6, time: 8, data: { turn: 2 } }),
-      JSON.stringify({ type: 'step/start', seq: 7, time: 9, data: { turn: 2, step: 1 } }),
-      '{"type":"assistant/chunk","seq":8,"ti', // truncated partial line (no newline)
-    ].join('\n'), { flag: 'a' })
-
-    // load PRESERVES the interrupted turn's real events (turn/start 6, step/start
-    // 7) — a turn can be huge, so they must not be truncated — and durably closes
-    // the orphaned turn with synthetic step/end (8) + turn/end {interrupted} (9).
-    const loaded = await ctx.sessionPersistence.load(m.id)
-    expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
-    const last = loaded.events.at(-1)!
-    expect(last.type === 'turn/end' && last.data.reason).toEqual({ kind: 'interrupted' })
-    const stepEnd = loaded.events[8]!
-    expect(stepEnd.type).toBe('step/end')
-    // the torn seq-8 chunk fragment did not survive
-    expect(loaded.events.some(e => e.type === 'assistant/chunk' && e.seq === 8)).toBe(false)
-
-    // The next append continues at seq 10 (the balanced length).
-    const turn3 = [
-      { type: 'turn/start', seq: 10, time: 11, data: { turn: 3 } },
-      { type: 'turn/end', seq: 11, time: 12, data: { turn: 3, reason: { kind: 'completed' } } },
-    ] as SessionEvent[]
-    await ctx.sessionPersistence.append(m.id, turn3)
-    const reloaded = await ctx.sessionPersistence.load(m.id)
-    expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
-  })
-
-  it('committed events are never rewritten: only the crash tail is repaired', async () => {
-    const m = meta('append-only')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    const before = await readFile(rawLogPath(root, undefined, m.id), 'utf8')
-    const committedPrefix = before // the whole committed log
-
-    // A crash tail then a repair-append.
-    await writeFile(rawLogPath(root, undefined, m.id), '\n{"partial', { flag: 'a' })
-    await ctx.sessionPersistence.load(m.id)
-    await ctx.sessionPersistence.append(m.id, [
-      { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } },
-      { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
-    ] as SessionEvent[])
-    const after = await readFile(rawLogPath(root, undefined, m.id), 'utf8')
-    // the committed prefix is byte-for-byte intact at the head of the file
-    expect(after.startsWith(committedPrefix)).toBe(true)
-  })
-
-  it('a failed appendLines truncates partial bytes so a retry has no seq gap', async () => {
-    const m = meta('truncate-retry')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog()) // materialized, seqs 0..5
-    const sizeBefore = (await stat(rawLogPath(root, undefined, m.id))).size
-
-    // Force the NEXT fsync (inside appendLines) to fail once, AFTER writeFile
-    // has already put bytes on disk — simulating an ENOSPC/fsync error
-    // mid-append. The recovery truncate() also fsyncs, so allow that one.
-    const handle = await (await import('node:fs/promises')).open(rawLogPath(root, undefined, m.id), 'r')
-    const proto = Object.getPrototypeOf(handle) as { sync: () => Promise<void> }
-    await handle.close()
-    const realSync = proto.sync
-    let failed = false
-    const spy = vi.spyOn(proto, 'sync').mockImplementation(async function (this: unknown) {
-      if (!failed) { failed = true; throw new Error('simulated fsync ENOSPC') }
-      return realSync.call(this)
-    })
-
-    const turn2 = [
-      { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } },
-      { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
-    ] as SessionEvent[]
-    // The append rejects, but the partial bytes are truncated back: the file is
-    // its pre-append size and the cursor is unchanged.
-    await expect(ctx.sessionPersistence.append(m.id, turn2)).rejects.toThrow(/ENOSPC/)
-    expect((await stat(rawLogPath(root, undefined, m.id))).size).toBe(sizeBefore)
-    spy.mockRestore()
-
-    // The retry now succeeds with NO seq gap — the log is contiguous 0..7.
-    await ctx.sessionPersistence.append(m.id, turn2)
-    const loaded = await ctx.sessionPersistence.load(m.id)
-    expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
-  })
-
-  it('reports both the append failure and a failed rollback', async () => {
-    const m = meta('rollback-failure')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-
-    const path = rawLogPath(root, undefined, m.id)
-    const handle = await (await import('node:fs/promises')).open(path, 'r')
-    const proto = Object.getPrototypeOf(handle) as { sync: () => Promise<void> }
-    await handle.close()
-    const realSync = proto.sync
-    let failed = false
-    const syncSpy = vi.spyOn(proto, 'sync').mockImplementation(async function (this: unknown) {
-      if (!failed) { failed = true; throw new Error('simulated append fsync failure') }
-      return realSync.call(this)
-    })
-    const backend = ctx.sessionPersistence as unknown as {
-      rollbackAppend: (path: string, size: number) => Promise<void>
-    }
-    const realRollback = backend.rollbackAppend.bind(backend)
-    backend.rollbackAppend = () => Promise.reject(new Error('simulated rollback failure'))
-
-    try {
-      await ctx.sessionPersistence.append(m.id, [
-        { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } },
-      ] as SessionEvent[])
-      throw new Error('expected append to reject')
-    } catch (error) {
-      expect(error).toBeInstanceOf(AggregateError)
-      const aggregate = error as AggregateError
-      expect(aggregate.message).toContain(`failed to roll back append to "${path}"`)
-      expect(aggregate.errors).toHaveLength(2)
-      expect(aggregate.errors[0]).toMatchObject({ message: 'simulated append fsync failure' })
-      expect(aggregate.errors[1]).toMatchObject({ message: 'simulated rollback failure' })
-    } finally {
-      backend.rollbackAppend = realRollback
-      syncSpy.mockRestore()
-    }
-  })
-
-  it('load returns immutable meta without exposing backend pathing', async () => {
-    const m = meta('meta-copy', '/proj')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    const loaded = await ctx.sessionPersistence.load(m.id)
-    expect(() => { mutableHeader(loaded.meta).cwd = '/evil' }).toThrow()
-    await ctx.sessionPersistence.append(m.id, [
-      { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } },
-      { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
-    ] as SessionEvent[])
-    // The append landed in the ORIGINAL /proj log, not beside an /evil path.
-    const reloaded = await ctx.sessionPersistence.load(m.id)
-    expect(reloaded.meta.cwd).toBe('/proj')
-    expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
-  })
-
-  it('rejects a mismatched header before repairing either session log', async () => {
-    const a = meta('identity-a', '/same')
-    const b = meta('identity-b', '/same')
-    await ctx.sessionPersistence.create(a)
-    await ctx.sessionPersistence.append(a.id, [{
-      type: 'turn/start',
-      seq: SessionSeq(0),
-      time: 1,
-      data: { turn: 1 },
-    }])
-    await ctx.sessionPersistence.create(b)
-    await ctx.sessionPersistence.append(b.id, oneTurnLog())
-
-    const aPath = rawLogPath(root, a.cwd, a.id)
-    const bPath = rawLogPath(root, b.cwd, b.id)
-    await rewriteHeader(aPath, (header) => { header.id = b.id })
-    const beforeA = await readFile(aPath)
-    const beforeB = await readFile(bPath)
-
-    await expect(ctx.sessionPersistence.load(a.id))
-      .rejects.toThrow(/requested id "identity-a" does not match header id "identity-b"/)
-    expect(await readFile(aPath)).toEqual(beforeA)
-    expect(await readFile(bPath)).toEqual(beforeB)
-  })
-
-  it('rejects a re-append of an already-stored seq', async () => {
-    const m = meta('reappend')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    await expect(ctx.sessionPersistence.append(m.id, oneTurnLog())).rejects.toThrow(/seq mismatch/)
-  })
-
-  it('path-traversal session ids are neutralized (no escape from root)', async () => {
-    const evil = SessionId('../../etc/pwn')
-    const m = { version: 0, id: evil, createdAt: 1, isSeeded: false }
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(evil, oneTurnLog())
-    // The file lives UNDER root, not at ../../etc.
-    const all: string[] = []
-    async function walk(dir: string): Promise<void> {
-      for (const e of await readdir(dir, { withFileTypes: true })) {
-        const p = join(dir, e.name)
-        if (e.isDirectory()) await walk(p)
-        else all.push(p)
-      }
-    }
-    await walk(root)
-    expect(all.length).toBeGreaterThan(0)
-    expect(all.every(p => p.startsWith(root))).toBe(true)
-  })
 })
 
-describe('JsonlSessionPersistence: write path (session/event → flush)', () => {
-  it('concurrent sessions do not cross buffers', async () => {
-    root = await freshRoot()
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
-
-    const a = ctx.sessions.create(SessionId('sa'))
-    const b = ctx.sessions.create(SessionId('sb'))
-    a.append('turn/start', { turn: 1 })
-    b.append('turn/start', { turn: 1 })
-    a.append('user/message', createUserMessage({
-      content: [{ type: 'text', text: 'A' }], source: { kind: 'user' },
-    }), { surfaceOp: 'append' })
-    b.append('user/message', createUserMessage({
-      content: [{ type: 'text', text: 'B' }], source: { kind: 'user' },
-    }), { surfaceOp: 'append' })
-    a.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    b.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    await ctx.sessions.flush(a)
-    await ctx.sessions.flush(b)
-
-    const la = await ctx.sessionPersistence.load(SessionId('sa'))
-    const lb = await ctx.sessionPersistence.load(SessionId('sb'))
-    expect(JSON.stringify(la.events)).toContain('"A"')
-    expect(JSON.stringify(la.events)).not.toContain('"B"')
-    expect(JSON.stringify(lb.events)).toContain('"B"')
-    expect(JSON.stringify(lb.events)).not.toContain('"A"')
-    await ctx.fiber.dispose()
-  })
-
-})
-
-
 describe('JsonlSessionPersistence: scanLog unit', () => {
   it('requires exactly one newline-terminated header record', () => {
     const header = JSON.stringify(toHeaderLine(meta('scanner-header')))
@@ -939,14 +1115,14 @@ describe('JsonlSessionPersistence: scanLog unit', () => {
     scanner.write(Buffer.from([
       JSON.stringify(oneTurnLog()[0]),
       '{not json',
-      JSON.stringify({ type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } }),
+      JSON.stringify({ type: 'step/start', seq: SessionSeq(1), time: 2, data: { turn: 1, step: 1 } }),
       '',
     ].join('\n')))
     expect(scanner.finish().events).toEqual([oneTurnLog()[0]])
 
     const committed = new SessionLogScanner(header)
     expect(() => { committed.write(Buffer.from([
-      JSON.stringify({ type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } }),
+      JSON.stringify({ type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } }),
       '',
     ].join('\n'))) }).toThrow(/seq gap in committed region/)
   })
@@ -1027,8 +1203,8 @@ describe('JsonlSessionPersistence: scanLog unit', () => {
     const line = toHeaderLine({
       version: 0,
       id: SessionId('composed'),
-      createdAt: 1,
       isSeeded: false,
+      createdAt: 1,
       delegationDepth: 0,
       agentPreset: 'minimal',
     })
@@ -1048,21 +1224,21 @@ describe('JsonlSessionPersistence: scanLog unit', () => {
   it('a seq gap after the last turn/end bounds the preserved tail (torn fragment tolerated)', () => {
     const log = [
       JSON.stringify({ type: 'session', version: 0, id: 'g', createdAt: 1, delegationDepth: 0 }),
-      JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }),
-      JSON.stringify({ type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }), // gap: missing seq 1
+      JSON.stringify({ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }),
+      JSON.stringify({ type: 'step/start', seq: SessionSeq(2), time: 2, data: { turn: 1, step: 1 } }), // gap: missing seq 1
     ].join('\n') + '\n'
-    // No committed turn/end, so the gap is a tolerated crash boundary: scanLog PRESERVES the
-    // contiguous prefix (turn/start seq 0) — real interrupted-turn work, not discarded — and
-    // stops at the gap. `loadCore`, not this scanner, later closes the orphaned turn.
+    // No committed turn/end, so the gap is a tolerated crash boundary: scanLog
+    // PRESERVES the contiguous prefix (turn/start seq 0) — real interrupted-turn
+    // work, not discarded — and stops at the gap.
     expect(scanLog(Buffer.from(log)).events.map(e => e.seq)).toEqual([0])
   })
 
   it('rejects a seq gap BEFORE a later committed turn/end (committed data damaged)', () => {
     const log = [
       JSON.stringify({ type: 'session', version: 0, id: 'g2', createdAt: 1, delegationDepth: 0 }),
-      JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }),
-      JSON.stringify({ type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }), // gap: missing seq 1
-      JSON.stringify({ type: 'turn/end', seq: 3, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }),
+      JSON.stringify({ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }),
+      JSON.stringify({ type: 'step/start', seq: SessionSeq(2), time: 2, data: { turn: 1, step: 1 } }), // gap: missing seq 1
+      JSON.stringify({ type: 'turn/end', seq: SessionSeq(3), time: 3, data: { turn: 1, reason: { kind: 'completed' } } }),
     ].join('\n') + '\n'
     // A turn/end exists, so the prefix up to it is committed — but it has a hole.
     // Truncating it would silently drop committed data → unloadable.
@@ -1079,7 +1255,7 @@ describe('JsonlSessionPersistence: scanLog unit', () => {
       const log = [
         JSON.stringify({ type: 'session', version: 0, id: 'c', createdAt: 1, delegationDepth: 0 }),
         record,
-        JSON.stringify({ type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } }),
+        JSON.stringify({ type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } }),
       ].join('\n') + '\n'
       expect(() => scanLog(Buffer.from(log))).toThrow(/unparsable committed event/)
     }
@@ -1096,7 +1272,7 @@ describe('JsonlSessionPersistence: scanLog unit', () => {
   it('a corrupt line after the last turn/end bounds the preserved tail', () => {
     const log = [
       JSON.stringify({ type: 'session', version: 0, id: 'c2', createdAt: 1, delegationDepth: 0 }),
-      JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }),
+      JSON.stringify({ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }),
       '{not json', // corrupt crash fragment, no turn/end committed
     ].join('\n') + '\n'
     // The contiguous prefix (turn/start seq 0) is preserved; the corrupt
@@ -1107,9 +1283,9 @@ describe('JsonlSessionPersistence: scanLog unit', () => {
   it('tolerates a seq gap AFTER a turn/end (uncommitted tail)', () => {
     const log = [
       JSON.stringify({ type: 'session', version: 0, id: 't', createdAt: 1, delegationDepth: 0 }),
-      JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }),
-      JSON.stringify({ type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } }),
-      JSON.stringify({ type: 'step/start', seq: 9, time: 3, data: { turn: 2, step: 1 } }), // gap in uncommitted tail
+      JSON.stringify({ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }),
+      JSON.stringify({ type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } }),
+      JSON.stringify({ type: 'step/start', seq: SessionSeq(9), time: 3, data: { turn: 2, step: 1 } }), // gap in uncommitted tail
     ].join('\n') + '\n'
     const { events } = scanLog(Buffer.from(log))
     expect(events.map(e => e.seq)).toEqual([0, 1]) // tail dropped
@@ -1121,7 +1297,6 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
   beforeEach(async () => {
     root = await freshRoot()
     ctx = new Context()
-    await ctx.plugin(SessionStore)
     // compression: 'none' — these tests assert the textual storage-record layout
     // (row tags per line); packing is orthogonal to the physical encoding.
     await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
@@ -1159,21 +1334,19 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
   it('writes a delta run as one text-chunks row by default and loads back identical events', async () => {
     const m = meta('packed', '/work')
     const log = chunkRunLog()
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, log)
+    await writeLog(ctx.sessionPersistence, m, log)
 
     const raw = (await readFile(rawLogPath(root, '/work', m.id), 'utf8')).split('\n').filter(Boolean)
     const tags = raw.slice(1).map(line => (JSON.parse(line) as { type: string }).type)
     expect(tags).toEqual(['turn/start', 'step/start', 'text-chunks', 'assistant/message', 'step/end', 'turn/end'])
 
-    const loaded = await ctx.sessionPersistence.load(m.id)
+    const loaded = await readAll(ctx.sessionPersistence, m.id)
     expect(loaded.events).toEqual(log)
   })
 
   it('packChunks: false writes one event per line and still loads identical events', async () => {
     const unpackedRoot = await freshRoot()
     const unpacked = new Context()
-    await unpacked.plugin(SessionStore)
     await unpacked.plugin(JsonlSessionPersistence, {
       root: unpackedRoot,
       packChunks: false,
@@ -1182,15 +1355,14 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
     try {
       const m = meta('unpacked', '/work')
       const log = chunkRunLog()
-      await unpacked.sessionPersistence.create(m)
-      await unpacked.sessionPersistence.append(m.id, log)
+      await writeLog(unpacked.sessionPersistence, m, log)
 
       const records = (await readFile(rawLogPath(unpackedRoot, '/work', m.id), 'utf8'))
         .split('\n').filter(Boolean).slice(1)
         .map(line => JSON.parse(line) as { type: string })
       expect(records.filter(record => record.type === 'assistant/chunk')).toHaveLength(5)
       expect(records.some(record => record.type === 'text-chunks')).toBe(false)
-      expect((await unpacked.sessionPersistence.load(m.id)).events).toEqual(log)
+      expect((await readAll(unpacked.sessionPersistence, m.id)).events).toEqual(log)
     } finally {
       await unpacked.fiber.dispose()
     }
@@ -1200,7 +1372,7 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
     const m = meta('mixed', '/work')
     const log = chunkRunLog()
     // First turn written line-per-event by an unpacked-config writer (an old
-    // file, hand-planted so this packed-config backend adopts it on load).
+    // file, hand-planted so this packed-config backend adopts it on open).
     await mkdir(sessionDir(root, '/work', m.id), { recursive: true })
     await writeFile(rawLogPath(root, '/work', m.id), [
       JSON.stringify({ type: 'session', version: 0, id: 'mixed', createdAt: 1000, cwd: '/work', delegationDepth: 0 }),
@@ -1208,15 +1380,15 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
     ].join('\n') + '\n')
     // Adopt the stored log (cursor = stored length), then append a second turn
     // through THIS packed-config backend.
-    expect((await ctx.sessionPersistence.load(m.id)).events).toEqual(log)
+    expect((await readAll(ctx.sessionPersistence, m.id)).events).toEqual(log)
     const secondTurn: SessionEvent[] = JSON.parse(JSON.stringify(log)) as SessionEvent[]
     for (const [k, e] of secondTurn.entries()) {
       ;(e as { seq: number }).seq = 10 + k
       ;(e.data as { turn: number }).turn = 2
     }
-    await ctx.sessionPersistence.append(m.id, secondTurn)
+    await appendBatch(ctx.sessionPersistence, m.id, secondTurn)
 
-    const loaded = await ctx.sessionPersistence.load(m.id)
+    const loaded = await readAll(ctx.sessionPersistence, m.id)
     expect(loaded.events).toEqual([...log, ...secondTurn])
     // The packed append really packed: the file's tail carries a text-chunks row.
     const tags = (await readFile(rawLogPath(root, '/work', m.id), 'utf8')).split('\n').filter(Boolean)
@@ -1228,13 +1400,13 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
   it('scanLog: a packed row advances the seq cursor by its whole run', () => {
     const logText = [
       JSON.stringify({ type: 'session', version: 0, id: 'rows', createdAt: 1, delegationDepth: 0 }),
-      JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }),
+      JSON.stringify({ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }),
       JSON.stringify({ type: 'text-chunks', seq0: 1, time0: 2, data: { turn: 1, step: 1, index: 0, dt: [1, 1], texts: ['a', 'b', 'c'] } }),
-      JSON.stringify({ type: 'turn/end', seq: 4, time: 5, data: { turn: 1, reason: { kind: 'completed' } } }),
+      JSON.stringify({ type: 'turn/end', seq: SessionSeq(4), time: 5, data: { turn: 1, reason: { kind: 'completed' } } }),
     ].join('\n') + '\n'
     const { events } = scanLog(Buffer.from(logText))
     expect(events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4])
-    expect(events[2]).toEqual({ type: 'assistant/chunk', seq: 2, time: 3, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'b' } } })
+    expect(events[2]).toEqual({ type: 'assistant/chunk', seq: SessionSeq(2), time: 3, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'b' } } })
   })
 
   it('scanLog: a malformed packed row in the committed region rejects like corrupt JSON', () => {
@@ -1242,7 +1414,7 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
       JSON.stringify({ type: 'session', version: 0, id: 'bad-row', createdAt: 1, delegationDepth: 0 }),
       // dt arity mismatch — row validation throws, so the line is a committed hole.
       JSON.stringify({ type: 'text-chunks', seq0: 0, time0: 1, data: { turn: 1, step: 1, index: 0, dt: [], texts: ['a', 'b'] } }),
-      JSON.stringify({ type: 'turn/end', seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }),
+      JSON.stringify({ type: 'turn/end', seq: SessionSeq(2), time: 3, data: { turn: 1, reason: { kind: 'completed' } } }),
     ].join('\n') + '\n'
     expect(() => scanLog(Buffer.from(logText))).toThrow(/unparsable committed event/)
   })
@@ -1250,7 +1422,7 @@ describe('JsonlSessionPersistence: default packed chunk rows', () => {
   it('scanLog: a packed row with a mid-run seq gap after the last turn/end drops the whole row', () => {
     const logText = [
       JSON.stringify({ type: 'session', version: 0, id: 'row-gap', createdAt: 1, delegationDepth: 0 }),
-      JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }),
+      JSON.stringify({ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }),
       // seq0 skips 1 — the run's first member is already a gap; no turn/end follows.
       JSON.stringify({ type: 'text-chunks', seq0: 2, time0: 2, data: { turn: 1, step: 1, index: 0, dt: [1, 1], texts: ['a', 'b', 'c'] } }),
     ].join('\n') + '\n'
@@ -1283,57 +1455,56 @@ describe('JsonlSessionPersistence: edge cases', () => {
   beforeEach(async () => {
     root = await freshRoot()
     ctx = new Context()
-    await ctx.plugin(SessionStore)
     await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   })
   afterEach(async () => { await ctx.fiber.dispose() })
 
-  it('append rejects non-JSON-serializable undefined-producing data', async () => {
-    const m = meta('undef')
-    await ctx.sessionPersistence.create(m)
-    // A value whose JSON.stringify yields undefined (a bare function as data).
-    const bad = [{ type: 'user/message', seq: 0, time: 1, data: (() => 0) as unknown }] as unknown as SessionEvent[]
-    await expect(ctx.sessionPersistence.append(m.id, bad)).rejects.toThrow(/non-JSON-serializable/)
-  })
-
   it('create snapshots its meta: mutating the caller object after the call is ignored', async () => {
     const m = meta('create-snap', '/orig')
     const p = ctx.sessionPersistence.create(m)
     // Mutate the caller's meta object immediately after calling create.
     mutableHeader(m).cwd = '/mutated'
-    await p
-    await ctx.sessionPersistence.append(SessionId('create-snap'), oneTurnLog())
+    const handle = await p
+    await handle.append(oneTurnLog())
+    await handle.close()
     // The log materialized under the ORIGINAL cwd, not the mutated one.
     expect((await stat(rawLogPath(root, '/orig', SessionId('create-snap')))).isFile()).toBe(true)
     await expect(stat(rawLogPath(root, '/mutated', SessionId('create-snap')))).rejects.toThrow()
   })
 
-  it('list discovers sessions across multiple project directories', async () => {
-    await ctx.sessionPersistence.create(meta('p1', '/projA'))
-    await ctx.sessionPersistence.append(SessionId('p1'), oneTurnLog())
-    await ctx.sessionPersistence.create(meta('p2', '/projB'))
-    await ctx.sessionPersistence.append(SessionId('p2'), oneTurnLog())
-    await ctx.sessionPersistence.create(meta('p3')) // no cwd → _no-cwd project directory
-    await ctx.sessionPersistence.append(SessionId('p3'), oneTurnLog())
+  it('create rejects non-JSON metadata and a fractional creation timestamp without reserving the id', async () => {
+    await expect(ctx.sessionPersistence.create({ ...meta('bad-meta'), extra: 1n } as unknown as SessionHeader))
+      .rejects.toThrow('session metadata must be losslessly JSON-serializable')
+    await expect(ctx.sessionPersistence.create({ ...meta('fractional-created-at'), createdAt: 1.5 }))
+      .rejects.toThrow('session metadata createdAt must be a non-negative safe integer')
 
-    const ids = (await ctx.sessionPersistence.list()).map(x => x.id).sort()
+    // The rejected create reserved nothing: the id is free.
+    const valid = meta('fractional-created-at')
+    await writeLog(ctx.sessionPersistence, valid, oneTurnLog())
+    expect((await readAll(ctx.sessionPersistence, valid.id)).meta.createdAt).toBe(valid.createdAt)
+  })
+
+  it('list discovers sessions across multiple project directories', async () => {
+    await writeLog(ctx.sessionPersistence, meta('p1', '/projA'), oneTurnLog())
+    await writeLog(ctx.sessionPersistence, meta('p2', '/projB'), oneTurnLog())
+    await writeLog(ctx.sessionPersistence, meta('p3'), oneTurnLog()) // no cwd → _no-cwd project directory
+
+    const ids = (await ctx.sessionPersistence.list()).map(s => s.header.id).sort()
     expect(ids).toEqual(['p1', 'p2', 'p3'])
   })
 
   it('groups sessions whose cwd paths normalize to the same project directory', async () => {
     const first = meta('normalized-first', '/a/b-c')
     const second = meta('normalized-second', '/a-b/c')
-    await ctx.sessionPersistence.create(first)
-    await ctx.sessionPersistence.append(first.id, oneTurnLog())
-    await ctx.sessionPersistence.create(second)
-    await ctx.sessionPersistence.append(second.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, first, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, second, oneTurnLog())
 
     expect(projectDir(root, first.cwd)).toBe(projectDir(root, second.cwd))
     expect(await readdir(projectDir(root, first.cwd))).toEqual(expect.arrayContaining([
       encodeSegment(first.id),
       encodeSegment(second.id),
     ]))
-    expect((await ctx.sessionPersistence.list()).map(header => header.id).sort())
+    expect((await ctx.sessionPersistence.list()).map(s => s.header.id).sort())
       .toEqual([first.id, second.id].sort())
   })
 
@@ -1343,16 +1514,15 @@ describe('JsonlSessionPersistence: edge cases', () => {
 
   it('keeps the transcript in an extensible session-owned directory', async () => {
     const m = meta('owned-directory', '/project')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
     const dir = sessionDir(root, m.cwd, m.id)
     await writeFile(join(dir, 'metadata.json'), '{}\n')
     await writeFile(join(projectDir(root, m.cwd), 'README'), 'project metadata\n')
     await mkdir(join(projectDir(root, m.cwd), 'reserved-session'), { recursive: true })
 
     expect(await readdir(dir)).toEqual(expect.arrayContaining(['metadata.json', 'session.jsonl']))
-    expect((await ctx.sessionPersistence.list()).map(header => header.id)).toContain(m.id)
-    expect((await ctx.sessionPersistence.load(m.id)).events).toEqual(oneTurnLog())
+    expect((await ctx.sessionPersistence.list()).map(s => s.header.id)).toContain(m.id)
+    expect((await readAll(ctx.sessionPersistence, m.id)).events).toEqual(oneTurnLog())
   })
 
   it('rejects the obsolete flat-file layout instead of ignoring stored sessions', async () => {
@@ -1366,7 +1536,7 @@ describe('JsonlSessionPersistence: edge cases', () => {
       '',
     ].join('\n'))
 
-    await expect(ctx.sessionPersistence.load(m.id)).rejects.toThrow(/unsupported flat-file layout/)
+    await expect(ctx.sessionPersistence.open(m.id, 'read')).rejects.toThrow(/unsupported flat-file layout/)
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/unsupported flat-file layout/)
   })
 
@@ -1377,15 +1547,14 @@ describe('JsonlSessionPersistence: edge cases', () => {
     await mkdir(project, { recursive: true })
     await writeFile(join(project, `${encodeSegment(m.id)}.jsonl.zstd`), 'legacy')
 
-    await expect(ctx.sessionPersistence.load(m.id)).rejects.toThrow(/unsupported flat-file layout/)
+    await expect(ctx.sessionPersistence.open(m.id, 'read')).rejects.toThrow(/unsupported flat-file layout/)
   })
 
   it('list skips empty and non-header session logs (metadata-only read)', async () => {
     // A real session…
-    await ctx.sessionPersistence.create(meta('real', '/p'))
-    await ctx.sessionPersistence.append(SessionId('real'), oneTurnLog())
+    await writeLog(ctx.sessionPersistence, meta('real', '/p'), oneTurnLog())
     // …alongside junk session directories whose fixed transcript is empty or
-    // lacks a header. Both remain unmaterialized and are skipped.
+    // lacks a header. Both remain unlisted.
     for (const [id, content] of [
       ['empty', ''],
       ['notheader', '{"type":"turn/start"}\n'],
@@ -1396,7 +1565,7 @@ describe('JsonlSessionPersistence: edge cases', () => {
       await writeFile(path, content)
     }
 
-    const ids = (await ctx.sessionPersistence.list()).map(x => x.id).sort()
+    const ids = (await ctx.sessionPersistence.list()).map(s => s.header.id).sort()
     expect(ids).toEqual(['real'])
   })
 
@@ -1407,7 +1576,7 @@ describe('JsonlSessionPersistence: edge cases', () => {
     await mkdir(sessionDir(root, undefined, id), { recursive: true })
     const bigHeader = JSON.stringify({ type: 'session', version: 0, id: 'big', createdAt: 1, delegationDepth: 0, pad: 'x'.repeat(9000) })
     await writeFile(rawLogPath(root, undefined, id), bigHeader + '\n')
-    const ids = (await ctx.sessionPersistence.list()).map(x => x.id)
+    const ids = (await ctx.sessionPersistence.list()).map(s => s.header.id)
     expect(ids).toContain('big')
   })
 
@@ -1419,8 +1588,7 @@ describe('JsonlSessionPersistence: edge cases', () => {
 
   it('list rejects a header whose cwd does not identify its physical log', async () => {
     const m = meta('misplaced', '/stored')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
     await rewriteHeader(rawLogPath(root, m.cwd, m.id), (header) => { header.cwd = '/elsewhere' })
 
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/and cwd identify/)
@@ -1428,8 +1596,7 @@ describe('JsonlSessionPersistence: edge cases', () => {
 
   it('accepts an alternate project path only when it identifies the same physical log', async () => {
     const m = meta('physical-alias', '/stored')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, m, oneTurnLog())
     const path = rawLogPath(root, m.cwd, m.id)
     const aliasCwd = '/alias'
     await symlink(
@@ -1439,8 +1606,8 @@ describe('JsonlSessionPersistence: edge cases', () => {
     )
     await rewriteHeader(path, (header) => { header.cwd = aliasCwd })
 
-    expect((await ctx.sessionPersistence.load(m.id)).meta.cwd).toBe(aliasCwd)
-    expect((await ctx.sessionPersistence.list()).map(header => header.id)).toContain(m.id)
+    expect((await readAll(ctx.sessionPersistence, m.id)).meta.cwd).toBe(aliasCwd)
+    expect((await ctx.sessionPersistence.list()).map(s => s.header.id)).toContain(m.id)
   })
 
   it('list rejects a session header whose id cannot name a storage path', async () => {
@@ -1453,7 +1620,7 @@ describe('JsonlSessionPersistence: edge cases', () => {
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/header id cannot name a storage path/)
   })
 
-  it('load and list reject one id materialized in multiple project directories', async () => {
+  it('open and list reject one id materialized in multiple project directories', async () => {
     const id = SessionId('duplicate')
     for (const cwd of ['/a', '/b']) {
       const m = meta(id, cwd)
@@ -1462,100 +1629,26 @@ describe('JsonlSessionPersistence: edge cases', () => {
       await writeFile(rawLogPath(root, cwd, id), content)
     }
 
-    await expect(ctx.sessionPersistence.load(id)).rejects.toThrow(/appears in multiple project directories/)
+    await expect(ctx.sessionPersistence.open(id, 'read')).rejects.toThrow(/appears in multiple project directories/)
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/appears in multiple project directories/)
   })
 
-  it('a DIFFERENT live session object reusing a disposed id gets its own init (no stale cache)', async () => {
-    // Session A materializes a log under id "reuse".
-    const sessFiberA = await ctx.plugin(Object.assign((inner: Context) => {
-      const a = inner.sessions.create(SessionId('reuse'), { meta: { cwd: '/a' } })
-      appendLog(a, oneTurnLog())
-    }, { inject: ['sessions'] }))
-    // Drain A, then dispose ITS fiber (the live session A is gone) while the
-    // backend stays loaded.
-    for (const s of ctx.sessions.list()) await ctx.sessions.flush(s)
-    await sessFiberA.dispose()
-
-    // A new Session object reuses the id. Object-keyed initialization must run independently,
-    // detect the disk collision, and reject instead of appending through session A's stale cursor.
-    let b!: Session
-    await ctx.plugin(Object.assign((inner: Context) => {
-      b = inner.sessions.create(SessionId('reuse'), { meta: { cwd: '/a' } })
-    }, { inject: ['sessions'] }))
-    await expect(ctx.sessions.flush(b)).rejects.toThrow(/already bound to a different live session|already has a persisted log on disk/)
-  })
-
-  it('a no-cwd live session cannot adopt a same-id log from another cwd', async () => {
-    // Backend 1: materialize a log under id "x" in the cwd "/w" bucket, then
-    // dispose the WHOLE backend (so backend 2 mounts with an EMPTY states map —
-    // the HMR/reload path with no tracked collision state).
-    await ctx.sessionPersistence.create(meta('x', '/w'))
-    await ctx.sessionPersistence.append(SessionId('x'), oneTurnLog())
-    await ctx.fiber.dispose()
-
-    // Backend 2 creates a no-cwd session whose id exists only in `/w`. The
-    // stored cwd check rejects instead of grafting no-cwd events onto that log.
+  it('create rejects an id already on disk under a different project directory', async () => {
+    // Persist the id under cwd A.
+    const a = meta('dup-id', '/projA')
+    await writeLog(ctx.sessionPersistence, a, oneTurnLog())
+    // A fresh backend creating the SAME id under cwd B must still refuse:
+    // opens identify by id across all projects, so a second log would make
+    // resume nondeterministic. create scans every project, not just meta.cwd's.
     const ctx2 = new Context()
-    await ctx2.plugin(SessionStore)
     await ctx2.plugin(JsonlSessionPersistence, { root, compression: 'none' })
-    let b!: Session
-    await ctx2.plugin(Object.assign((inner: Context) => {
-      b = inner.sessions.create(SessionId('x')) // no cwd
-    }, { inject: ['sessions'] }))
-    await expect(ctx2.sessions.flush(b)).rejects.toThrow(/different cwd|id collision/)
-
-    // The "/w" log is untouched — no no-cwd events were grafted onto it, and no
-    // `_no-cwd` log for "x" was created.
-    const inW = scanLog(await readFile(rawLogPath(root, '/w', SessionId('x'))))
-    expect(inW.meta.cwd).toBe('/w')
-    expect(inW.events).toHaveLength(6)
-    await expect(stat(rawLogPath(root, undefined, SessionId('x')))).rejects.toThrow()
+    await expect(ctx2.sessionPersistence.create(meta('dup-id', '/projB')))
+      .rejects.toThrow(/already exists/)
     await ctx2.fiber.dispose()
   })
 
-  it('a seed with matching seq/type/time but DIFFERENT data is rejected (deep prefix compare)', async () => {
-    // Materialize and load (ownerless, cursor = 6).
-    await ctx.sessionPersistence.create(meta('divergent', '/a'))
-    await ctx.sessionPersistence.append(SessionId('divergent'), oneTurnLog())
-    await ctx.sessionPersistence.load(SessionId('divergent'))
-
-    // A seed that keeps every seq/type/time but mutates a payload must NOT be
-    // accepted as "the same session" — otherwise drain filters those seqs as
-    // already persisted and the divergent payload is silently lost.
-    const tampered = structuredClone(oneTurnLog())
-    const userMsg = tampered[1]
-    if (userMsg?.type === 'user/message') {
-      (userMsg.data as { content: unknown[] }).content = [{ type: 'text', text: 'DIFFERENT' }]
-    }
-    let bad!: Session
-    await ctx.plugin(Object.assign((inner: Context) => {
-      bad = inner.sessions.create(SessionId('divergent'), { seed: tampered, meta: { cwd: '/a' } })
-    }, { inject: ['sessions'] }))
-    await expect(ctx.sessions.flush(bad)).rejects.toThrow(/do not match this live session|already has a persisted log/)
-  })
-
-  it('a second live session reusing a bound id is rejected', async () => {
-    // A live session materializes and owns the id.
-    const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      const a = inner.sessions.create(SessionId('bound'), { meta: { cwd: '/a' } })
-      a.append('turn/start', { turn: 1 })
-      a.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    }, { inject: ['sessions'] }))
-    for (const s of ctx.sessions.list()) await ctx.sessions.flush(s)
-    await firstFiber.dispose()
-
-    let second!: Session
-    await ctx.plugin(Object.assign((inner: Context) => {
-      second = inner.sessions.create(SessionId('bound'), { meta: { cwd: '/a' } })
-    }, { inject: ['sessions'] }))
-    await expect(ctx.sessions.flush(second))
-      .rejects.toThrow(/already bound to a different live session|already has a persisted log|do not match/)
-  })
-
   it('list returns nothing when the root directory does not exist', async () => {
     const ctx2 = new Context()
-    await ctx2.plugin(SessionStore)
     await ctx2.plugin(JsonlSessionPersistence, {
       root: join(root, 'does-not-exist-yet'),
       compression: 'none',
@@ -1568,7 +1661,6 @@ describe('JsonlSessionPersistence: edge cases', () => {
     const filePath = join(root, 'not-a-dir')
     await writeFile(filePath, 'x')
     const ctx2 = new Context()
-    await ctx2.plugin(SessionStore)
     await expect(ctx2.plugin(JsonlSessionPersistence, { root: filePath, compression: 'none' })).rejects.toThrow(/ENOTDIR/)
     await ctx2.fiber.dispose()
   })
@@ -1590,147 +1682,38 @@ describe('JsonlSessionPersistence: edge cases', () => {
 
   it('materialization surfaces a project-directory storage fault', async () => {
     const cwd = '/x'
-    const ctx2 = new Context()
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(JsonlSessionPersistence, { root, compression: 'none' })
     await writeFile(projectDir(root, cwd), 'x') // project path is now a file
-    let s!: Session
-    await ctx2.plugin(Object.assign((inner: Context) => {
-      s = inner.sessions.create(SessionId('exists-fault'), { meta: { cwd } })
-      appendClosedTurn(s)
-    }, { inject: ['sessions'] }))
-    await expectFlushCode(ctx2.sessions.flush(s), ['EEXIST', 'ENOTDIR'])
-    await ctx2.fiber.dispose()
+    const handle = await ctx.sessionPersistence.create(meta('exists-fault', cwd))
+    try {
+      await expectCode(handle.append(oneTurnLog()), ['EEXIST', 'ENOTDIR'])
+    } finally {
+      await handle.close()
+    }
   })
 
-  it('append() to a disk-only session adopts it and repairs a crash tail', async () => {
-    // Persist a session, then corrupt its tail, all through ONE backend.
-    const m = meta('disk-append', '/d')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    await writeFile(rawLogPath(root, '/d', m.id), '\n{"partial crash', { flag: 'a' })
-
-    // A FRESH backend with no in-memory state: append directly (no prior load)
-    // → append must adopt from disk, and the adopt's load schedules a repair
-    // that the same append then performs before writing.
-    const ctx2 = new Context()
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(JsonlSessionPersistence, { root, compression: 'none' })
-    await ctx2.sessionPersistence.append(m.id, [
-      { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } },
-      { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
-    ] as SessionEvent[])
-    const loaded = await ctx2.sessionPersistence.load(m.id)
-    expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
-    await ctx2.fiber.dispose()
-  })
-
-  it('a header-only log (open turn, no turn/end) preserves the open turn on load and closes it', async () => {
-    // A session whose only durable content is an unclosed first turn. scanLog
-    // preserves the turn/start; loadCore closes it with a synthetic
-    // turn/end {interrupted} so the returned log is balanced.
-    const m = meta('open-turn', '/h')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-    ] as SessionEvent[])
-    const { events } = await ctx.sessionPersistence.load(m.id)
-    expect(events.map(e => e.type)).toEqual(['turn/start', 'turn/end'])
-    const end = events[1]!
-    expect(end.type === 'turn/end' && end.data.reason).toEqual({ kind: 'interrupted' })
-  })
-
-
-  it('createCore rejects an id already on disk under a different project directory', async () => {
-    // Persist the id under cwd A.
-    const a = meta('dup-id', '/projA')
-    await ctx.sessionPersistence.create(a)
-    await ctx.sessionPersistence.append(a.id, oneTurnLog())
-    // A fresh backend creating the SAME id under cwd B must still refuse: load
-    // identifies by id across all projects, so a second log would make resume
-    // nondeterministic. create scans every project, not just meta.cwd's.
-    const ctx2 = new Context()
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(JsonlSessionPersistence, { root, compression: 'none' })
-    await expect(ctx2.sessionPersistence.create(meta('dup-id', '/projB')))
-      .rejects.toThrow(/already has a persisted log on disk/)
-    await ctx2.fiber.dispose()
-  })
-
-  it('flush keeps buffered events when the append fails (no silent loss)', async () => {
-    root = await freshRoot()
-    const ctx2 = new Context()
-    await ctx2.plugin(SessionStore)
-    await ctx2.plugin(JsonlSessionPersistence, { root, compression: 'none' })
-    const session = ctx2.sessions.create(SessionId('flush-fail'))
-    // A full turn lands in the write-behind buffer.
-    session.append('turn/start', { turn: 1 })
-    session.append('user/message', createUserMessage({
-      content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
-    }), { surfaceOp: 'append' })
-    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    // Make the durable materialize fail on the next flush.
-    const backend = ctx2.sessionPersistence as unknown as { materialize: (...args: unknown[]) => Promise<void> }
-    const origMat = backend.materialize.bind(backend)
-    backend.materialize = () => Promise.reject(new Error('disk full'))
-    await expectFlushError(ctx2.sessions.flush(session), /disk full/)
-    // The events are STILL buffered (not silently dropped): a retry persists them.
-    backend.materialize = origMat
-    await ctx2.sessions.flush(session)
-    const loaded = await ctx2.sessionPersistence.load(SessionId('flush-fail'))
-    expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2])
-    await ctx2.fiber.dispose()
-  })
-
-  it('rejects non-JSON event data: BigInt, function, circular, Map, undefined property', async () => {
-    const m = meta('serial')
-    await ctx.sessionPersistence.create(m)
-    const bad = (extra: unknown) => [{
-      type: 'user/message',
-      seq: 0,
-      time: 1,
-      data: {
-        id: MessageId('invalid-json'),
-        role: 'user',
-        content: [{ type: 'text', text: 'x' }],
-        source: { kind: 'user' },
-        extra,
-      },
-    }] as unknown as SessionEvent[]
-    await expect(ctx.sessionPersistence.append(m.id, bad(1n))).rejects.toThrow(/non-JSON-serializable/)
-    await expect(ctx.sessionPersistence.append(m.id, bad(() => 0))).rejects.toThrow(/non-JSON-serializable/)
-    await expect(ctx.sessionPersistence.append(m.id, bad(Symbol('s')))).rejects.toThrow(/non-JSON-serializable/)
-    await expect(ctx.sessionPersistence.append(m.id, bad(new Map()))).rejects.toThrow(/non-JSON-serializable/)
-    await expect(ctx.sessionPersistence.append(m.id, bad(undefined))).rejects.toThrow(/non-JSON-serializable/)
-    await expect(ctx.sessionPersistence.append(m.id, bad(Infinity))).rejects.toThrow(/non-JSON-serializable/)
-    // a circular structure
-    const circ: Record<string, unknown> = {}
-    circ.self = circ
-    await expect(ctx.sessionPersistence.append(m.id, bad(circ))).rejects.toThrow(/non-JSON-serializable/)
-    // The session was never materialized by any of the rejected appends.
-    expect((await ctx.sessionPersistence.list()).map(h => h.id)).not.toContain(m.id)
+  it('backend teardown closes handles left open and fails later operations loudly', async () => {
+    const m = meta('teardown')
+    const handle = await ctx.sessionPersistence.create(m)
+    await handle.append(oneTurnLog())
+    await ctx.fiber.dispose()
+    await expect(handle.append([
+      { type: 'turn/start', seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+    ])).rejects.toThrow(/on a closed handle/)
+    // Reload the backend so the shared afterEach dispose stays valid.
+    ctx = new Context()
+    await ctx.plugin(JsonlSessionPersistence, { root, compression: 'none' })
   })
 
   it('accepts well-formed JSON values (null, booleans, nested arrays/objects)', async () => {
     const m = meta('json-ok')
-    await ctx.sessionPersistence.create(m)
-    const ev = [{ type: 'user/message', seq: 0, time: 1, data: createUserMessage({
-      content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra: { a: null, b: true, c: [1, 2, { d: 'nested' }] },
-    }) }] as unknown as SessionEvent[]
-    await ctx.sessionPersistence.append(m.id, ev)
-    expect((await ctx.sessionPersistence.list()).map(h => h.id)).toContain(m.id)
+    const events = [{ type: 'user/message', seq: SessionSeq(0), time: 1, data: {
+      id: MessageId('json-ok'),
+      role: 'user',
+      content: [{ type: 'text', text: 'x' }],
+      source: { kind: 'user' },
+      extra: { a: null, b: true, c: [1, 2, { d: 'nested' }] },
+    }, surfaceOp: 'append' }] as unknown as SessionEvent[]
+    await writeLog(ctx.sessionPersistence, m, events)
+    expect((await readAll(ctx.sessionPersistence, m.id)).events).toEqual(events)
   })
-
-  it('Session.append rejects a non-serializable event at the source (never enters the log)', () => {
-    const session = ctx.sessions.create(SessionId('reject-bad'))
-    // Serializability is enforced at the source: Session.append throws on a BigInt-bearing
-    // event before it enters session.snapshotEvents(), so the durable log can never diverge from the live
-    // log. The error therefore surfaces synchronously at append, not later during backend flush.
-    expect(() => {
-      session.append('user/message', { content: [{ type: 'text', text: 'bad' }], source: { kind: 'user' }, bad: 1n } as never, { surfaceOp: 'append' })
-    }).toThrow(/non-JSON-serializable/)
-    // The bad event was rejected, so the log stayed empty.
-    expect(session.snapshotEvents().length).toBe(0)
-  })
-
 })
diff --git a/packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts
index a8da30bd28..cb13896983 100644
--- a/packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import {
-  compressZstdFrame, createZstdFrameDecoder, decompressZstdFrame, decompressZstdPrefix, scanZstdFrames,
+  compressZstdFrame, createZstdFrameDecoder, decompressZstdFrame, scanZstdFrames,
 } from '../src/zstd.ts'
 import { NodePrivateZstdFrameDecoder } from '../src/zstd-private-decoder.ts'
 import { PublicZstdFrameDecoder } from '../src/zstd-public-decoder.ts'
@@ -34,6 +34,5 @@ describe('JSONL Zstandard compatibility', () => {
     const eventFrame = encoded.subarray(frames[1]!.start, frames[1]!.end)
     const missingChecksumByte = eventFrame.subarray(0, -1)
     expect(scanZstdFrames(missingChecksumByte)).toEqual({ frames: [], tornStart: 0 })
-    expect((await decompressZstdPrefix(missingChecksumByte)).toString()).toContain('"type":"turn/start"')
   })
 })
diff --git a/packages/session/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
index 9d311d2b39..828529cd26 100644
--- a/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
@@ -5,8 +5,9 @@ import type { FileHandle } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { performance } from 'node:perf_hooks'
-import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionSeq, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { logPath, scanLog, sessionDir, toHeaderLine, type JsonlCompression } from '../src/format.ts'
 import {
@@ -16,7 +17,6 @@ import {
 import { NodePrivateZstdFrameDecoder } from '../src/zstd-private-decoder.ts'
 import { PublicZstdFrameDecoder } from '../src/zstd-public-decoder.ts'
 import { runPersistenceContract, meta, oneTurnLog } from '../../session-persistence/tests/contract.ts'
-import { runCoordinatorContract, type CoordinatorFixture } from '../../session-persistence/tests/coordinator-contract.ts'
 
 const MAGIC = Buffer.from([0x28, 0xB5, 0x2F, 0xFD])
 const roots: string[] = []
@@ -43,7 +43,6 @@ async function freshRoot(prefix = 'dsh-jsonl-zstd-'): Promise<string> {
 async function mount(root: string, compression?: JsonlCompression): Promise<Context> {
   const ctx = new Context()
   contexts.push(ctx)
-  await ctx.plugin(SessionStore)
   await ctx.plugin(JsonlSessionPersistence, {
     root,
     ...(compression === undefined ? {} : { compression }),
@@ -51,6 +50,36 @@ async function mount(root: string, compression?: JsonlCompression): Promise<Cont
   return ctx
 }
 
+/** Create + append + close: persist one whole log through the write handle. */
+async function writeLog(persistence: SessionPersistence, m: SessionHeader, events: readonly SessionEvent[]): Promise<void> {
+  const handle = await persistence.create(m)
+  try {
+    await handle.append(events)
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Open a read handle, read the whole log, and close. */
+async function readAll(persistence: SessionPersistence, id: SessionId): Promise<{ meta: SessionHeader; events: readonly SessionEvent[] }> {
+  const handle = await persistence.open(id, 'read')
+  try {
+    return { meta: handle.header, events: await handle.read() }
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Append one contiguous batch through a temporary write handle. */
+async function appendBatch(persistence: SessionPersistence, id: SessionId, events: readonly SessionEvent[]): Promise<void> {
+  const handle = await persistence.open(id, 'write')
+  try {
+    await handle.append(events)
+  } finally {
+    await handle.close()
+  }
+}
+
 async function decodeCompleteFrames(buffer: Buffer): Promise<Buffer> {
   const { frames, tornStart } = scanZstdFrames(buffer)
   expect(tornStart).toBeUndefined()
@@ -61,10 +90,8 @@ async function decodeCompleteFrames(buffer: Buffer): Promise<Buffer> {
   return Buffer.concat(plaintext)
 }
 
-async function tornFrame(
-  plaintext: string,
-  accepts: (decoded: string) => boolean,
-): Promise<Buffer> {
+/** Truncate one compressed frame so a scan reports it torn and the recovered plaintext satisfies `accepts`. */
+async function tornFrame(plaintext: string, accepts: (decoded: string) => boolean = () => true): Promise<Buffer> {
   const frame = await compressZstdFrame(plaintext)
   const candidateEnds = [
     frame.length - 1,
@@ -114,33 +141,34 @@ afterEach(async () => {
 
 runPersistenceContract('jsonl-zstd', async () => {
   const root = await mkdtemp(join(tmpdir(), 'dsh-jsonl-zstd-contract-'))
-  const ctx = new Context()
-  await ctx.plugin(SessionStore)
-  const fiber = await ctx.plugin(JsonlSessionPersistence, { root })
+  const instance = async (): Promise<{ persistence: SessionPersistence; dispose: () => Promise<void> }> => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(JsonlSessionPersistence, { root })
+    return {
+      persistence: ctx.sessionPersistence,
+      dispose: async () => { await fiber.dispose() },
+    }
+  }
+  const primary = await instance()
   return {
-    persistence: ctx.sessionPersistence,
+    persistence: primary.persistence,
     dispose: async () => {
-      await fiber.dispose()
+      await primary.dispose()
       await rm(root, { recursive: true, force: true })
     },
-  }
-})
-
-runCoordinatorContract('jsonl-zstd', async (): Promise<CoordinatorFixture> => {
-  const root = await mkdtemp(join(tmpdir(), 'dsh-jsonl-zstd-coordinator-'))
-  return {
-    mount: async ctx => ctx.plugin(JsonlSessionPersistence, { root }),
+    reopen: instance,
+    // A torn final frame: the batch's append never resolved, so the whole
+    // frame is an uncommitted crash fragment for the write path to truncate.
     corruptTail: async (id, cwd) => {
       const line = JSON.stringify({
         type: 'assistant/chunk',
-        seq: 8,
+        seq: SessionSeq(8),
         time: 9,
         data: { turn: 2, step: 1, chunk: { type: 'text-delta', index: 0, text: deterministicNoise(300_000) } },
       }) + '\n'
-      const partial = await tornFrame(line, decoded => decoded.length > 0 && !decoded.endsWith('\n'))
+      const partial = await tornFrame(line, decoded => !decoded.includes('\n'))
       await appendFile(logPath(root, cwd, id, 'zstd'), partial)
     },
-    cleanup: async () => { await rm(root, { recursive: true, force: true }) },
   }
 })
 
@@ -332,51 +360,30 @@ describe('Zstandard frame structure', () => {
 })
 
 describe('JsonlSessionPersistence: default Zstandard encoding', () => {
-  it('lists seeded metadata from the header frame without decoding the event body', async () => {
-    const root = await freshRoot()
-    const ctx = await mount(root)
-    const header = { ...meta('zstd-header-only-seeded', '/work'), isSeeded: true }
-    const path = logPath(root, '/work', header.id, 'zstd')
-    await mkdir(sessionDir(root, '/work', header.id), { recursive: true })
-    const headerFrame = await compressZstdFrame(
-      `${JSON.stringify(toHeaderLine(header, SessionLogOffset(0)))}\n`,
-    )
-    await writeFile(path, Buffer.concat([headerFrame, Buffer.from('invalid event frame')]))
-
-    await expect(ctx.sessionPersistence.list()).resolves.toEqual([
-      expect.objectContaining({ id: header.id, isSeeded: true }),
-    ])
-  })
-
   it('materializes an explicitly durable empty session as one header frame', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
-    const session = ctx.sessions.create(SessionId('empty-zstd'), { meta: { cwd: '/work' } })
+    const m = meta('empty-zstd', '/work')
+    const handle = await ctx.sessionPersistence.create(m)
+    await handle.flush()
+    await handle.close()
 
-    await ctx.sessionPersistence.ensureMaterialized(session)
-
-    const buffer = await readFile(logPath(root, '/work', session.id, 'zstd'))
+    const buffer = await readFile(logPath(root, '/work', m.id, 'zstd'))
     expect(scanZstdFrames(buffer).frames).toHaveLength(1)
-    expect((await decodeCompleteFrames(buffer)).toString()).toBe(`${JSON.stringify(toHeaderLine(session.header))}\n`)
-    await expect(ctx.sessionPersistence.load(session.id)).resolves.toEqual({
-      meta: session.header,
-      inheritedEventCount: 0,
-      events: [],
-    })
+    expect((await decodeCompleteFrames(buffer)).toString()).toBe(`${JSON.stringify(toHeaderLine(m))}\n`)
+    await expect(readAll(ctx.sessionPersistence, m.id)).resolves.toMatchObject({ events: [] })
   })
 
   it('writes .jsonl.zstd by default with one header frame and one first-batch frame', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('default-zstd', '/work')
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, header, oneTurnLog())
 
     const path = logPath(root, header.cwd, header.id, 'zstd')
     const buffer = await readFile(path)
     expect(buffer.subarray(0, 4)).toEqual(MAGIC)
     await expect(stat(logPath(root, header.cwd, header.id, 'none'))).rejects.toThrow()
-    expect(ctx.sessionPersistence.locate(header)).toEqual({ kind: 'jsonl', path })
 
     const scan = scanZstdFrames(buffer)
     expect(scan.frames).toHaveLength(2)
@@ -386,57 +393,30 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       ...oneTurnLog().map(e => JSON.stringify(e)),
       '',
     ].join('\n'))
-    expect((await ctx.sessionPersistence.load(header.id)).events).toEqual(oneTurnLog())
+    expect((await readAll(ctx.sessionPersistence, header.id)).events).toEqual(oneTurnLog())
   })
 
-  it('readRaw decodes the compressed artifact back to the original JSONL text', async () => {
-    const root = await freshRoot()
-    const ctx = await mount(root)
-    const header = meta('raw-read-zstd', '/work')
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
 
-    const raw = await ctx.sessionPersistence.readRaw(header.id)
-    expect(raw).toBeDefined()
-    // The logical name drops the physical encoding suffix.
-    expect(raw!.filename).toBe('session.jsonl')
-    expect(raw!.meta.id).toBe(header.id)
-    expect(raw!.content).toBe([
-      JSON.stringify(toHeaderLine(header)),
-      ...oneTurnLog().map(e => JSON.stringify(e)),
-      '',
-    ].join('\n'))
-    const scanned = scanLog(Buffer.from(raw!.content))
-    expect(scanned.events.map(event => event.type)).toEqual(oneTurnLog().map(event => event.type))
-  })
-
-  it('readRaw rejects a present zstd artifact that carries no frame', async () => {
+  it('a read rejects a present zstd artifact that carries no frame', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('raw-zero-frame', '/work')
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, header, oneTurnLog())
     // The path still exists, so zero frames is corruption rather than absence.
     await writeFile(logPath(root, '/work', header.id, 'zstd'), Buffer.alloc(0))
-    await expect(ctx.sessionPersistence.readRaw(header.id))
-      .rejects.toThrow('empty or header-less Zstandard session log')
+    await expect(readAll(ctx.sessionPersistence, header.id)).rejects.toThrow()
   })
 
   it('resolves the default when a programmatic wrapper bypasses Loader schema normalization', async () => {
     const root = await freshRoot()
     const ctx = new Context()
     contexts.push(ctx)
-    await ctx.plugin(SessionStore)
     let backend!: JsonlSessionPersistence
-    await ctx.plugin(Object.assign((inner: Context) => {
+    await ctx.plugin((inner: Context) => {
       backend = new JsonlSessionPersistence(inner, { root })
-    }, { inject: ['sessions'] }))
+    })
     const header = meta('direct-default')
     const path = logPath(root, header.cwd, header.id, 'zstd')
-    expect(backend.locate(header)).toEqual({
-      kind: 'jsonl',
-      path,
-    })
 
     const base = oneTurnLog()
     const events: SessionEvent[] = [
@@ -453,50 +433,49 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
         time: event.time + 3,
       })),
     ]
-    await backend.create(header)
-    await backend.append(header.id, events)
+    await writeLog(backend, header, events)
 
     const plaintext = (await decodeCompleteFrames(await readFile(path))).toString()
     const recordTypes = plaintext.trimEnd().split('\n')
       .map(line => (JSON.parse(line) as { type: string }).type)
     expect(recordTypes).toContain('text-chunks')
-    expect((await backend.load(header.id)).events).toEqual(events)
+    expect((await readAll(backend, header.id)).events).toEqual(events)
   })
 
   it('appends one frame per durable batch without rewriting prior bytes', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('append-frame')
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    const handle = await ctx.sessionPersistence.create(header)
+    await handle.append(oneTurnLog())
     const path = logPath(root, header.cwd, header.id, 'zstd')
     const before = await readFile(path)
-    const secondTurn = [
-      { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-      { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-    ] as SessionEvent[]
-    await ctx.sessionPersistence.append(header.id, secondTurn)
+    const secondTurn: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+      { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+    ]
+    await handle.append(secondTurn)
+    await handle.close()
 
     const after = await readFile(path)
     expect(after.subarray(0, before.length)).toEqual(before)
     expect(scanZstdFrames(after).frames).toHaveLength(3)
-    expect((await ctx.sessionPersistence.load(header.id)).events).toEqual([...oneTurnLog(), ...secondTurn])
+    expect((await readAll(ctx.sessionPersistence, header.id)).events).toEqual([...oneTurnLog(), ...secondTurn])
   })
 
   it('lists from a multi-chunk header frame without decoding a corrupt event frame', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('large-header', `/work/${'x'.repeat(24_000)}`)
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, header, oneTurnLog())
     const path = logPath(root, header.cwd, header.id, 'zstd')
     const buffer = Buffer.from(await readFile(path))
     const eventFrame = scanZstdFrames(buffer).frames[1]!
     buffer[eventFrame.end - 1] = buffer[eventFrame.end - 1]! ^ 0xFF
     await writeFile(path, buffer)
 
-    expect((await ctx.sessionPersistence.list()).map(item => item.id)).toEqual([header.id])
-    await expect(ctx.sessionPersistence.load(header.id)).rejects.toThrow(/frame at byte .* failed validation/)
+    expect((await ctx.sessionPersistence.list()).map(item => item.header.id)).toEqual([header.id])
+    await expect(readAll(ctx.sessionPersistence, header.id)).rejects.toThrow(/frame at byte .* failed validation/)
   })
 
   it('stops multi-frame inspection when cancellation arrives at a slice deadline', async () => {
@@ -541,8 +520,7 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       const root = await freshRoot()
       const ctx = await mount(root, compression)
       const header = meta(`cancel-${compression}-header-read`, '/work')
-      await ctx.sessionPersistence.create(header)
-      await ctx.sessionPersistence.append(header.id, oneTurnLog())
+      await writeLog(ctx.sessionPersistence, header, oneTurnLog())
       await ctx.sessionPersistence.list()
       const path = logPath(root, header.cwd, header.id, compression)
       const probe = await open(path, 'r')
@@ -563,107 +541,162 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
         return result
       })
 
-      await expect(ctx.sessionPersistence.list(controller.signal)).rejects.toBe(reason)
+      await expect(ctx.sessionPersistence.list({ signal: controller.signal })).rejects.toBe(reason)
       expect(read).toHaveBeenCalledTimes(1)
     },
   )
 
-  it('preserves complete records from a torn frame and re-encodes them with crash closers', async () => {
+  it('recovers complete records from a torn final frame and rewrites them on the next append', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('recover-torn', '/proj')
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, header, oneTurnLog())
     const path = logPath(root, header.cwd, header.id, 'zstd')
     const committed = await readFile(path)
-    const openTurn = [
-      { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-      { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } },
-      { type: 'assistant/chunk', seq: 8, time: 9, data: { turn: 2, step: 1, chunk: { type: 'text-delta', index: 0, text: deterministicNoise(300_000) } } },
-    ] as SessionEvent[]
+    const openTurn: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+      { type: 'step/start', seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
+      { type: 'assistant/chunk', seq: SessionSeq(8), time: 9, data: { turn: 2, step: 1, chunk: { type: 'text-delta', index: 0, text: deterministicNoise(300_000) } } },
+    ]
     const plaintext = openTurn.map(e => JSON.stringify(e)).join('\n') + '\n'
-    const partial = await tornFrame(plaintext, (decoded) => {
+    await appendFile(path, await tornFrame(plaintext, (decoded) => {
       const newlines = decoded.match(/\n/g)?.length ?? 0
       return newlines >= 2 && !decoded.endsWith('\n')
-    })
-    await appendFile(path, partial)
+    }))
 
-    const loaded = await ctx.sessionPersistence.load(header.id)
-    expect(loaded.events.map(event => event.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+    // Complete JSONL records already flushed into the torn frame are real
+    // emitted events: reads recover them, while the half-written chunk stays
+    // invisible and the file keeps its bytes until the write path repairs it.
+    const loaded = await readAll(ctx.sessionPersistence, header.id)
+    expect(loaded.events.map(event => event.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
     expect(loaded.events[6]).toEqual(openTurn[0])
     expect(loaded.events[7]).toEqual(openTurn[1])
-    expect(loaded.events.some(event => event.type === 'assistant/chunk' && event.seq === 8)).toBe(false)
-    expect(loaded.events[8]?.type).toBe('step/end')
-    expect(loaded.events[9]?.type).toBe('turn/end')
+
+    // The first append truncates the torn bytes and rewrites the recovered
+    // records durably before the new batch, continuing at their next-seq.
+    const closers: SessionEvent[] = [
+      { type: 'step/end', seq: SessionSeq(8), time: 10, data: { turn: 2, step: 1 } },
+      { type: 'turn/end', seq: SessionSeq(9), time: 11, data: { turn: 2, reason: { kind: 'interrupted' } } },
+    ]
+    await appendBatch(ctx.sessionPersistence, header.id, closers)
     expect(warn).toHaveBeenCalledWith('session-persistence-jsonl: session "recover-torn" recovered from a torn tail; incomplete tail bytes were discarded')
 
     const repaired = await readFile(path)
     expect(repaired.subarray(0, committed.length)).toEqual(committed)
     expect(scanZstdFrames(repaired).tornStart).toBeUndefined()
-    expect(scanLog(await decodeCompleteFrames(repaired)).events).toEqual(loaded.events)
+    expect(scanLog(await decodeCompleteFrames(repaired)).events)
+      .toEqual([...oneTurnLog(), openTurn[0]!, openTurn[1]!, ...closers])
+  })
+
+  it('retries the torn-tail rewrite when its first durable write fails', async () => {
+    const root = await freshRoot()
+    const ctx = await mount(root)
+    const header = meta('retry-torn-rewrite', '/proj')
+    vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    await writeLog(ctx.sessionPersistence, header, oneTurnLog())
+    const path = logPath(root, header.cwd, header.id, 'zstd')
+    const recovered: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+      { type: 'step/start', seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
+      { type: 'assistant/chunk', seq: SessionSeq(8), time: 9, data: { turn: 2, step: 1, chunk: { type: 'text-delta', index: 0, text: deterministicNoise(300_000) } } },
+    ]
+    await appendFile(path, await tornFrame(recovered.map(e => JSON.stringify(e)).join('\n') + '\n', (decoded) => {
+      const newlines = decoded.match(/\n/g)?.length ?? 0
+      return newlines >= 2 && !decoded.endsWith('\n')
+    }))
+
+    const handle = await ctx.sessionPersistence.open(header.id, 'write')
+    try {
+      const failure = new Error('rewrite refused')
+      const service = ctx.sessionPersistence as unknown as { persistBatch: () => Promise<void> }
+      vi.spyOn(service, 'persistBatch').mockRejectedValueOnce(failure)
+      const closers: SessionEvent[] = [
+        { type: 'step/end', seq: SessionSeq(8), time: 10, data: { turn: 2, step: 1 } },
+        { type: 'turn/end', seq: SessionSeq(9), time: 11, data: { turn: 2, reason: { kind: 'interrupted' } } },
+      ]
+      // The rewrite of the recovered records fails first; the retained repair
+      // state makes the retried append rewrite them exactly once.
+      await expect(handle.append(closers)).rejects.toBe(failure)
+      await handle.append(closers)
+    } finally {
+      await handle.close()
+    }
+
+    const repaired = await readFile(path)
+    expect(scanZstdFrames(repaired).tornStart).toBeUndefined()
+    expect(scanLog(await decodeCompleteFrames(repaired)).events.map(e => e.seq))
+      .toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
   })
 
   it('drops a frame torn in its header before it has produced plaintext', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('partial-magic')
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, header, oneTurnLog())
     const path = logPath(root, header.cwd, header.id, 'zstd')
     const committed = await readFile(path)
     await appendFile(path, MAGIC.subarray(0, 2))
 
-    expect((await ctx.sessionPersistence.load(header.id)).events).toEqual(oneTurnLog())
-    expect(await readFile(path)).toEqual(committed)
+    expect((await readAll(ctx.sessionPersistence, header.id)).events).toEqual(oneTurnLog())
+    // Reads never repair: the torn bytes stay until a write-path append.
+    expect(await readFile(path)).toEqual(Buffer.concat([committed, MAGIC.subarray(0, 2)]))
   })
 
-  it('recovers complete events when EOF tears only the final frame checksum', async () => {
+  it('recovers a final frame torn at its checksum byte in full', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('partial-checksum')
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, header, oneTurnLog())
     const path = logPath(root, header.cwd, header.id, 'zstd')
-    const secondTurn = [
-      { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-      { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-    ] as SessionEvent[]
+    const committed = await readFile(path)
+    const secondTurn: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+      { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+    ]
     const frame = await compressZstdFrame(secondTurn.map(e => JSON.stringify(e)).join('\n') + '\n')
     await appendFile(path, frame.subarray(0, -1))
 
-    const loaded = await ctx.sessionPersistence.load(header.id)
+    // One missing checksum byte leaves the frame structurally torn, but its
+    // complete records decode in full: reads recover them, and the next
+    // append rewrites them as a complete checksummed frame.
+    const loaded = await readAll(ctx.sessionPersistence, header.id)
     expect(loaded.events).toEqual([...oneTurnLog(), ...secondTurn])
+    const thirdTurn: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(8), time: 9, data: { turn: 3 } },
+      { type: 'turn/end', seq: SessionSeq(9), time: 10, data: { turn: 3, reason: { kind: 'completed' } } },
+    ]
+    await appendBatch(ctx.sessionPersistence, header.id, thirdTurn)
     const repaired = await readFile(path)
+    expect(repaired.subarray(0, committed.length)).toEqual(committed)
     expect(scanZstdFrames(repaired).tornStart).toBeUndefined()
-    expect(scanLog(await decodeCompleteFrames(repaired)).events).toEqual(loaded.events)
+    expect(scanLog(await decodeCompleteFrames(repaired)).events).toEqual([...oneTurnLog(), ...secondTurn, ...thirdTurn])
   })
 
   it('rejects a complete frame containing a torn JSONL record', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('complete-bad-jsonl')
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    await writeLog(ctx.sessionPersistence, header, oneTurnLog())
     await appendFile(
       logPath(root, header.cwd, header.id, 'zstd'),
       await compressZstdFrame('{"type":"turn/start"'),
     )
-    await expect(ctx.sessionPersistence.load(header.id)).rejects.toThrow(/complete frame contains a torn JSONL record/)
+    await expect(readAll(ctx.sessionPersistence, header.id)).rejects.toThrow(/complete frame contains a torn JSONL record/)
   })
 
   it('rolls back a checksummed append frame when fsync fails', async () => {
     const root = await freshRoot()
     const ctx = await mount(root)
     const header = meta('zstd-fsync-rollback')
-    await ctx.sessionPersistence.create(header)
-    await ctx.sessionPersistence.append(header.id, oneTurnLog())
+    const handle = await ctx.sessionPersistence.create(header)
+    await handle.append(oneTurnLog())
     const path = logPath(root, header.cwd, header.id, 'zstd')
     const before = await readFile(path)
 
-    const handle = await open(path, 'r')
-    const prototype = Object.getPrototypeOf(handle) as { sync: () => Promise<void> }
-    await handle.close()
+    const probe = await open(path, 'r')
+    const prototype = Object.getPrototypeOf(probe) as { sync: () => Promise<void> }
+    await probe.close()
     const realSync = prototype.sync
     let failed = false
     const spy = vi.spyOn(prototype, 'sync').mockImplementation(async function (this: FileHandle) {
@@ -673,15 +706,16 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       }
       return realSync.call(this)
     })
-    const secondTurn = [
-      { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } },
-      { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-    ] as SessionEvent[]
-    await expect(ctx.sessionPersistence.append(header.id, secondTurn)).rejects.toThrow(/simulated Zstandard fsync failure/)
+    const secondTurn: SessionEvent[] = [
+      { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
+      { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+    ]
+    await expect(handle.append(secondTurn)).rejects.toThrow(/simulated Zstandard fsync failure/)
     expect(await readFile(path)).toEqual(before)
     spy.mockRestore()
-    await ctx.sessionPersistence.append(header.id, secondTurn)
-    expect((await ctx.sessionPersistence.load(header.id)).events).toEqual([...oneTurnLog(), ...secondTurn])
+    await handle.append(secondTurn)
+    await handle.close()
+    expect((await readAll(ctx.sessionPersistence, header.id)).events).toEqual([...oneTurnLog(), ...secondTurn])
   })
 
   it('skips empty, incomplete, and non-header compressed artifacts while rejecting malformed header frames', async () => {
@@ -706,7 +740,7 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       '',
     ].join('\n')))
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/first frame is not exactly one header line/)
-    await expect(ctx.sessionPersistence.load(SessionId('two-lines')))
+    await expect(ctx.sessionPersistence.open(twoLinesId, 'read'))
       .rejects.toThrow(/first frame is not exactly one header line/)
   })
 
@@ -722,9 +756,9 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
     await writeFile(logPath(root, undefined, SessionId('bad-checksum'), 'zstd'), corruptHeader)
     const ctx = await mount(root)
 
-    await expect(ctx.sessionPersistence.load(SessionId('partial-only')))
+    await expect(ctx.sessionPersistence.open(SessionId('partial-only'), 'read'))
       .rejects.toThrow(/empty or header-less Zstandard session log/)
-    await expect(ctx.sessionPersistence.load(SessionId('empty-header')))
+    await expect(ctx.sessionPersistence.open(SessionId('empty-header'), 'read'))
       .rejects.toThrow(/first frame is not exactly one header line/)
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/header frame failed validation/)
   })
@@ -734,17 +768,13 @@ describe('JsonlSessionPersistence: encoding selection', () => {
   it('rejects roots owned by the opposite encoding in both directions', async () => {
     const rawRoot = await freshRoot('dsh-jsonl-raw-mismatch-')
     const raw = await mount(rawRoot, 'none')
-    const rawHeader = meta('raw-log')
-    await raw.sessionPersistence.create(rawHeader)
-    await raw.sessionPersistence.append(rawHeader.id, oneTurnLog())
+    await writeLog(raw.sessionPersistence, meta('raw-log'), oneTurnLog())
     const defaultBackend = await mount(rawRoot)
     await expect(defaultBackend.sessionPersistence.list()).rejects.toThrow(/configured for compression "zstd"/)
 
     const zstdRoot = await freshRoot('dsh-jsonl-zstd-mismatch-')
     const zstd = await mount(zstdRoot)
-    const zstdHeader = meta('zstd-log')
-    await zstd.sessionPersistence.create(zstdHeader)
-    await zstd.sessionPersistence.append(zstdHeader.id, oneTurnLog())
+    await writeLog(zstd.sessionPersistence, meta('zstd-log'), oneTurnLog())
     const rawBackend = await mount(zstdRoot, 'none')
     await expect(rawBackend.sessionPersistence.list()).rejects.toThrow(/configured for compression "none"/)
   })
@@ -761,9 +791,8 @@ describe('JsonlSessionPersistence: encoding selection', () => {
       ...oneTurnLog().map(e => JSON.stringify(e)),
       '',
     ].join('\n'))
-    await expect(ctx.sessionPersistence.load(loadHeader.id)).rejects.toThrow(/uses \.jsonl/)
-    await expect((ctx.sessionPersistence as JsonlSessionPersistence).loadStored(loadHeader.id))
-      .rejects.toThrow(/uses \.jsonl/)
+    await expect(ctx.sessionPersistence.open(loadHeader.id, 'read')).rejects.toThrow(/uses \.jsonl/)
+    await expect(ctx.sessionPersistence.open(loadHeader.id, 'write')).rejects.toThrow(/uses \.jsonl/)
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/uses \.jsonl/)
   })
 
@@ -772,14 +801,15 @@ describe('JsonlSessionPersistence: encoding selection', () => {
     const ctx = await mount(root)
     await ctx.sessionPersistence.list()
     const header = meta('late-raw-materialize', '/late')
-    await ctx.sessionPersistence.create(header)
+    const handle = await ctx.sessionPersistence.create(header)
     await mkdir(sessionDir(root, header.cwd, header.id), { recursive: true })
     await writeFile(logPath(root, header.cwd, header.id, 'none'), [
       JSON.stringify(toHeaderLine(header)),
       ...oneTurnLog().map(e => JSON.stringify(e)),
       '',
     ].join('\n'))
-    await expect(ctx.sessionPersistence.append(header.id, oneTurnLog())).rejects.toThrow(/uses \.jsonl/)
+    await expect(handle.append(oneTurnLog())).rejects.toThrow(/uses \.jsonl/)
+    await handle.close()
     expect((await readdir(sessionDir(root, header.cwd, header.id))).some(name => name.endsWith('.jsonl.zstd'))).toBe(false)
   })
 })
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index 6cb47067fa..8d50b72854 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/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/session/session-persistence/README.md
-README.md: 6d430173b985d7e32b615e0b42713a925bc8b344
-README.zh.md: a3b6cd90fa4ccba2b28f0e81517bbabab0ce047e
+README.md: 2c7716e1512a9b5dac2ae966c6d59ac45d03297a
+README.zh.md: 0039ef280e730afe3f234d3658c11b7a2c4cc2f9
diff --git a/packages/session/session-persistence/README.md b/packages/session/session-persistence/README.md
index 6d430173b9..2c7716e151 100644
--- a/packages/session/session-persistence/README.md
+++ b/packages/session/session-persistence/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-session-persistence` stores a session's event log durably, reloads it on resume, and lists stored sessions through the backend-neutral `ctx.sessionPersistence` service. The persisted unit is the existing `SessionEvent` log — there is no parallel stored message type. `SessionHeader.isSeeded` makes lineage visible to lightweight listing, while the exact `inheritedEventCount` accompanies every body-bearing storage read and prepared Session. A backend owns its storage, while the service owns append-only logs, contiguous sequence numbers, crash recovery that preserves an interrupted turn instead of truncating it, and durable writes that resolve only after the batch is safe. The shipped JSONL provider implements this service with one artifact per Session; third-party providers may implement the same contract without changing the loop or model.
+`dsh-session-persistence` stores a session's event log durably and addresses each stored session through one per-session handle: the backend-neutral service (`ctx.sessionPersistence`) exposes `create`/`open`/`stat`/`list`, and `create`/`open` return a `SessionHandle` that carries every log read and write plus single-writer ownership. The persisted unit is the existing `SessionEvent` log — there is no parallel stored message type — and non-replayable metadata (format version, working directory, lineage, seed boundary) travels separately as `SessionHeader`. Backends own their storage, the seam owns the semantics: append-only contiguous logs, best-effort appends behind an explicit `flush` durability barrier, a torn physical tail that never reaches a reader, fail-closed validation of stored records, and in-process exclusion of a second writer. Mount the shipped [JSONL backend](../session-persistence-jsonl/README.md) (one artifact per session) and agent-loop persists and resumes sessions without the loop or the model knowing which backend is underneath.
 
 ## Table of Contents
 
@@ -25,33 +25,44 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount one persistence backend to make sessions durable. The backend registers itself as `ctx.sessionPersistence`; nothing else in the composition changes — the loop, resume, and replay all call the same service.
+Mount one persistence backend to make sessions durable. The backend registers itself as `ctx.sessionPersistence` and routes every published session's live events into that session's active write handle; agent-loop — the production publication point for sessions — acquires each session's write handle before publication, so nothing else in the composition changes.
 
 ### Choosing a backend
 
-The seam ships the [JSONL](../session-persistence-jsonl/README.md) backend. It stores one append-only `.jsonl.zstd` artifact per Session and returns its absolute path from `locate(meta)`. A third-party backend may implement the service directly; the [backend contract](#understand-the-implementation) below is what it must honor.
+The seam ships the [JSONL](../session-persistence-jsonl/README.md) backend: one append-only `.jsonl.zstd` log per session. A third-party backend may implement the service directly; the [backend contract](#understand-the-implementation) below is what it must honor.
 
 ### What the service provides
 
-With a backend mounted, you can store a session's events durably, reload the stored log, and list what is stored:
+With a backend mounted, five service methods address stored sessions:
 
 ```text
-await ctx.sessionPersistence.create(meta, inheritedEventCount) // cut required when meta.isSeeded
-await ctx.sessionPersistence.ensureMaterialized(session)   // persist an empty resumable session
-await ctx.sessionPersistence.append(id, events)            // durably persist a batch
-const { meta, inheritedEventCount, events } = await ctx.sessionPersistence.load(id)
-const headers = await ctx.sessionPersistence.list()        // every stored session
+const handle = await ctx.sessionPersistence.create(header)     // store a new session, take write ownership
+const handle = await ctx.sessionPersistence.open(id, 'write')  // claim single-writer ownership of an existing session
+const reader = await ctx.sessionPersistence.open(id, 'read')   // observe without ownership
+const snap = await ctx.sessionPersistence.stat(id)             // header + revision (+ eventCount / sizeBytes) without a log read
+const all = await ctx.sessionPersistence.list()                // one snapshot per visible stored session
+await ctx.sessionPersistence.flush()                           // backend-wide durability barrier over every active write handle
 ```
 
-`append` resolves only after the batch is durable, so a resolved write survives an OS crash or power loss. Ordinary `create(meta, inheritedEventCount)` remains lazy; `meta.isSeeded: true` requires the sibling exact cut, while unseeded metadata may omit it and rejects a nonzero value. The first materializing batch for a seeded session must reach the complete inherited prefix, so storage never exposes metadata whose cut exceeds its log. A lifecycle frontend calls `ensureMaterialized` only when an empty session must itself appear in durable listing without inventing an event. `load` returns an immutable balanced log and commits any needed crash recovery; `inspect` reads the same complete view without committing recovery. `readFrom` accepts a `SessionLogOffset` and returns a detached `SessionEventSuffix` carrying that `fromSeq`, the unchanged inherited cut, and only stored events at or after the cut. A session's artifact location (`locate`) resolves without filesystem I/O.
+Service-level `flush()` drains every active write handle's routed events and materializes its session, exactly as each handle's own `flush` would; failures aggregate per session as an `AggregateError` without abandoning the sweep, and a handle closed mid-sweep counts as flushed because close itself drains durably.
+
+Every log read and write flows through the returned `SessionHandle`; there are no id-addressed append or load methods. `handle.read(offset?, length?)` returns validated contiguous prefix slices — never a torn tail, and repeated reads on one handle never observe an older state than a prior read; a write handle reads its own successful appends. `handle.append(events)` appends a contiguous batch whose first `seq` equals the stored next-seq; persistence is best-effort on resolution — the batch is accepted, ordered, and visible to reads on this backend instance, and only a resolved `flush` promises it survives a crash (the shipped JSONL backend happens to persist each batch immediately). `handle.flush()` is the durability barrier and also materializes an empty created session so it becomes durably listable. `handle.close()` is idempotent and uncancellable: a read handle frees local resources, a write handle completes pending durability and releases write ownership. Once an `append` or `flush` resolves, reads started afterwards on the same backend instance — on any handle, or through `stat`/`list` — observe at least that prefix.
+
+### Ownership and visibility
+
+`create` and `open(id, 'write')` take in-process single-writer ownership: a second write open while an owner is active rejects with `SessionAlreadyOwnedError`, `create` on an occupied id rejects with `SessionAlreadyExistsError`, and a mutation on a `read` handle rejects with `SessionReadOnlyError` — one handle type, runtime refusal. Any operation on a closed handle rejects with `SessionHandleClosedError`, and `SessionOwnershipLostError` marks a write handle whose ownership is permanently gone (close it and reopen). A created session is observable in this process from the moment `create` resolves, while the backend may defer physical materialization until the first `append` or `flush`; other processes see only materialized sessions, and a session that never materialized before a crash never existed.
+
+### The live write path and shutdown drain
+
+The backend owns the live write path: it installs the session listeners once and routes every published session's events by id to that session's active write handle — `session/event` copies into a bounded internal batching window, `session/flush` is the immediate durability and error-observation barrier, and `session/disposed` runs the final drain and closes the handle. A published session without an active write handle persists nothing. A background write failure retains its events in order, pauses the automatic path, and is logged; the next explicit flush retries and rejects loudly. `close()` itself drains the routed buffer through the still-open storage before releasing ownership, so backend teardown's close sweep keeps application shutdown lossless even though root-fiber disposal runs fibers' disposers concurrently.
 
 ### Resuming and crash recovery
 
-Resume is `load` plus session preparation: the stored log comes back with its header lineage and exact inherited cut intact, so ownership checks do not infer the cut from a marker or the full restore length. A session that crashed mid-turn reloads with its interrupted final turn preserved and balanced: `load` appends synthetic `tool/result` and `turn/end {interrupted}` closers for unanswered calls instead of dropping the events — a single turn can be large, and those events were durably written before the crash. Only a never-fully-written torn tail fragment is discarded.
+Persistence returns the physically valid log; semantic repair belongs to the reader. A session that crashed mid-turn keeps its open final turn — a single turn can be large, and those events were durably appended before the crash; only the incomplete fragment of a never-acknowledged torn tail is discarded — complete records recovered from it are durably rewritten by the write path before the handle's first new append. Resume (agent-loop) reads the stored log through its write handle, computes `interruptedTurnClosers` — synthetic `tool/result` errors, any open `step/end`, and `turn/end {interrupted}` — and appends them through the same handle as an ordinary batch. Read-only observers (session-query) balance an interrupted cold log with the same closers in memory only.
 
 ### Failures and recovery
 
-A stored log the current build cannot faithfully interpret is refused with a direction-aware error, never misread. `SESSION_FORMAT_VERSION` remains v0 and this build provides no format-migration path; a newer version instructs the operator to upgrade the harness. The decoder accepts only the bounded same-version record variants named below. An event type unknown to this build refuses unless its envelope marks it `ignorable`, and committed-prefix corruption rejects as `SessionPersistenceCorruptionError`. A `load` on an id still bound to a live session first flushes its snapshot and rejects while its turn is open; a cold load applies recovery.
+A stored log the current build cannot faithfully interpret is refused with a direction-aware error, never misread. `SESSION_FORMAT_VERSION` remains v0 and this build provides no format-migration path; a newer version instructs the operator to upgrade the harness. The decoder accepts only the bounded same-version record variants named below. An event type unknown to this build refuses unless its envelope marks it `ignorable`, and committed-prefix corruption rejects as `SessionPersistenceCorruptionError`.
 
 -----
 
@@ -65,33 +76,35 @@ This section explains how the seam realizes durable storage and how backends plu
 
 ### Design concept
 
-The package is the Service Definition of a capability seam with two halves. The abstract `SessionPersistence` service is the public contract; a `PersistenceCoordinator` provides backend-neutral orchestration for buffering, serialization, materialization, repair, adoption, and quiescent disposal. The JSONL provider implements the small durable primitives for stored reads, append, repair, and listing; a third-party provider may reuse the same coordinator or implement the service directly.
+The package is a seam, not a backend framework: it exports the abstract `SessionPersistence` service, the `SessionHandle` contract, the stable error classes consumers catch, the pure stored-record validation helpers (`storage-contract`), and the branded revision — nothing else. Each provider owns its complete storage runtime (handle class, mutation ordering, single-writer bookkeeping, live-event routing, teardown), and two shared test suites — `runPersistenceContract` and `runLiveWritePathContract` under `tests/` — pin the observable behavior every provider must agree on. Deliberate consequence: providers may resemble each other where their storage happens to be similar, but no implementation machinery crosses the package boundary.
 
 ### The invariants every backend honors
 
-- **Append-only; a crashed turn is closed, not truncated.** Flushed events are never rewritten; `load` preserves an interrupted final turn and durably appends synthetic closers.
-- **Contiguous `seq`.** A gap in the middle of the log rejects; `append`'s first `seq` must equal the stored next-seq.
-- **Lossless JSON data.** Batches pass the shared one-pass lossless-JSON boundary; non-serializable payloads reject at the append site.
-- **Durability.** `append` resolves only once the batch is durable.
+- **Append-only, contiguous `seq`.** Committed events are never rewritten; `append`'s first `seq` must equal the stored next-seq, and a gap rejects.
+- **A torn physical tail never reaches a reader.** It belongs to an append that never resolved; the write path truncates it durably before its first new append.
+- **Lossless JSON data.** Batches and headers pass the shared one-pass validate-and-snapshot boundary (`materializeAppendBatch`/`materializeCreateHeader`); non-serializable payloads reject at the call site.
+- **Durability.** `append` persists best-effort; `flush` — per handle or service-wide — is the barrier that promises storage and also materializes an empty session.
+- **Fail-closed reads.** `validateStoredEvents` refuses unknown event vocabulary and retired pre-release shapes; `assertVersion` refuses foreign format versions.
+- **Single writer per backend instance.** The provider's in-process claim is taken at `create`/`open('write')` and released at handle close.
 
 ### Source map
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: the abstract `SessionPersistence` service and re-exported metadata types |
-| [`src/coordinator.ts`](src/coordinator.ts) | Shared write orchestration: batching, serialization, repair, adoption, disposal, format refusal |
-| [`src/write-behind.ts`](src/write-behind.ts) | The per-session bounded write controller and flush barrier |
-| [`src/preparations.ts`](src/preparations.ts) | Bounded retention of unpublished Session preparations for resume reuse |
+| [`src/index.ts`](src/index.ts) | Plugin entry: the abstract `SessionPersistence` service and re-exported seam vocabulary |
+| [`src/handle.ts`](src/handle.ts) | The `SessionHandle` contract: read/append/flush/close semantics and freshness rules |
+| [`src/storage-contract.ts`](src/storage-contract.ts) | Shared validation: version gate, fail-closed vocabulary, batch materialization, contiguity |
+| [`src/errors.ts`](src/errors.ts) | Stable handle/ownership failures and format refusals |
 | [`src/revision.ts`](src/revision.ts) | The branded opaque revision token |
 | — | No runtime invariant companion is published; persistence correctness requires backend round-trip and crash-tail tests; this package exposes no continuously observable in-process relation. |
 
 ### The write path at a glance
 
-Each `session/event` copies the event into its session's controller. The first pending event starts a fixed batching window; later events join without resetting its deadline. Expiry starts one durable append; events admitted during that write form a separately bounded follow-up batch. `session/flush` cancels the wait and drains through quiescence, so the loop uses it as the ordering and error-observation checkpoint before the next turn. A rejected background write retains its events and pauses automatic retry; a new event starts a fresh window, while explicit flush or backend teardown retries immediately.
+Each `session/event` for the writer's session copies into that handle's internal buffer. The first pending event starts a fixed batching window; later events join without resetting its deadline. Expiry drains the pending prefix through the handle's mutation chain; events admitted during a drain coalesce into the next chained batch, in order. `session/flush` cancels the wait and drains through quiescence, then runs `handle.flush()`, so the loop uses it as the ordering and error-observation checkpoint before the next turn. A rejected background drain retains its events and pauses the automatic timer; explicit flush, writer close, or backend teardown retries immediately and rejects loudly. Constructor seed events never emit `session/event`, so a seed appended through the handle before publication is never re-enqueued.
 
-### Stored-record compatibility
+### Stored-record validation
 
-Backend reads normalize only the explicitly supported v0 record variants before validating current records. The coordinator uses the same normalized view for `load`, `inspect`, `readFrom`, ownerless-state claims, and HMR adoption. Reads do not rewrite stored records, and later appends use current v0. The [pre-identity message](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md) and [pre-react-loop session](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md) notes own these bounded exceptions; they are not a general format-migration promise.
+Backend reads validate current v0 records only and never rewrite them; appends write current v0 ([rationale](../../../.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md)). Every backend runs the same `storage-contract` helpers on every read path — handle reads and write-open priming — refusing an unknown event type as `SessionFormatUnsupportedError` and a retired payload variant of a current type as `SessionPersistenceCorruptionError`, with the raw-log `SessionLocation` attached when the backend keeps one artifact per session.
 
 </details>
 -----
@@ -101,9 +114,10 @@ Backend reads normalize only the explicitly supported v0 record variants before
 
 Read these pages when the package-level contract is not enough. They move from the shared durability model to the shipped backends and the decision evidence.
 
-- [Session persistence subsystem](../../../docs/subsystems/persistence.md) — the full service contract, flush checkpoint, crash recovery, and generated Cordis API.
+- [Session persistence subsystem](../../../docs/subsystems/persistence.md) — the full service contract, handle semantics, flush checkpoint, crash recovery, and generated Cordis API.
+- [Handle-based persistence Agent Note](../../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md) — the seam design and its ownership model.
 - [JSONL persistence backend](../session-persistence-jsonl/README.md) — the shipped per-session-file backend.
-- [Session checkpoint policy](../session-checkpoint-policy/README.md) — the plugin that flushes through this service at semantic boundaries.
+- [Session checkpoint policy](../session-checkpoint-policy/README.md) — the plugin that flushes through `session/flush` at semantic boundaries.
 - [Session package map](../README.md) — adjacent persistence, projection, title, and telemetry packages.
 
 -----
@@ -132,9 +146,12 @@ Persistence does not mutate live request prefixes. A resumed loop can reuse prov
 
 These limits define where the seam's guarantees stop. They are current package constraints, not a task backlog.
 
+- **Write ownership is in-process only** — the provider's writer table excludes a second writer inside one backend instance; the durable cross-process lease is the planned next layer on the same handle shape, and until it lands another process must not write the same session.
+- **A backend plugin reload under live sessions fails their writers loudly** — a reloaded backend cannot serve handles the old instance issued; writes fail until the sessions restart, and nothing silently re-adopts the logs.
+- **Only handle-acquired sessions persist** — `ctx.sessions.create` + `session/flush` alone stores nothing; agent-loop is the production acquisition point, and tests seed storage through `create`/`append`/`close`.
 - **No deletion or retention API** — pruning stored sessions is out-of-band backend maintenance.
-- **`list()` is unpaginated and unfiltered** — it returns every stored session's header; fine for local stores, unindexed at scale.
-- **Synthetic closers are the only crash story** — a backend must synthesize `tool/result`/`step/end`/`turn/end` closers on load; there is no partial-turn resume that continues an interrupted turn instead of closing it.
+- **`list()` is unpaginated and unfiltered** — it returns every stored session's snapshot; fine for local stores, unindexed at scale.
+- **Synthetic closers are the only crash story** — resume appends `interruptedTurnClosers` through the write handle; there is no partial-turn resume that continues an interrupted turn instead of closing it.
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/session/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
index a3b6cd90fa..0039ef280e 100644
--- a/packages/session/session-persistence/README.zh.md
+++ b/packages/session/session-persistence/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-session-persistence` 通过后端无关的 `ctx.sessionPersistence` 服务持久存储会话的事件日志、在恢复时重新加载并列出已存储会话。持久化单元就是现有 `SessionEvent` 日志——不存在另一套并行的存储消息类型。`SessionHeader.isSeeded` 让轻量列表可见血缘，而精确的 `inheritedEventCount` 随每次带正文的存储读取与 prepared Session 一同传输。后端拥有自己的存储，而服务拥有仅追加日志、连续序列号、保留中断轮次而非截断的崩溃恢复，以及只在批次安全后才返回的持久写入。随产品交付的 JSONL provider 用每个 Session 一份产物实现该服务；第三方 provider 可以实现同一约定，而不改变 loop 或模型。
+`dsh-session-persistence` 持久存储会话的事件日志，并通过一个逐会话句柄寻址每个已存储会话：后端无关服务（`ctx.sessionPersistence`）暴露 `create`/`open`/`stat`/`list`，`create`/`open` 返回承载全部日志读写与单写者所有权的 `SessionHandle`。持久化单元就是现有 `SessionEvent` 日志——不存在另一套并行的存储消息类型——不可回放的元数据（格式版本、工作目录、血缘、种子边界）作为 `SessionHeader` 单独传输。后端拥有自己的存储，seam 拥有语义：仅追加的连续日志、以显式 `flush` 持久性屏障托底的尽力而为 append、绝不到达读取方的撕裂物理尾部、失败即关闭的存储记录校验，以及进程内排除第二个写入方。挂载随产品交付的 [JSONL 后端](../session-persistence-jsonl/README.zh.md)（每个会话一份产物），agent-loop 就会持久化并恢复会话，loop 与模型无需知道下面是哪个后端。
 
 ## 目录
 
@@ -25,33 +25,44 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-挂载一个持久化后端即可让会话持久化。后端把自己注册为 `ctx.sessionPersistence`；组合中的其他部分不变——loop、恢复与回放调用的是同一个服务。
+挂载一个持久化后端即可让会话持久化。后端把自己注册为 `ctx.sessionPersistence`，并把每个已发布会话的实时事件路由进该会话的活跃写句柄；agent-loop——会话在生产环境中的发布点——在发布之前获取每个会话的写句柄，因此组合中的其他部分不变。
 
 ### 选择后端
 
-seam 随产品交付 [JSONL](../session-persistence-jsonl/README.zh.md) 后端。它把每个 Session 存为一份仅追加 `.jsonl.zstd` 产物，并由 `locate(meta)` 返回绝对路径。第三方后端可以直接实现该服务；必须遵守的[后端约定](#understand-the-implementation)见下文。
+seam 随产品交付 [JSONL](../session-persistence-jsonl/README.zh.md) 后端。它把每个 Session 存为一份仅追加 `.jsonl.zstd` 产物。第三方后端可以直接实现该服务；必须遵守的[后端约定](#understand-the-implementation)见下文。
 
 ### 服务提供什么
 
-挂载后端后，你可以持久存储会话事件、重新加载已存储日志并列出已存储内容：
+挂载后端后，五个服务方法寻址已存储会话：
 
 ```text
-await ctx.sessionPersistence.create(meta, inheritedEventCount) // cut required when meta.isSeeded
-await ctx.sessionPersistence.ensureMaterialized(session)   // persist an empty resumable session
-await ctx.sessionPersistence.append(id, events)            // durably persist a batch
-const { meta, inheritedEventCount, events } = await ctx.sessionPersistence.load(id)
-const headers = await ctx.sessionPersistence.list()        // every stored session
+const handle = await ctx.sessionPersistence.create(header)     // store a new session, take write ownership
+const handle = await ctx.sessionPersistence.open(id, 'write')  // claim single-writer ownership of an existing session
+const reader = await ctx.sessionPersistence.open(id, 'read')   // observe without ownership
+const snap = await ctx.sessionPersistence.stat(id)             // header + revision (+ eventCount / sizeBytes) without a log read
+const all = await ctx.sessionPersistence.list()                // one snapshot per visible stored session
+await ctx.sessionPersistence.flush()                           // backend-wide durability barrier over every active write handle
 ```
 
-`append` 只在批次持久后返回，因此成功返回的写入在操作系统崩溃或断电后依然存在。普通 `create(meta, inheritedEventCount)` 保持惰性；`meta.isSeeded: true` 要求单独的精确 cut，unseeded metadata 可以省略它并拒绝非零值。seeded 会话的首个物化批次必须到达完整继承前缀，因此存储绝不公开 cut 超过日志的 metadata。只有当空会话本身必须出现在持久列表中时，生命周期前端才调用 `ensureMaterialized`，且不会虚构事件。`load` 返回不可变的平衡日志并提交任何需要的崩溃恢复；`inspect` 读取同一份完整视图但不提交恢复。`readFrom` 接受 `SessionLogOffset`，并返回分离的 `SessionEventSuffix`，其中携带该 `fromSeq`、不变的继承 cut，以及 cut 位置或之后的存储事件。会话的产物位置（`locate`）不经文件系统 I/O 即可解析。
+服务级 `flush()` 排空每个活跃写句柄已路由的事件并把其会话实体化，效果与各句柄自己的 `flush` 完全相同；失败按会话聚合为一个 `AggregateError` 而不中途放弃清扫，清扫途中被关闭的句柄视同已 flush，因为 close 本身会持久排空。
+
+每一次日志读写都流经返回的 `SessionHandle`；不存在按 id 寻址的 append 或 load 方法。`handle.read(offset?, length?)` 返回经过验证的连续前缀切片——绝不返回撕裂尾部，且同一句柄上的重复读取绝不会观察到比先前读取更旧的状态；写句柄能读到自己成功的 append。`handle.append(events)` 追加一个连续批次，其第一个 `seq` 等于已存储 next-seq；完成时的持久化是尽力而为的——批次被接受、有序，并对同一后端实例上的读取可见，只有完成的 `flush` 才承诺它在崩溃后依然存在（交付的 JSONL 后端恰好会立即持久化每个批次）。`handle.flush()` 是持久性屏障，同时把空的已创建会话实体化，使其可被持久列出。`handle.close()` 幂等且不可取消：读句柄释放本地资源，写句柄完成待处理的持久化并释放写所有权。一旦某次 `append` 或 `flush` 完成，其后在同一后端实例上开始的读取——无论经由任何句柄，还是经由 `stat`/`list`——至少能观察到该前缀。
+
+### 所有权与可见性
+
+`create` 与 `open(id, 'write')` 取得进程内单写者所有权：在持有者活跃期间第二次以写模式打开会以 `SessionAlreadyOwnedError` 拒绝，对已占用 id 执行 `create` 会以 `SessionAlreadyExistsError` 拒绝，在 `read` 句柄上执行修改会以 `SessionReadOnlyError` 拒绝——一种句柄类型，运行时拒绝。对已关闭句柄的任何操作会以 `SessionHandleClosedError` 拒绝，`SessionOwnershipLostError` 标记写所有权已永久丢失的写句柄（关闭并重新打开）。已创建的会话自 `create` 完成之刻起即可在本进程内被观察到，而后端可以把物理实体化推迟到第一次 `append` 或 `flush`；其他进程只能看到已实体化的会话，一个在崩溃前从未实体化的会话等于从未存在。
+
+### 实时写路径与关闭排空
+
+实时写路径由后端自持：它一次性安装会话监听器，把每个已发布会话的事件按 id 路由到该会话的活跃写句柄——`session/event` 复制进有界的内部批处理窗口，`session/flush` 是即时的持久性与错误观察屏障，`session/disposed` 执行最终排空并关闭句柄。没有活跃写句柄的已发布会话不做任何持久化。后台写入失败时按序保留其事件、暂停自动路径并记入日志；下一次显式 flush 会重试并响亮地拒绝。`close()` 本身会先经由仍然打开的存储排空路由缓冲区再释放所有权，因此即便根 fiber 的 dispose 并发运行各 fiber 的 disposer，后端 teardown 的关闭清扫也能保证应用关闭不丢数据。
 
 ### 恢复与崩溃恢复
 
-恢复就是 `load` 加会话准备：存储日志连同其 header 血缘与精确继承切点一起返回，因此所有权检查不从标记或完整恢复长度推断切点。中途崩溃的会话重新加载时，其被中断的最终轮次会保留并保持平衡：`load` 为未获回答的调用追加合成 `tool/result` 与 `turn/end {interrupted}` closer，而不是丢弃事件——单个轮次可能很大，而这些事件在崩溃前已持久写入。只有从未完整写入的撕裂尾部碎片会被丢弃。
+持久化返回物理上有效的日志；语义修复属于读方。中途崩溃的会话保留其未闭合的最终轮次——单个轮次可能很大，而这些事件在崩溃前已持久追加；只有从未确认的撕裂尾部中不完整的碎片会被丢弃——从中恢复的完整记录由写路径在句柄的第一次新 append 之前持久重写。恢复（agent-loop）通过其写句柄读取已存储日志，计算 `interruptedTurnClosers`——合成 `tool/result` 错误、任何未闭合的 `step/end`，以及 `turn/end {interrupted}`——并把它们作为普通批次通过同一句柄追加。只读观察方（session-query）仅在内存中用同样的 closer 配平被中断的冷日志。
 
 ### 失败与恢复
 
-当前构建无法忠实解读的存储日志会以方向感知的错误被拒绝，绝不错读。`SESSION_FORMAT_VERSION` 保持 v0，本构建不提供格式迁移路径；更高版本会要求操作者升级 harness。解码器只接受下文点名的有限同版本记录变体。本构建不认识的事件类型会被拒绝，除非其信封标记为 `ignorable`；已提交前缀中的损坏以 `SessionPersistenceCorruptionError` 拒绝。对仍绑定到活动会话的 id 执行 `load`，会先刷新其快照并在轮次开放时拒绝；冷 load 应用恢复。
+当前构建无法忠实解读的存储日志会以方向感知的错误被拒绝，绝不错读。`SESSION_FORMAT_VERSION` 保持 v0，本构建不提供格式迁移路径；更高版本会要求操作者升级 harness。解码器只接受下文点名的有限同版本记录变体。本构建不认识的事件类型会被拒绝，除非其信封标记为 `ignorable`；已提交前缀中的损坏以 `SessionPersistenceCorruptionError` 拒绝。
 
 -----
 
@@ -65,33 +76,35 @@ const headers = await ctx.sessionPersistence.list()        // every stored sessi
 
 ### 设计理念
 
-本包是能力 seam 的 Service Definition，分两半。抽象的 `SessionPersistence` 服务是公开约定；`PersistenceCoordinator` 为缓冲、串行化、物化、修复、接管与完全停稳的 dispose 提供后端无关编排。JSONL provider 实现存储读取、追加、修复与列出所需的小型持久原语；第三方 provider 可以复用同一 coordinator，也可以直接实现该服务。
+本包是 seam，而不是后端框架：它只导出抽象 `SessionPersistence` 服务、`SessionHandle` 约定、消费方捕获的稳定 error 类、纯函数的存储记录校验辅助（`storage-contract`）以及带品牌类型的 revision——再无其他。每个 provider 拥有自己完整的存储运行时（句柄类、修改排序、单写者记账、实时事件路由、teardown），`tests/` 下的两套共享测试套件——`runPersistenceContract` 与 `runLiveWritePathContract`——钉住每个 provider 都必须一致的可观察行为。有意为之的后果：各 provider 在存储恰好相似之处可以彼此相像，但没有任何实现机制跨越包边界。
 
 ### 每个后端必须遵守的不变量
 
-- **仅追加；崩溃轮次会被关闭，而非截断。** 已 flush 事件绝不重写；`load` 保留中断的最终轮次并持久追加合成 closer。
-- **连续 `seq`。** 日志中间的缺口会被拒绝；`append` 的第一个 `seq` 必须等于已存储 next-seq。
-- **无损 JSON 数据。** 批次经过共享单遍无损 JSON 边界；无法序列化的载荷在 append 处被拒绝。
-- **持久性。** `append` 只在批次持久后返回。
+- **仅追加，连续 `seq`。** 已提交事件绝不重写；`append` 的第一个 `seq` 必须等于已存储 next-seq，缺口会被拒绝。
+- **撕裂的物理尾部绝不到达读取方。** 它属于一次从未完成的 append；写路径在第一次新 append 之前将其持久截断。
+- **无损 JSON 数据。** 批次与 header 经过共享的单遍校验并快照边界（`materializeAppendBatch`/`materializeCreateHeader`）；无法序列化的载荷在调用处被拒绝。
+- **持久性。** `append` 尽力而为地持久化；`flush`——逐句柄或服务级——是承诺存储并同时把空会话实体化的屏障。
+- **失败即关闭的读取。** `validateStoredEvents` 拒绝未知事件词汇与已废弃的预发布形态；`assertVersion` 拒绝外来格式版本。
+- **每个后端实例单写者。** provider 的进程内认领在 `create`/`open('write')` 时取得，在句柄关闭时释放。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：抽象 `SessionPersistence` 服务与重新导出的元数据类型 |
-| [`src/coordinator.ts`](src/coordinator.ts) | 共享写入编排：批处理、串行化、修复、接管、dispose、格式拒绝 |
-| [`src/write-behind.ts`](src/write-behind.ts) | 每会话有界写入控制器与 flush 屏障 |
-| [`src/preparations.ts`](src/preparations.ts) | 为恢复复用而有界保留的未发布 Session 准备结果 |
+| [`src/index.ts`](src/index.ts) | 插件入口：抽象 `SessionPersistence` 服务与重新导出的 seam 词汇 |
+| [`src/handle.ts`](src/handle.ts) | `SessionHandle` 约定：read/append/flush/close 语义与新鲜度规则 |
+| [`src/storage-contract.ts`](src/storage-contract.ts) | 共享校验：版本门、失败即关闭词汇表、批次实体化、连续性 |
+| [`src/errors.ts`](src/errors.ts) | 稳定的句柄/所有权失败与格式拒绝 |
 | [`src/revision.ts`](src/revision.ts) | 带品牌类型的不透明修订值 token |
-| — | 不发布运行时不变式伴生入口；协调器断言存储/活动身份与 cwd。 |
+| — | 不发布运行时不变式伴生入口；持久化正确性需要后端往返与崩溃尾部测试；本包不暴露可持续观察的进程内关系。 |
 
 ### 写入路径概览
 
-每个 `session/event` 把事件复制到其会话的 controller。第一个待处理事件开启固定批处理窗口；后续事件加入但不重置截止时间。窗口到期后启动一次持久追加；该次写入期间接纳的事件形成另一个独立有界的后续批次。`session/flush` 取消等待并排空至完全停稳，因此 loop 在下一轮次前把它用作排序与错误观察检查点。被拒绝的后台写入保留其事件并暂停自动重试；新事件开启新窗口，而显式 flush 或后端拆卸会立即重试。
+写入器会话的每个 `session/event` 都复制进该句柄的内部缓冲。第一个待处理事件开启固定批处理窗口；后续事件加入但不重置截止时间。窗口到期后经由句柄的修改链排空待处理前缀；排空期间接纳的事件按顺序合并进下一个链上的批次。`session/flush` 取消等待并排空至完全停稳，随后运行 `handle.flush()`，因此 loop 在下一轮次前把它用作排序与错误观察检查点。被拒绝的后台排空保留其事件并暂停自动计时器；显式 flush、写入器 close 或后端 teardown 会立即重试并响亮地拒绝。构造 seed 事件绝不发出 `session/event`，因此发布前通过句柄追加的 seed 绝不会被重新入队。
 
-### 存储记录兼容
+### 存储记录校验
 
-后端读取只会在校验当前记录之前，规范化明确支持的 v0 记录变体。协调器对 `load`、`inspect`、`readFrom`、无所有者状态认领与 HMR 接管使用同一份规范化视图。读取不会重写已存记录，后续追加使用当前 v0。[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md)与 [react-loop 引入前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md)笔记规定这些有限例外；它们不构成通用格式迁移承诺。
+后端读取只校验当前 v0 记录且绝不重写它们；追加写入当前 v0（[理由](../../../.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.zh.md)）。每个后端在每条读取路径——句柄读取与写打开预热——上运行同一套 `storage-contract` 辅助函数，把未知事件类型作为 `SessionFormatUnsupportedError` 拒绝，把当前类型的已废弃载荷变体作为 `SessionPersistenceCorruptionError` 拒绝，并在后端为每个会话保留一份产物时附上原始日志的 `SessionLocation`。
 
 </details>
 -----
@@ -101,9 +114,10 @@ const headers = await ctx.sessionPersistence.list()        // every stored sessi
 
 当包级约定不够用时阅读以下页面。它们从共享持久性模型逐步进入随产品交付的后端与决策证据。
 
-- [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——完整服务约定、flush 检查点、崩溃恢复与生成的 Cordis API。
+- [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——完整服务约定、句柄语义、flush 检查点、崩溃恢复与生成的 Cordis API。
+- [基于句柄的持久化 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md)——seam 设计及其所有权模型。
 - [JSONL 持久化后端](../session-persistence-jsonl/README.zh.md)——随产品交付、按会话存储文件的后端。
-- [会话检查点策略](../session-checkpoint-policy/README.zh.md)——在语义边界上经由本服务刷新的插件。
+- [会话检查点策略](../session-checkpoint-policy/README.zh.md)——在语义边界上经由 `session/flush` 刷新的插件。
 - [会话包映射](../README.zh.md)——相邻的持久化、投影、标题与遥测包。
 
 -----
@@ -132,9 +146,12 @@ seam 不添加提示词或 schema。恢复会将已存储的表层事件还原
 
 这些限制界定 seam 保证的终点。它们是当前包约束，不是任务积压。
 
+- **写所有权仅限进程内**——provider 的写入器表只在单个后端实例内排除第二个写入方；持久的跨进程租约是计划在同一句柄形态上叠加的下一层，在它落地之前另一进程不得写入同一会话。
+- **在有活跃会话时重载后端插件会使其写入器响亮地失败**——重载后的后端无法服务旧实例签发的句柄；写入会持续失败直到会话重启，没有任何机制静默重新接管日志。
+- **只有通过句柄获取的会话才会持久化**——仅靠 `ctx.sessions.create` + `session/flush` 不存储任何内容；agent-loop 是生产环境的获取点，测试通过 `create`/`append`/`close` 播种存储。
 - **无删除或保留接口**——剪枝已存储会话属于带外后端维护。
-- **`list()` 无分页且无过滤**——它返回每个已存储会话的 header；适合本地存储，大规模时无索引。
-- **合成 closer 是唯一崩溃方案**——后端必须在 load 时合成 `tool/result`/`step/end`/`turn/end` closer；没有继续中断轮次而不先关闭它的部分轮次恢复。
+- **`list()` 无分页且无过滤**——它返回每个已存储会话的快照；适合本地存储，大规模时无索引。
+- **合成 closer 是唯一崩溃方案**——恢复通过写句柄追加 `interruptedTurnClosers`；没有继续中断轮次而不先关闭它的部分轮次恢复。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/session/session-persistence/src/coordinator.ts b/packages/session/session-persistence/src/coordinator.ts
deleted file mode 100644
index c16fae6d40..0000000000
--- a/packages/session/session-persistence/src/coordinator.ts
+++ /dev/null
@@ -1,1564 +0,0 @@
-/**
- * Shared buffering, serialization, adoption, repair, and disposal orchestration
- * for first-party backends. Third-party backends may implement the public
- * persistence seam directly.
- * @module @deepseek-ai/dsh-session-persistence/coordinator
- */
-
-import { Context } from '@deepseek-ai/cordis'
-import {
-  adoptSessionEvent,
-  interruptedTurnClosers,
-  KNOWN_SESSION_EVENT_TYPES,
-  SESSION_FORMAT_VERSION,
-  SessionLogOffset,
-  SessionPreparation,
-  SessionSeq,
-  snapshotSessionEvent,
-} from '@deepseek-ai/dsh-session'
-import type {
-  Session,
-  SessionEvent,
-  SessionId,
-  SessionHeader,
-  SessionLogOffset as SessionLogOffsetType,
-  SessionSeq as SessionSeqType,
-} from '@deepseek-ai/dsh-session'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import { snapshotJsonValue } from '@deepseek-ai/dsh-util-values'
-import type {
-  BorrowedSessionSource,
-  SessionEventSuffix,
-  SessionInspection,
-  SessionLocation,
-  SessionStorageMetadata,
-} from './index.ts'
-import { SessionPersistenceNotFoundError } from './errors.ts'
-import type { SessionPersistenceRevision } from './revision.ts'
-import { observeQueuedAbort, SessionPreparations } from './preparations.ts'
-import type { SessionPreparationReservation } from './preparations.ts'
-import { SessionWriteBehind } from './write-behind.ts'
-
-/** Default number of detached session preparations retained by a coordinator. */
-export const DEFAULT_PREPARED_SESSION_CACHE_SIZE = 5
-
-/** Default maximum intentional wait before a live session batch starts writing. */
-export const DEFAULT_WRITE_BATCH_MAX_DELAY_MS = 200
-
-/** Largest write batching delay accepted by Node's timer implementation. */
-export const MAX_WRITE_BATCH_DELAY_MS = MAX_TIMER_DELAY_MS
-
-/** Durable session contents failed validation after a successful backend read. */
-export class SessionPersistenceCorruptionError extends Error {
-  /**
-   * @param message - stable corruption context.
-   * @param options - original validation failure.
-   */
-  constructor(message: string, options: ErrorOptions) {
-    super(message, options)
-    this.name = 'SessionPersistenceCorruptionError'
-  }
-}
-
-/**
- * The stored log is intact but this runtime cannot faithfully interpret it:
- * the header carries an unsupported format version, or an event's type is
- * unknown to this build and the event is not marked ignorable. Distinct from
- * {@link SessionPersistenceCorruptionError} — nothing is damaged; the raw log
- * remains readable at {@link location} when the backend keeps one artifact
- * per session.
- */
-export class SessionFormatUnsupportedError extends Error {
-  /**
-   * @param message - stable reason the log cannot be interpreted, already
-   *   including the raw-log path when one exists.
-   * @param location - the backend's artifact location, when one exists.
-   */
-  constructor(message: string, readonly location?: SessionLocation) {
-    super(message)
-    this.name = 'SessionFormatUnsupportedError'
-  }
-}
-
-/**
- * Direction-aware refusal text for a stored session whose format version this
- * build does not read. Shared by the coordinator's load-time check and by
- * backends that must refuse BEFORE decoding version-dependent structure (a
- * future format may not satisfy this build's structural checks at all, and the
- * user must see "upgrade the harness", never "corrupt").
- * @param id - the stored session id, for message context.
- * @param version - the stored format version.
- * @returns the stable refusal text, without a raw-log path suffix.
- */
-export function sessionFormatVersionRefusal(id: string, version: number): string {
-  return version > SESSION_FORMAT_VERSION
-    ? `session "${id}" uses log format v${version}, but this harness reads only v${SESSION_FORMAT_VERSION}: the log was written by a newer harness — upgrade the harness to open it`
-    : `session "${id}" uses log format v${version}, older than the supported v${SESSION_FORMAT_VERSION}, and this build ships no upgrade path for it`
-}
-
-/** Coordinator policy supplied by a concrete persistence backend. */
-export interface PersistenceCoordinatorOptions {
-  /** Maximum completed unpublished preparations retained for reuse. */
-  readonly preparedSessionCacheSize: number
-  /** Maximum intentional batching wait after an idle live queue receives work. */
-  readonly writeBatchMaxDelayMs: number
-}
-
-/**
- * A stored session's header, valid contiguous event prefix, source-qualified
- * revision, and optional opaque torn-tail marker. The revision identifies the
- * exact detached prefix. The coordinator only checks marker presence and
- * returns its value to {@link PersistenceBackend.commitRepair}; each backend
- * owns the marker type.
- */
-export interface StoredPrefix<TornMarker = unknown> extends SessionStorageMetadata {
-  events: SessionEvent[]
-  /** Revision observed for exactly this detached prefix. */
-  revision: SessionPersistenceRevision
-  tornMarker?: TornMarker
-}
-
-/**
- * A stored session's header plus the events at or past a requested seq — the
- * return shape of the optional seek-capable
- * {@link PersistenceBackend.loadStoredFrom} hook. Non-mutating reads carry no
- * torn marker: there is nothing to repair.
- */
-export interface StoredSuffix extends SessionStorageMetadata {
-  events: SessionEvent[]
-}
-
-/**
- * The storage contract between {@link PersistenceCoordinator} and a concrete
- * backend: the minimal set of durable primitives the orchestration calls. A
- * backend implements these (over files, rows, an object store, …); the
- * coordinator supplies everything else (buffering, serialization, cursors,
- * adoption, crash repair sequencing, dispose quiescence).
- *
- * @typeParam TornMarker - the backend's opaque torn-tail repair token (see
- * {@link StoredPrefix}). The coordinator treats it as fully opaque.
- */
-export interface PersistenceBackend<TornMarker = unknown> {
-  /** Human-readable backend name, used in the dispose-failure AggregateError. */
-  readonly name: string
-
-  /**
-   * Read a stored prefix by id, scanning every backend storage scope. Returns
-   * `undefined` if no stored artifact exists. Returned metadata must identify
-   * `id` before repair or state publication. Used by resume/load, live adoption,
-   * and — via `!== undefined` — the create-collision probe. The returned
-   * `tornMarker` is present iff there is a torn tail to truncate. Every header
-   * and event graph must be fresh, mutually unaliased, and unretained by the
-   * backend because preparation freezes and publishes them in place. The
-   * returned revision must identify exactly those values and use the same
-   * representation as {@link readStoredRevision}.
-   * @param id - persisted session id to resolve.
-   * @param signal - optional cancellation for backend read work.
-   */
-  loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<TornMarker> | undefined>
-
-  /**
-   * Read the current source-qualified revision for one stored session without
-   * loading its event log. Returns `undefined` when the identity is absent.
-   * @param id - persisted session id to observe.
-   * @param signal - optional cancellation for backend read work.
-   */
-  readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<SessionPersistenceRevision | undefined>
-
-  /**
-   * Optional seek-capable suffix read behind the service's `readFrom`: return
-   * the header plus the stored events with `seq >= fromSeq` without reading
-   * the whole log. A backend whose medium can address events by seq implements
-   * this so `readFrom` scales with the suffix; sequential backends
-   * omit it and the coordinator falls back to {@link loadStored} plus a
-   * forward skip. Non-mutating (no truncation, no closers). Validation of the
-   * region strictly below `fromSeq` is limited to seq contiguity — the
-   * service contract scopes this read to the suffix — unless that suffix
-   * contains a supported legacy shape whose normalization needs earlier
-   * message-identity facts, in which case the coordinator falls back
-   * to the complete stored prefix.
-   * Unknown-type refusal follows the same suffix scope: a seek-capable
-   * backend's `readFrom` checks only the returned suffix, while the
-   * sequential fallback parses the whole artifact and refuses on an unknown
-   * required event anywhere in it — over-refusal on the sequential side is
-   * accepted rather than widening the seek read.
-   * @param id - persisted session id to resolve.
-   * @param fromSeq - first event seq to include (non-negative safe integer,
-   *   validated by the coordinator before this hook runs).
-   * @param signal - optional cancellation for backend read work.
-   */
-  loadStoredFrom?(id: SessionId, fromSeq: SessionLogOffsetType, signal?: AbortSignal): Promise<StoredSuffix | undefined>
-
-  /** Durably create an empty header-only session artifact. */
-  materializeHeader?(storage: SessionStorageMetadata): Promise<void>
-
-  /**
-   * Durably append a CONTIGUOUS batch, lazily materializing the session first
-   * when `!isMaterialized`. The materialize-write and the first event batch MUST
-   * commit ATOMICALLY (a crash between them must not leave a materialized-but-
-   * empty session). Returns once the batch is durable.
-   * The coordinator calls this only after a first batch reaches the declared
-   * inherited prefix length.
-   */
-  appendBatch(
-    storage: SessionStorageMetadata,
-    events: readonly SessionEvent[],
-    isMaterialized: boolean,
-  ): Promise<void>
-
-  /**
-   * Make a crash repair durable: truncate the torn tail (iff
-   * `tornMarker !== undefined`) and append `closers` (iff any). NOT required to
-   * be atomic — a file backend may truncate-then-append in two fsync'd steps.
-   * Used by load (truncate + synthetic closers) and by live-adoption (truncate
-   * only, `closers = []`).
-   */
-  commitRepair(
-    storage: SessionStorageMetadata,
-    tornMarker: TornMarker | undefined,
-    closers: readonly SessionEvent[],
-  ): Promise<void>
-
-  /**
-   * List all stored (materialized) sessions' metadata.
-   * @param signal - optional cancellation for backend listing work.
-   */
-  list(signal?: AbortSignal): Promise<SessionHeader[]>
-
-  /**
-   * Optional side-effect-free artifact locator, used to point refusal
-   * diagnostics ({@link SessionFormatUnsupportedError}) at the raw log.
-   * Backends without one artifact per session omit it or return `undefined`.
-   * @param meta - the header whose artifact is requested.
-   */
-  locate?(meta: SessionHeader): SessionLocation | undefined
-
-  /**
-   * Optional lifecycle teardown (e.g. close a database handle). Awaited by the
-   * coordinator's dispose effect AFTER the quiescence drain. A stateless file
-   * backend omits it.
-   */
-  close?(): Promise<void>
-}
-
-/** Per-session write state held by the coordinator's in-memory bookkeeping. */
-interface SessionState {
-  storage: SessionStorageMetadata
-  /** The next seq the backend expects to append (the stored log length). */
-  cursor: SessionLogOffsetType
-  /**
-   * Whether lazy creation has produced a durable artifact. The first append
-   * atomically materializes the header with events; reclaim logic uses this to
-   * distinguish an unused id from a persisted collision.
-   */
-  materialized: boolean
-  /**
-   * The live Session this state was bound to via `onCreated`, if any. State
-   * created through the public `create()`/`load()` API has no owner; state bound
-   * to a live session lets `onCreated` reject a second, unrelated session on the
-   * same id (a collision) instead of silently no-opping.
-   */
-  owner?: Session
-}
-
-/** One live session's initialization and bounded write-behind controller. */
-interface LiveSessionState {
-  init: Promise<void>
-  writes: SessionWriteBehind
-}
-
-/** One validated cold source and the exact unpublished Session built from it. */
-interface PreparedSessionSource<TornMarker> {
-  readonly inspection: SessionInspection
-  readonly session: Session
-  readonly revision: SessionPersistenceRevision
-  /** Session length after constructor-owned seed markers were appended. */
-  readonly sessionLength: SessionLogOffsetType
-  readonly tornMarker: TornMarker | undefined
-  readonly closers: readonly SessionEvent[]
-}
-
-/** Collect the rejection reasons from a set of promises (none-throwing). */
-async function settledErrors(promises: Iterable<Promise<unknown>>): Promise<unknown[]> {
-  const settled = await Promise.allSettled([...promises])
-  const errors: unknown[] = []
-  for (const result of settled) {
-    if (result.status === 'rejected') errors.push(result.reason)
-  }
-  return errors
-}
-
-/** Whether a live session seed reproduces a persisted prefix exactly. */
-function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly SessionEvent[]): boolean {
-  return prefix.length <= seed.length
-    && prefix.every((event, index) => {
-      const seedEvent = seed[index]
-      return seedEvent !== undefined && JSON.stringify(seedEvent) === JSON.stringify(event)
-    })
-}
-
-/** Normalize the exact fork cut paired with one logical Session header. */
-function storageMetadata(
-  meta: SessionHeader,
-  inheritedEventCount?: SessionLogOffsetType,
-): SessionStorageMetadata {
-  if (meta.isSeeded && inheritedEventCount === undefined) {
-    throw new TypeError('seeded session metadata requires an inherited event count')
-  }
-  const cut = SessionLogOffset(inheritedEventCount ?? 0)
-  if (!meta.isSeeded && cut !== 0) {
-    throw new TypeError('unseeded session metadata inherited event count must be 0')
-  }
-  return { meta, inheritedEventCount: cut }
-}
-
-/** Exact storage metadata owned by one live Session. */
-function sessionStorageMetadata(session: Session): SessionStorageMetadata {
-  return storageMetadata(session.header, session.inheritedEventCount)
-}
-
-/** Reject events from an obsolete v0 vocabulary that this build cannot replay. */
-function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId): void {
-  const legacyType: string = 'request/header-delta'
-  const legacy = events.find(event => event.type === legacyType)
-  if (legacy !== undefined) {
-    throw new Error(`session "${id}" contains unsupported legacy request/header-delta event at seq ${legacy.seq}`)
-  }
-  const legacyModeType: string = 'mode/set'
-  const legacyMode = events.find(event => event.type === legacyModeType)
-  if (legacyMode !== undefined) {
-    throw new Error(`session "${id}" contains unsupported legacy mode/set event at seq ${legacyMode.seq}`)
-  }
-  const fallback = events.find(event => event.type === 'request/header'
-    && (event.data as { reason?: string }).reason === 'fallback')
-  if (fallback !== undefined) {
-    throw new Error(`session "${id}" contains unsupported legacy request/header reason "fallback" at seq ${fallback.seq}`)
-  }
-}
-
-/** Return an object record without widening arrays into message payloads. */
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? value as Record<string, unknown>
-    : undefined
-}
-
-/** Whether a record contains every required key and no key outside the optional extension set. */
-function hasOnlyKeys(
-  record: Record<string, unknown>,
-  required: readonly string[],
-  optional: readonly string[] = [],
-): boolean {
-  const allowed = [...required, ...optional]
-  return Object.keys(record).every(key => allowed.includes(key))
-    && required.every(key => Object.hasOwn(record, key))
-}
-
-type PersistedMessageId = SessionEvent<'user/message'>['data']['id']
-
-/** Mint the stable import identity for a message persisted before identities existed. */
-function legacyMessageId(id: SessionId, seq: SessionSeqType): PersistedMessageId {
-  return `legacy-message:${id}:${seq}` as PersistedMessageId
-}
-
-/** Read a replacement target while leaving malformed surface metadata to the session validator. */
-function replacementStart(event: SessionEvent): SessionSeqType | undefined {
-  const op = asRecord((event as SessionEvent & { surfaceOp?: unknown }).surfaceOp)
-  if (op?.['op'] !== 'replace' || typeof op['start'] !== 'number') return undefined
-  try {
-    return SessionSeq(op['start'])
-  } catch {
-    return undefined
-  }
-}
-
-/** Whether one suffix event needs facts available only from the preceding stored prefix. */
-function needsLegacyPrefix(event: SessionEvent): boolean {
-  const data = asRecord(event.data)
-  const legacySteeringType: string = 'steering/message'
-  if (event.type === legacySteeringType) return true
-  if (data === undefined) return false
-  switch (event.type) {
-    case 'user/message':
-      return !Object.hasOwn(data, 'id') && Object.hasOwn(data, 'content')
-    case 'assistant/message':
-      return !Object.hasOwn(data, 'message') && Object.hasOwn(data, 'content')
-    case 'tool/result':
-      return !Object.hasOwn(data, 'message') && Object.hasOwn(data, 'callId')
-    default:
-      return false
-  }
-}
-
-/** Upgrade the removed steering surface event into its current user-message equivalent. */
-function migrateLegacySteeringEvent(event: SessionEvent, id: SessionId): SessionEvent {
-  const legacyType: string = 'steering/message'
-  if (event.type !== legacyType) return event
-  const data = asRecord(event.data)
-  if (data === undefined) {
-    throw new Error(`session "${id}" contains malformed pre-react-loop steering/message at seq ${event.seq}`)
-  }
-  const wrapped = asRecord(data['message'])
-  if (wrapped !== undefined && Number.isSafeInteger(data['turn'])
-    && hasOnlyKeys(data, ['turn', 'message'])) {
-    return { ...event, type: 'user/message', data: wrapped } as SessionEvent
-  }
-  if (!Number.isSafeInteger(data['turn']) || !hasOnlyKeys(data, ['turn', 'content', 'source'])) {
-    throw new Error(`session "${id}" contains malformed pre-react-loop steering/message at seq ${event.seq}`)
-  }
-  const { turn: _turn, ...message } = data
-  return {
-    ...event,
-    type: 'user/message',
-    data: {
-      ...message,
-      id: legacyMessageId(id, event.seq),
-      role: 'user',
-    },
-  } as SessionEvent
-}
-
-/** Remove the obsolete trigger after verifying the complete old turn-start envelope. */
-function migrateLegacyTurnStartEvent(event: SessionEvent, id: SessionId): SessionEvent {
-  if (event.type !== 'turn/start') return event
-  const data = asRecord(event.data)
-  if (data === undefined || !Object.hasOwn(data, 'trigger')) return event
-  const trigger = asRecord(data['trigger'])
-  if (!Number.isSafeInteger(data['turn']) || (data['turn'] as number) < 1
-    || !hasOnlyKeys(data, ['turn', 'trigger'])
-    || trigger === undefined || typeof trigger['kind'] !== 'string' || trigger['kind'].length === 0) {
-    throw new Error(`session "${id}" contains malformed pre-react-loop turn/start at seq ${event.seq}`)
-  }
-  return { ...event, data: { turn: data['turn'] } } as SessionEvent
-}
-
-/** Upgrade an obsolete turn ending while preserving the latest-master envelope. */
-function migrateLegacyTurnEndEvent(event: SessionEvent, id: SessionId): SessionEvent {
-  if (event.type !== 'turn/end') return event
-  const data = asRecord(event.data)
-  /* v8 ignore next -- a non-record current envelope cannot match a legacy shape. */
-  if (data === undefined) return event
-  const malformed = (): never => {
-    throw new Error(`session "${id}" contains malformed pre-react-loop turn/end at seq ${event.seq}`)
-  }
-  const reason = asRecord(data['reason'])
-  if (!Number.isSafeInteger(data['turn']) || (data['turn'] as number) < 1
-    || !hasOnlyKeys(data, ['turn', 'reason'])
-    || reason === undefined || typeof reason['kind'] !== 'string') return malformed()
-
-  let currentReason: Record<string, unknown> | undefined
-  switch (reason['kind']) {
-    case 'completed':
-    case 'blocked':
-    case 'max-tokens':
-    case 'interrupted':
-      if (!hasOnlyKeys(reason, ['kind'])) return malformed()
-      return event
-    case 'aborted':
-      if (Object.hasOwn(reason, 'reason')) return event
-      if (!hasOnlyKeys(reason, ['kind'])) return malformed()
-      currentReason = { kind: 'aborted', reason: { kind: 'legacy' } }
-      break
-    case 'disposed':
-      if (!hasOnlyKeys(reason, ['kind'])) return malformed()
-      currentReason = { kind: 'aborted', reason: { kind: 'disposed' } }
-      break
-    case 'error': {
-      if (Object.hasOwn(reason, 'error')) return event
-      if (!Number.isSafeInteger(reason['step']) || (reason['step'] as number) < 0) return malformed()
-      const failure = asRecord(reason['failure'])
-      if (failure !== undefined && hasOnlyKeys(reason, ['kind', 'step', 'failure'])
-        && hasOnlyKeys(failure, ['message', 'code'], ['status', 'providerRetryAfterMs', 'requestId'])
-        && typeof failure['message'] === 'string' && typeof failure['code'] === 'string'
-        && (failure['status'] === undefined || typeof failure['status'] === 'number')
-        && (failure['providerRetryAfterMs'] === undefined || typeof failure['providerRetryAfterMs'] === 'number')
-        && (failure['requestId'] === undefined || typeof failure['requestId'] === 'string')) {
-        currentReason = { kind: 'error', error: failure }
-        break
-      }
-      const messageKeys = reason['code'] === undefined
-        ? ['kind', 'step', 'message']
-        : ['kind', 'step', 'message', 'code']
-      if (!hasOnlyKeys(reason, messageKeys)
-        || typeof reason['message'] !== 'string'
-        || (reason['code'] !== undefined && typeof reason['code'] !== 'string')) return malformed()
-      currentReason = {
-        kind: 'error',
-        error: {
-          message: reason['message'],
-          code: typeof reason['code'] === 'string' ? reason['code'] : 'UNKNOWN',
-        },
-      }
-      break
-    }
-    default:
-      return event
-  }
-
-  return {
-    ...event,
-    data: {
-      ...data,
-      reason: currentReason,
-    },
-  } as SessionEvent
-}
-
-/**
- * Upgrade one pre-identity message event into the current wrapper shape.
- * Current-looking malformed events remain untouched so validation rejects them
- * instead of disguising corruption as legacy data.
- */
-function migrateLegacyMessageEvent(
-  event: SessionEvent,
-  id: SessionId,
-  messageIds: ReadonlyMap<SessionSeqType, PersistedMessageId>,
-): SessionEvent {
-  const data = asRecord(event.data)
-  if (data === undefined) return event
-  switch (event.type) {
-    case 'user/message': {
-      if (Object.hasOwn(data, 'id') || Object.hasOwn(data, 'role')
-        || Object.hasOwn(data, 'message')
-        || !Object.hasOwn(data, 'content') || !Object.hasOwn(data, 'source')) return event
-      return {
-        ...event,
-        data: {
-          ...data,
-          id: legacyMessageId(id, event.seq),
-          role: 'user',
-        },
-      } as SessionEvent
-    }
-    case 'assistant/message': {
-      if (Object.hasOwn(data, 'message')
-        || !Object.hasOwn(data, 'content') || !Object.hasOwn(data, 'provenance')) return event
-      const { content, provenance, ...eventData } = data
-      return {
-        ...event,
-        data: {
-          ...eventData,
-          message: {
-            id: legacyMessageId(id, event.seq),
-            role: 'assistant',
-            content,
-            source: {
-              ...asRecord(provenance),
-              kind: 'model',
-            },
-          },
-        },
-      } as SessionEvent
-    }
-    case 'tool/result': {
-      if (Object.hasOwn(data, 'message')
-        || !Object.hasOwn(data, 'callId') || !Object.hasOwn(data, 'content')
-        || !Object.hasOwn(data, 'isError')) return event
-      const { callId, content, isError, ...eventData } = data
-      const inheritedId = replacementStart(event)
-      return {
-        ...event,
-        data: {
-          ...eventData,
-          message: {
-            id: inheritedId === undefined
-              ? legacyMessageId(id, event.seq)
-              : messageIds.get(inheritedId),
-            role: 'user',
-            content: [{
-              type: 'tool-result',
-              toolCallId: callId,
-              content,
-              isError,
-            }],
-            source: {
-              kind: 'tool',
-              callId,
-            },
-          },
-        },
-      } as SessionEvent
-    }
-    default:
-      return event
-  }
-}
-
-/** Read the identified message carried by one validated current event. */
-function eventMessageId(event: SessionEvent): PersistedMessageId | undefined {
-  const data = asRecord(event.data)
-  const message = event.type === 'user/message' ? data : asRecord(data?.['message'])
-  return typeof message?.['id'] === 'string' ? message['id'] as PersistedMessageId : undefined
-}
-
-/** Materialize stored events as upgraded, validated snapshots with immutable messages. */
-function snapshotStoredEvents(events: readonly SessionEvent[], id: SessionId): SessionEvent[] {
-  assertSupportedEvents(events, id)
-  const messageIds = new Map<SessionSeqType, PersistedMessageId>()
-  return events.map((event) => {
-    const migratedStart = migrateLegacyTurnStartEvent(event, id)
-    const migratedTurn = migrateLegacyTurnEndEvent(migratedStart, id)
-    const migratedSteering = migrateLegacySteeringEvent(migratedTurn, id)
-    const snapshot = snapshotSessionEvent(migrateLegacyMessageEvent(migratedSteering, id, messageIds))
-    const messageId = eventMessageId(snapshot)
-    if (messageId !== undefined) messageIds.set(snapshot.seq, messageId)
-    return snapshot
-  })
-}
-
-/** Upgrade and validate an exclusively owned backend result without copying it. */
-function adoptStoredEvents(events: SessionEvent[], id: SessionId): SessionEvent[] {
-  assertSupportedEvents(events, id)
-  const messageIds = new Map<SessionSeqType, PersistedMessageId>()
-  for (const [index, event] of events.entries()) {
-    const migratedStart = migrateLegacyTurnStartEvent(event, id)
-    const migratedTurn = migrateLegacyTurnEndEvent(migratedStart, id)
-    const migratedSteering = migrateLegacySteeringEvent(migratedTurn, id)
-    const adopted = adoptSessionEvent(migrateLegacyMessageEvent(migratedSteering, id, messageIds))
-    events[index] = adopted
-    const messageId = eventMessageId(adopted)
-    if (messageId !== undefined) messageIds.set(adopted.seq, messageId)
-  }
-  return events
-}
-
-/**
- * Owns the backend-agnostic session write-path orchestration. A backend
- * constructs one (`new PersistenceCoordinator(ctx, this)`), implements
- * {@link PersistenceBackend}, and delegates its write/read service methods to
- * the matching coordinator methods.
- *
- * All per-id operations are serialized (a per-id promise chain) so concurrent
- * flushes / a flush racing a load never interleave storage writes. The
- * constructor installs the write-path listeners, per-session retirement, and
- * the backend dispose effect.
- *
- * @typeParam TornMarker - the backend's opaque torn-tail repair token.
- */
-export class PersistenceCoordinator<TornMarker = unknown> {
-  /** Backend bookkeeping keyed by session id (NOT the live Session object). */
-  private states = new Map<SessionId, SessionState>()
-  /** Lifecycle and write-behind state keyed by the exact live Session. */
-  private live = new Map<Session, LiveSessionState>()
-  /** Exact disposed lifecycles whose buffered tail is still draining. */
-  private retirements = new Map<SessionId, Promise<void>>()
-  /** Shared cold reads, unpublished reservations, and completed LRU entries. */
-  private readonly preparations: SessionPreparations<PreparedSessionSource<TornMarker>, SessionState>
-  /**
-   * Per-session serialization: every operation chains onto the prior one for the
-   * same id, so writes for one session never interleave. Keyed by session id.
-   */
-  private chains = new Map<SessionId, Promise<unknown>>()
-  /** Resolved fixed write-batching window shared by per-session controllers. */
-  private readonly writeBatchMaxDelayMs: number
-
-  constructor(
-    private ctx: Context,
-    private backend: PersistenceBackend<TornMarker>,
-    options: PersistenceCoordinatorOptions = {
-      preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
-      writeBatchMaxDelayMs: DEFAULT_WRITE_BATCH_MAX_DELAY_MS,
-    },
-  ) {
-    if (!Number.isSafeInteger(options.preparedSessionCacheSize)
-      || options.preparedSessionCacheSize < 1) {
-      throw new TypeError('preparedSessionCacheSize must be a positive safe integer')
-    }
-    if (!Number.isSafeInteger(options.writeBatchMaxDelayMs)
-      || options.writeBatchMaxDelayMs < 1
-      || options.writeBatchMaxDelayMs > MAX_WRITE_BATCH_DELAY_MS) {
-      throw new TypeError(`writeBatchMaxDelayMs must be an integer between 1 and ${MAX_WRITE_BATCH_DELAY_MS}`)
-    }
-    this.writeBatchMaxDelayMs = options.writeBatchMaxDelayMs
-    this.preparations = new SessionPreparations(options.preparedSessionCacheSize)
-    this.installWritePath()
-  }
-
-  // --- Public API (the backend's service methods delegate here) ---
-
-  /**
-   * Register detached session metadata for lazy creation on the first append.
-   * @param meta - header to snapshot; duplicate tracked or persisted ids reject.
-   * @param inheritedEventCount - exact inherited prefix length; required for
-   * a seeded header and omitted only for an unseeded header.
-   */
-  create(meta: SessionHeader, inheritedEventCount?: SessionLogOffsetType): Promise<void> {
-    // Snapshot before queueing so caller mutation cannot diverge the key and header.
-    const snapshot = snapshotJsonValue(meta)
-    if (snapshot === undefined) {
-      return Promise.reject(new TypeError('session metadata must be losslessly JSON-serializable'))
-    }
-    if (!Number.isSafeInteger(snapshot.createdAt) || snapshot.createdAt < 0) {
-      return Promise.reject(new TypeError('session metadata createdAt must be a non-negative safe integer'))
-    }
-    let storage: SessionStorageMetadata
-    try {
-      storage = storageMetadata(snapshot, inheritedEventCount)
-    } catch (error: unknown) {
-      /* v8 ignore next -- Session storage validation only throws Error instances. */
-      return Promise.reject(error instanceof Error
-        ? error
-        : new TypeError('invalid session storage metadata', { cause: error }))
-    }
-    return this.serialize(snapshot.id, () => this.createCore(storage))
-  }
-
-  /**
-   * Materialize one exact live session without inventing a session event.
-   * @param session - live session already registered through the write path.
-   */
-  async ensureMaterialized(session: Session): Promise<void> {
-    await this.flush(session)
-    await this.serialize(session.id, async () => {
-      const state = this.states.get(session.id)
-      /* v8 ignore next -- successful live flush always initializes the exact session state. */
-      if (state === undefined) throw new Error(`session "${session.id}" is not registered for persistence`)
-      if (state.materialized) return
-      if (this.backend.materializeHeader === undefined) {
-        throw new Error('session persistence backend cannot materialize an empty session')
-      }
-      await this.backend.materializeHeader(state.storage)
-      state.materialized = true
-      this.preparations.invalidate(session.id)
-    })
-  }
-
-  private async createCore(storage: SessionStorageMetadata): Promise<void> {
-    const { meta } = storage
-    // Do NOT clobber an existing session: the SessionId IS the identity.
-    if (this.states.has(meta.id) || this.preparations.has(meta.id)) {
-      throw new Error(`session "${meta.id}" already exists in this backend`)
-    }
-    // A persisted artifact under this id (in ANY scope) blocks creation: load/
-    // resume identify a session by id alone, so a second artifact would make
-    // resume nondeterministic.
-    if (await this.backend.loadStored(meta.id) !== undefined) {
-      throw new Error(`session "${meta.id}" already has a persisted log on disk; load/resume it instead of creating`)
-    }
-    // Pure lazy: record intent only. No artifact until the first append.
-    this.states.set(meta.id, {
-      storage,
-      cursor: SessionLogOffset(0),
-      materialized: false,
-    })
-  }
-
-  // `async` so synchronous materialization failures below reject (not throw) per
-  // the Promise<void> contract — callers use `await expect(...).rejects`.
-  /**
-   * Durably persist a batch of events. Honors the append-only and contiguous-seq
-   * contracts; rejects non-JSON-serializable `event.data`.
-   * @param id - the session the batch belongs to.
-   * @param events - the contiguous batch to persist, in seq order; materialized
-   *   as a detached lossless-JSON snapshot at call time.
-   */
-  async append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
-    // Validate and deep-snapshot the complete batch HERE, in one traversal,
-    // before the op waits behind the per-session chain. A check followed by
-    // structuredClone would reread accessors and could sanitize an exotic value
-    // into an apparently valid record; the single-pass materializer makes the
-    // checked value exactly the value persisted.
-    const batch = snapshotJsonValue(events)
-    if (batch === undefined) {
-      throw new TypeError('session event batch is not losslessly JSON-serializable because it contains non-JSON-serializable data')
-    }
-    return this.serialize(id, () => this.appendCore(id, batch))
-  }
-
-  private async appendCore(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
-    // Every append route converges here: the public service, live write-behind
-    // drains, and HMR seed/suffix adoption. Legacy-shape rejection stays at
-    // this shared boundary so a stale JavaScript plugin cannot persist a
-    // retired shape this backend refuses to load. The unknown-type guard is
-    // deliberately read-side only: an append-time refusal would stall a live
-    // session's durability mid-flight, which costs more than a loud refusal at
-    // the log's next load (trade-off owned by the session-log-version-mechanism
-    // Agent Note).
-    assertSupportedEvents(events, id)
-    if (events.length === 0) return
-    this.preparations.assertWritable(id)
-    let state = this.states.get(id)
-    if (state === undefined) state = await this.adopt(id)
-
-    // Contiguity contract: each event's seq must continue the stored log.
-    for (const [i, event] of events.entries()) {
-      if (event.seq !== state.cursor + i) {
-        throw new Error(`append seq mismatch for "${id}": expected ${state.cursor + i} at index ${i}, got ${event.seq}`)
-      }
-    }
-
-    const nextCursor = SessionLogOffset(state.cursor + events.length)
-    if (!state.materialized && nextCursor < state.storage.inheritedEventCount) {
-      throw new Error(`session "${id}" cannot materialize before its inherited prefix is complete`)
-    }
-
-    await this.backend.appendBatch(state.storage, events, state.materialized)
-    // The durable write is the transaction: mark materialized + advance the
-    // cursor as soon as it commits (uniform across backends).
-    state.materialized = true
-    state.cursor = nextCursor
-    this.preparations.invalidate(id)
-  }
-
-  /**
-   * Prepare and reserve the exact unpublished Session used by resume.
-   * Revision retries converge once the durable log remains unchanged for one
-   * read/check round trip; continuous external writers may delay completion.
-   * @param id - persisted session to prepare.
-   * @param signal - optional cancellation for reading and repair.
-   * @returns an owned preparation released after publication or rollback.
-   */
-  async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation> {
-    for (;;) {
-      await this.waitForRetirement(id, signal)
-      if (this.ctx.sessions.get(id) !== undefined) {
-        throw new Error(`cannot prepare session "${id}" while it is live`)
-      }
-      const reservation = await this.preparations.reserve(
-        id,
-        () => this.serialize(id, () => this.prepareCore(id)),
-        source => this.serialize(id, () => this.commitPrepared(source), signal),
-        signal,
-      )
-      if (reservation === undefined) continue
-      if (this.ctx.sessions.get(id) !== undefined) {
-        this.preparations.release(reservation, false)
-        throw new Error(`cannot prepare session "${id}" while it is live`)
-      }
-      return SessionPreparation.create(reservation.source.session, {
-        release: () => {
-          this.preparations.release(
-            reservation,
-            reservation.state.owner === undefined
-              && reservation.source.session.seq === reservation.source.sessionLength,
-          )
-        },
-      })
-    }
-  }
-
-  /**
-   * Commit recovery and return its immutable logical view without publication.
-   * Revision retries converge once the durable log remains unchanged for one
-   * read/check round trip; continuous external writers may delay completion.
-   * @param id - persisted session to load.
-   * @returns prepared header and balanced events.
-   */
-  async load(id: SessionId): Promise<SessionInspection> {
-    for (;;) {
-      await this.waitForRetirement(id)
-      const live = this.ctx.sessions.get(id)
-      if (live !== undefined) return this.loadLiveSnapshot(live)
-      const reservation = await this.preparations.reserve(
-        id,
-        () => this.serialize(id, () => this.prepareCore(id)),
-        source => this.serialize(id, () => this.commitPrepared(source)),
-      )
-      if (reservation === undefined) continue
-      const attached = this.ctx.sessions.get(id)
-      if (attached !== undefined) {
-        this.preparations.discard(reservation)
-        return this.loadLiveSnapshot(attached)
-      }
-      this.preparations.discard(reservation)
-      return reservation.source.inspection
-    }
-  }
-
-  /**
-   * Inspect a logical session without publishing it or committing recovery.
-   * A stale ready source is reloaded. A source already committing or reserved
-   * for resume remains exclusive, and inspection may borrow its immutable view.
-   * Revision retries converge once the log is stable for one read/check round
-   * trip; continuous external writers may delay completion.
-   * @param id - persisted session to inspect.
-   * @param signal - optional cancellation for preparation work.
-   * @returns immutable prepared metadata and events; a live view may have an open turn.
-   */
-  async inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection> {
-    for (;;) {
-      signal?.throwIfAborted()
-      if (this.retirements.has(id)) await this.waitForRetirement(id, signal)
-      const live = this.ctx.sessions.get(id)
-      if (live !== undefined) return this.inspectLive(live)
-      try {
-        const source = await this.preparations.inspect(
-          id,
-          () => this.serialize(id, () => this.prepareCore(id)),
-          signal,
-        )
-        const attached = this.ctx.sessions.get(id)
-        if (attached !== undefined) return this.inspectLive(attached)
-        const current = await this.serialize(
-          id,
-          () => this.isPreparedSourceCurrent(source, signal),
-          signal,
-        )
-        const published = this.ctx.sessions.get(id)
-        if (published !== undefined) return this.inspectLive(published)
-        if (current) return source.inspection
-        if (this.preparations.discardReady(id, source) === 'retained') {
-          return source.inspection
-        }
-      } catch (error: unknown) {
-        signal?.throwIfAborted()
-        const attached = this.ctx.sessions.get(id)
-        if (attached !== undefined) return this.inspectLive(attached)
-        throw error
-      }
-    }
-  }
-
-  /**
-   * Borrow one exact logical view while pinning its reusable prepared Session.
-   * @param id - persisted session to observe.
-   * @param signal - optional cancellation for preparation work.
-   * @returns a disposable observation retaining the prepared source.
-   */
-  async borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource> {
-    for (;;) {
-      signal?.throwIfAborted()
-      if (this.retirements.has(id)) await this.waitForRetirement(id, signal)
-      const live = this.ctx.sessions.get(id)
-      if (live !== undefined) {
-        return { source: 'live', inspection: this.inspectLive(live), [Symbol.dispose]: () => {} }
-      }
-      const observation = await this.preparations.borrow(
-        id,
-        () => this.serialize(id, () => this.prepareCore(id)),
-        signal,
-      )
-      const source = observation.source
-      try {
-        const attached = this.ctx.sessions.get(id)
-        if (attached !== undefined) {
-          observation[Symbol.dispose]()
-          return { source: 'live', inspection: this.inspectLive(attached), [Symbol.dispose]: () => {} }
-        }
-        const current = await this.serialize(
-          id,
-          () => this.isPreparedSourceCurrent(source, signal),
-          signal,
-        )
-        const published = this.ctx.sessions.get(id)
-        if (published !== undefined) {
-          observation[Symbol.dispose]()
-          return { source: 'live', inspection: this.inspectLive(published), [Symbol.dispose]: () => {} }
-        }
-        if (current || this.preparations.discardReady(id, source) === 'retained') {
-          return {
-            source: 'prepared',
-            inspection: source.inspection,
-            revision: source.revision,
-            preparedSession: source.session,
-            [Symbol.dispose]: () => { observation[Symbol.dispose]() },
-          }
-        }
-      } catch (error: unknown) {
-        observation[Symbol.dispose]()
-        signal?.throwIfAborted()
-        const attached = this.ctx.sessions.get(id)
-        if (attached !== undefined) {
-          return { source: 'live', inspection: this.inspectLive(attached), [Symbol.dispose]: () => {} }
-        }
-        throw error
-      }
-      observation[Symbol.dispose]()
-    }
-  }
-
-  /**
-   * Read the stored events from `fromSeq` onward, detached and non-mutating
-   * (the read-from-seq primitive behind the service's `readFrom`). Runs on
-   * the same per-id chain as writes; a backend with the seek-capable
-   * {@link PersistenceBackend.loadStoredFrom} hook reads only the suffix,
-   * every other backend reads its stored prefix and skips forward here.
-   * @param id - persisted session to read.
-   * @param fromSeq - first event seq to include; a non-negative safe integer.
-   * @param signal - optional cancellation for queued and backend read work.
-   * @returns stored metadata, the requested offset, and valid events with `seq >= fromSeq`.
-   */
-  readFrom(
-    id: SessionId,
-    fromSeq: SessionLogOffsetType,
-    signal?: AbortSignal,
-  ): Promise<SessionEventSuffix> {
-    try {
-      SessionLogOffset(fromSeq)
-    } catch (error: unknown) {
-      /* v8 ignore next -- Session log-offset validation only throws Error instances. */
-      return Promise.reject(error instanceof Error
-        ? error
-        : new TypeError('invalid session read offset', { cause: error }))
-    }
-    const retired = Promise.resolve(this.retirements.get(id))
-    const waited = signal === undefined ? retired : observeQueuedAbort(retired, signal, () => false)
-    return waited.then(() => this.serialize(id, () => this.readFromCore(id, fromSeq, signal), signal))
-  }
-
-  private async readFromCore(
-    id: SessionId,
-    fromSeq: SessionLogOffsetType,
-    signal?: AbortSignal,
-  ): Promise<SessionEventSuffix> {
-    signal?.throwIfAborted()
-    if (this.backend.loadStoredFrom !== undefined) {
-      let suffix: StoredSuffix | undefined
-      try {
-        suffix = await this.backend.loadStoredFrom(id, fromSeq, signal)
-      } catch (error: unknown) {
-        if (signal?.aborted) signal.throwIfAborted()
-        throw error
-      }
-      signal?.throwIfAborted()
-      if (suffix === undefined) throw new SessionPersistenceNotFoundError(id)
-      this.assertStoredId(id, suffix.meta)
-      this.assertVersion(suffix.meta)
-      if (suffix.events.some(needsLegacyPrefix)) {
-        const whole = await this.readStoredPrefix(id, signal)
-        return {
-          meta: whole.meta,
-          inheritedEventCount: whole.inheritedEventCount,
-          fromSeq,
-          events: whole.events.filter(event => event.seq >= fromSeq),
-        }
-      }
-      const events = snapshotStoredEvents(suffix.events, id)
-      this.assertEventsSupported(suffix.meta, events)
-      return {
-        meta: structuredClone(suffix.meta),
-        inheritedEventCount: SessionLogOffset(suffix.inheritedEventCount),
-        fromSeq,
-        events,
-      }
-    }
-    const whole = await this.readStoredPrefix(id, signal)
-    // Sequential fallback: contiguous seqs from 0 make the suffix an index slice.
-    return {
-      meta: whole.meta,
-      inheritedEventCount: whole.inheritedEventCount,
-      fromSeq,
-      events: whole.events.slice(fromSeq),
-    }
-  }
-
-  /** Read one detached physical prefix without logical recovery or caching. */
-  private async readStoredPrefix(
-    id: SessionId,
-    signal?: AbortSignal,
-  ): Promise<SessionInspection> {
-    signal?.throwIfAborted()
-    const stored = await this.backend.loadStored(id, signal)
-    signal?.throwIfAborted()
-    if (stored === undefined) throw new SessionPersistenceNotFoundError(id)
-    this.assertStoredId(id, stored.meta)
-    this.assertVersion(stored.meta)
-    const events = snapshotStoredEvents(stored.events, id)
-    this.assertEventsSupported(stored.meta, events)
-    return {
-      meta: structuredClone(stored.meta),
-      inheritedEventCount: SessionLogOffset(stored.inheritedEventCount),
-      events,
-    }
-  }
-
-  /** Read, repair in memory, validate, and freeze one cold source once. */
-  private async prepareCore(id: SessionId): Promise<PreparedSessionSource<TornMarker>> {
-    const stored = await this.backend.loadStored(id)
-    if (stored === undefined) throw new SessionPersistenceNotFoundError(id)
-    try {
-      const { meta, inheritedEventCount, events, revision, tornMarker } = stored
-      this.assertStoredId(id, meta)
-      this.assertVersion(meta)
-      const storedEvents = adoptStoredEvents(events, id)
-      this.assertEventsSupported(meta, storedEvents)
-      if (inheritedEventCount > storedEvents.length) {
-        throw new Error(`session "${id}" inherited event count exceeds its stored event count`)
-      }
-
-      // Preserve complete interrupted events and synthesize only missing closers.
-      const closers = interruptedTurnClosers(storedEvents).map(adoptSessionEvent)
-      const balanced = [...storedEvents, ...closers]
-      const session = this.ctx.sessions.prepare(id, {
-        seed: balanced,
-        meta,
-        inheritedEventCount,
-        seedSource: 'persistence',
-      })
-      const inspection: SessionInspection = Object.freeze({
-        meta: session.header,
-        inheritedEventCount: session.inheritedEventCount,
-        events: Object.freeze(balanced),
-      })
-      return {
-        inspection,
-        session,
-        revision,
-        sessionLength: session.seq,
-        tornMarker,
-        closers,
-      }
-    } catch (error: unknown) {
-      // An unsupported format is a refusal over an intact log, not damage —
-      // surface it unwrapped so callers can point at the raw artifact.
-      if (error instanceof SessionFormatUnsupportedError) throw error
-      throw new SessionPersistenceCorruptionError(
-        `stored session "${id}" failed validation: ${String(error)}`,
-        { cause: error },
-      )
-    }
-  }
-
-  /** Commit one prepared repair and establish its ownerless durable cursor. */
-  private async commitPrepared(
-    source: PreparedSessionSource<TornMarker>,
-  ): Promise<{ source: PreparedSessionSource<TornMarker>; state: SessionState } | undefined> {
-    const id = source.inspection.meta.id
-    const cursor = SessionLogOffset(source.inspection.events.length)
-    const existing = this.states.get(id)
-    if (existing?.owner !== undefined) {
-      throw new Error(`session "${id}" already has a live persistence owner`)
-    }
-    if (!await this.isPreparedSourceCurrent(source)) return undefined
-    if (source.tornMarker !== undefined || source.closers.length > 0) {
-      await this.backend.commitRepair(source.inspection, source.tornMarker, source.closers)
-      // The repair changed the durable revision. Reload the exact committed
-      // graph instead of associating the old in-memory view with a newer revision.
-      return undefined
-    }
-    const state = existing ?? {
-      storage: source.inspection,
-      cursor,
-      materialized: true,
-    }
-    state.storage = source.inspection
-    state.cursor = cursor
-    state.materialized = true
-    this.states.set(id, state)
-    return {
-      source,
-      state,
-    }
-  }
-
-  /** Whether one cached source still names the current durable log revision. */
-  private async isPreparedSourceCurrent(
-    source: PreparedSessionSource<TornMarker>,
-    signal?: AbortSignal,
-  ): Promise<boolean> {
-    return await this.backend.readStoredRevision(source.inspection.meta.id, signal) === source.revision
-  }
-
-  /** Return one durable immutable view of an already-live Session. */
-  private async loadLiveSnapshot(session: Session): Promise<SessionInspection> {
-    const events = session.snapshotEvents()
-    await this.flush(session)
-    const state = this.states.get(session.id)
-    /* v8 ignore next -- successful flush always publishes this live session's durable state */
-    if (state === undefined) throw new Error(`session "${session.id}" lost persistence state during load`)
-    if (events.length === 0 && !state.materialized) throw new Error(`session "${session.id}" not found`)
-    if (interruptedTurnClosers(events).length > 0) {
-      throw new Error(`cannot load session "${session.id}" while its live turn is open; use the live Session or wait for the turn to close`)
-    }
-    return Object.freeze({
-      meta: state.storage.meta,
-      inheritedEventCount: state.storage.inheritedEventCount,
-      events,
-    })
-  }
-
-  /** Borrow one immutable view from an already-live Session. */
-  private inspectLive(session: Session): SessionInspection {
-    return Object.freeze({
-      meta: session.header,
-      inheritedEventCount: session.inheritedEventCount,
-      events: session.snapshotEvents(),
-    })
-  }
-
-  /** Await one retiring lifecycle with caller cancellation. */
-  private waitForRetirement(id: SessionId, signal?: AbortSignal): Promise<void> {
-    const retired = Promise.resolve(this.retirements.get(id))
-    return signal === undefined
-      ? retired
-      : observeQueuedAbort(retired, signal, () => false)
-  }
-
-  // Listing is a direct backend read and needs no coordinator state.
-
-  // --- per-id serialization + adoption helpers ---
-
-  /**
-   * Run `op` after any in-flight operation for the same session id, so writes for
-   * one session never interleave. Errors do not poison the chain. NOTE: serialized
-   * public methods must NOT call each other (deadlock); they call the unserialized
-   * `*Core` helpers instead.
-   */
-  private serialize<T>(
-    id: SessionId,
-    op: () => Promise<T> | T,
-    signal?: AbortSignal,
-  ): Promise<T> {
-    const prior = this.chains.get(id) ?? Promise.resolve()
-    let started = false
-    const run = (): Promise<T> | T => {
-      signal?.throwIfAborted()
-      started = true
-      return op()
-    }
-    const next = prior.then(run, run)
-    // Keep the chain alive but swallow this op's rejection for the NEXT waiter
-    // (the caller still sees the real rejection via `next`).
-    const tail = next.then(() => undefined, () => undefined)
-    this.chains.set(id, tail)
-    // Settled tails carry no serialization value. Delete only the exact tail
-    // installed above: a later operation may already have replaced it.
-    void tail.then(() => {
-      if (this.chains.get(id) === tail) this.chains.delete(id)
-    })
-    return signal === undefined ? next : observeQueuedAbort(next, signal, () => started)
-  }
-
-  /** Build a state for a session discovered in storage but not yet in memory. */
-  private async adopt(id: SessionId): Promise<SessionState> {
-    // This runs inside the id's serialization chain, so it uses core helpers
-    // instead of re-entering through public prepare/load methods.
-    for (;;) {
-      const source = this.preparations.takeReady(id) ?? await this.prepareCore(id)
-      const committed = await this.commitPrepared(source)
-      if (committed !== undefined) return committed.state
-    }
-  }
-
-  private assertVersion(meta: SessionHeader): void {
-    if (meta.version === SESSION_FORMAT_VERSION) return
-    throw this.unsupported(meta, sessionFormatVersionRefusal(meta.id, meta.version))
-  }
-
-  /**
-   * Refuse a log containing an event type this build does not know, unless the
-   * writer marked the event ignorable: an unrecognized required event may
-   * change how the rest of the log must be interpreted, so silently skipping
-   * it would reconstruct a wrong session (the envelope contract on
-   * `SessionEvent.ignorable`). Runs on NORMALIZED events — after
-   * `snapshotStoredEvents`/`adoptStoredEvents` has upgraded the legacy shapes
-   * this build still reads and rejected the ones it does not, so those keep
-   * their specific diagnostics.
-   */
-  private assertEventsSupported(meta: SessionHeader, events: readonly SessionEvent[]): void {
-    for (const event of events) {
-      if (KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true) continue
-      throw this.unsupported(meta, `session "${meta.id}" contains event type "${event.type}" (seq ${event.seq}) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness`)
-    }
-  }
-
-  /** Build a format refusal that points at the raw artifact when the backend has one. */
-  private unsupported(meta: SessionHeader, reason: string): SessionFormatUnsupportedError {
-    const location = this.backend.locate?.(meta)
-    return new SessionFormatUnsupportedError(
-      location === undefined ? reason : `${reason} (raw log: ${location.path})`,
-      location,
-    )
-  }
-
-  /** Reject backend metadata that is not bound to the requested session id. */
-  private assertStoredId(id: SessionId, meta: SessionHeader): void {
-    if (meta.id !== id) {
-      throw new Error(`stored session identity mismatch: requested "${id}", header contains "${meta.id}"`)
-    }
-  }
-
-  // --- write path (session/event → flush drain) ---
-
-  private installWritePath(): void {
-    const ctx = this.ctx
-
-    // Register the disposer BEFORE the listeners. Cordis tears effects down in
-    // reverse registration order, so event admission closes before this final
-    // drain reaches quiescence and closes the backend.
-    ctx.effect(() => async () => {
-      let disposeError: unknown
-      try {
-        const errors = await settledErrors([...this.live.keys()].map(session => this.flush(session)))
-        while (this.chains.size > 0) await Promise.allSettled([...this.chains.values()])
-        if (errors.length > 0) {
-          throw new AggregateError(errors, `${this.backend.name} dispose failed`)
-        }
-      } catch (error: unknown) {
-        disposeError = error
-        throw error
-      } finally {
-        try {
-          await this.backend.close?.()
-        } catch (closeError: unknown) {
-          // A close failure can only add teardown context; keep the already-
-          // captured drain AggregateError as the primary failure rather than
-          // masking it. Only surface the close error if the drain succeeded.
-          /* v8 ignore start -- close failure racing disposal is a defensive teardown edge */
-          if (disposeError === undefined) throw closeError
-          /* v8 ignore stop */
-        }
-      }
-    }, `${this.backend.name} write path`)
-
-    // Capture the header on creation and persist a fork's seed once.
-    ctx.on('session/created', (session) => {
-      void this.initFor(session)
-    })
-
-    // Keep a persistence-owned copy of each frozen event and start its bounded window.
-    ctx.on('session/event', (session, event) => {
-      const live = this.initFor(session)
-      live.writes.enqueue(event)
-    })
-
-    // Callers use flush as the immediate durability barrier for buffered writes.
-    ctx.on('session/flush', session => this.flush(session))
-
-    // Session disposal is observe-only, so retirement contains its own failure.
-    ctx.on('session/disposed', (session) => { this.retire(session) })
-
-    // HMR does not replay session/created, so seed existing live sessions.
-    for (const session of ctx.sessions.list()) void this.initFor(session)
-  }
-
-  /** Start and observe one disposed session's final drain. */
-  private retire(session: Session): void {
-    if (!this.live.has(session)) return
-    const retirement = this.retireCore(session)
-    this.retirements.set(session.id, retirement)
-    const forget = (): void => {
-      if (this.retirements.get(session.id) === retirement) this.retirements.delete(session.id)
-    }
-    void retirement.then(forget, forget)
-    void retirement.catch((error: unknown) => {
-      this.ctx.logger.warn(`${this.backend.name}: session "${session.id}" retirement failed: ${String(error)}`)
-    })
-  }
-
-  /** Drain and release state owned by one exact disposed Session lifecycle. */
-  private async retireCore(session: Session): Promise<void> {
-    await this.flush(session)
-    const id = session.header.id
-    await this.serialize(id, () => {
-      this.live.delete(session)
-      if (this.states.get(id)?.owner === session) this.states.delete(id)
-    })
-  }
-
-  /** Return the one lifecycle controller for a live session, creating it if needed. */
-  private initFor(session: Session): LiveSessionState {
-    const existing = this.live.get(session)
-    if (existing) return existing
-    const reservation = this.preparations.reservationFor(session)
-    if (reservation !== undefined) {
-      const restored = this.attachPrepared(session, reservation)
-      this.live.set(session, restored)
-      return restored
-    }
-    // Session owns this stable deep-frozen snapshot; backends only serialize it.
-    const seed = session.snapshotEvents()
-    const live: LiveSessionState = {
-      init: Promise.resolve(),
-      writes: this.createWriteBehind(session, () => live.init),
-    }
-    this.live.set(session, live)
-    live.init = this.serialize(session.header.id, () => this.onCreated(session, seed))
-    live.init.catch(() => { /* observed by flush/dispose through the controller */ })
-    return live
-  }
-
-  /** Bind one exact prepared Session and persist only its unpublished suffix. */
-  private attachPrepared(
-    session: Session,
-    reservation: SessionPreparationReservation<PreparedSessionSource<TornMarker>, SessionState>,
-  ): LiveSessionState {
-    const { source, state } = reservation
-    if (source.session !== session || state.owner !== undefined
-      || state.cursor !== source.inspection.events.length
-      || session.firstLiveSeq !== state.cursor) {
-      throw new Error(`session "${session.id}" preparation no longer matches its persistence state`)
-    }
-    const suffix = session.snapshotEvents(state.cursor).map(event => structuredClone(event))
-    this.preparations.attach(reservation)
-    state.owner = session
-    const live: LiveSessionState = {
-      init: Promise.resolve(),
-      writes: this.createWriteBehind(session, () => live.init),
-    }
-    if (suffix.length > 0) {
-      live.init = this.serialize(session.id, () => this.appendCore(session.id, suffix))
-      live.init.catch(() => { /* observed by flush/dispose through the controller */ })
-    }
-    return live
-  }
-
-  /**
-   * Whether a live session's `seed` reproduces the first `cursor` persisted
-   * events. A `cursor` of 0 (nothing persisted yet) trivially matches. Used when
-   * a live session claims ownerless state left by a prior `load()`/`create()`.
-   */
-  private async seedMatchesPersisted(
-    id: SessionId,
-    seed: readonly SessionEvent[],
-    cursor: SessionLogOffsetType,
-  ): Promise<boolean> {
-    if (cursor === 0) return true
-    const stored = await this.backend.loadStored(id)
-    /* v8 ignore next -- a cursor > 0 means the session was materialized, so it exists */
-    if (stored === undefined) return false
-    this.assertStoredId(id, stored.meta)
-    return seedCoversPrefix(seed, snapshotStoredEvents(stored.events, id).slice(0, cursor))
-  }
-
-  /**
-   * On session/created: sync the backend's in-memory state to a live Session.
-   *
-   * Cases, by whether this backend tracks the id and whether an artifact exists:
-   *   1. Already tracked → no-op (or claim ownerless state if the seed matches,
-   *      or reclaim a truly-abandoned id, else reject as a collision).
-   *   2. Not tracked, an artifact EXISTS at the same cwd and is a seq-aligned
-   *      PREFIX of the live events → ADOPT it, persisting any live suffix.
-   *   3. Not tracked, an artifact EXISTS at another cwd or is NOT a prefix →
-   *      REJECT (collision).
-   *   4. Not tracked and NO artifact → a genuinely new session: register meta
-   *      (lazy) and persist its seed once.
-   */
-  private async onCreated(session: Session, seed: readonly SessionEvent[]): Promise<void> {
-    const id = session.header.id
-    const tracked = this.states.get(id)
-    if (tracked !== undefined) {
-      // case 1: already tracked.
-      /* v8 ignore next -- initFor dedupes per session object; same-object re-entry can't occur */
-      if (tracked.owner === session) return
-      if (tracked.owner === undefined) {
-        // Ownerless state from the public create()/load() API. The FIRST live
-        // session claims it — but ONLY if BOTH the cwd scope and the seed match.
-        // A same-id ownerless artifact at a different cwd is a collision, not a
-        // claim: accepting it would append this live session's events through
-        // the stored header's cwd. The seed guard then ensures the live events
-        // reproduce the persisted prefix; otherwise a fresh session reusing the
-        // id could have its leading events filtered as already written.
-        if (tracked.storage.meta.cwd !== session.header.cwd) {
-          throw new Error(`session "${id}" is already persisted at a different cwd (persisted: ${String(tracked.storage.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
-        }
-        if (tracked.storage.inheritedEventCount !== session.inheritedEventCount) {
-          throw new Error(`session "${id}" is already persisted with a different inherited event count (id collision)`)
-        }
-        if (!await this.seedMatchesPersisted(id, seed, tracked.cursor)) {
-          throw new Error(`session "${id}" is already persisted with ${tracked.cursor} event(s) that do not match this live session (id collision)`)
-        }
-        tracked.owner = session
-        // Persist the seed SUFFIX beyond the persisted prefix. Constructor seed
-        // events never emit session/event, so the buffer never sees them.
-        const suffix = seed.slice(tracked.cursor)
-        if (suffix.length > 0) await this.appendCore(id, suffix)
-        return
-      }
-      const owner = this.live.get(tracked.owner)
-      if (!tracked.materialized && !owner?.writes.hasWork) {
-        this.states.delete(id)
-      } else {
-        throw new Error(`session "${id}" is already bound to a different live session in this backend (id collision)`)
-      }
-    }
-
-    // case 2/3: resolve the id once across storage, then let adoption reject a
-    // cwd mismatch before repair or state publication.
-    const live = await this.backend.loadStored(id)
-    if (live !== undefined) {
-      // Do NOT route through cold preparation: that crash-repairs open turns as
-      // interrupted, which is wrong for HMR while the live Session is still the
-      // authority and may append the real step/turn end later.
-      await this.adoptLivePrefix(session, seed, live)
-      return
-    }
-
-    // case 4: a genuinely new session. Register its meta (lazy), then persist its
-    // seed (events present at creation time) once.
-    const storage = sessionStorageMetadata(session)
-    await this.createCore({
-      meta: { ...storage.meta },
-      inheritedEventCount: storage.inheritedEventCount,
-    })
-    // Bind this state to the live session so a later DIFFERENT session reusing
-    // the id is detected as a collision (case 1) rather than silently no-opped.
-    const created = this.states.get(id)
-    /* v8 ignore next -- create() always sets the state for the id */
-    if (created !== undefined) created.owner = session
-    if (seed.length > 0) await this.appendCore(id, seed)
-  }
-
-  /**
-   * Adopt a stored prefix as a live session's history (HMR/reload): verify the
-   * seed covers the stored prefix, truncate any torn tail (NOT the open turn —
-   * the live Session is still the authority), bind ownership, and persist the
-   * live suffix that was ahead of the stored prefix.
-   */
-  private async adoptLivePrefix(session: Session, seed: readonly SessionEvent[], stored: StoredPrefix<TornMarker>): Promise<void> {
-    const { meta, inheritedEventCount, events, tornMarker } = stored
-    this.assertStoredId(session.header.id, meta)
-    if (meta.cwd !== session.header.cwd) {
-      throw new Error(`session "${session.header.id}" is already persisted at a different cwd (persisted: ${String(meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
-    }
-    if (inheritedEventCount !== session.inheritedEventCount) {
-      throw new Error(`session "${session.header.id}" is already persisted with a different inherited event count (id collision)`)
-    }
-    this.assertVersion(meta)
-    const storedEvents = snapshotStoredEvents(events, session.header.id)
-    this.assertEventsSupported(meta, storedEvents)
-    if (!seedCoversPrefix(seed, storedEvents)) {
-      throw new Error(`session "${session.header.id}" already has a persisted log on disk that does not match this live session (id collision)`)
-    }
-    // Truncate-only repair (no closers): the open turn is NOT closed here.
-    if (tornMarker !== undefined) await this.backend.commitRepair(stored, tornMarker, [])
-    this.states.set(session.header.id, {
-      storage: {
-        meta: { ...meta },
-        inheritedEventCount,
-      },
-      cursor: SessionLogOffset(storedEvents.length),
-      materialized: true,
-      owner: session,
-    })
-    const suffix = seed.slice(storedEvents.length)
-    if (suffix.length > 0) await this.appendCore(session.header.id, suffix)
-  }
-
-  private async flush(session: Session): Promise<void> {
-    const live = this.initFor(session)
-    live.writes.cancelAutomaticWait()
-    try {
-      await live.init
-    } catch (error: unknown) {
-      // Admission is closed during retirement/teardown, but an ordinary flush
-      // may have raced one last enqueue while initialization was pending.
-      live.writes.cancelAutomaticWait()
-      throw error
-    }
-    await live.writes.flush()
-  }
-
-  /** Build one package-private write controller around initialization and id serialization. */
-  private createWriteBehind(session: Session, ready: () => Promise<void>): SessionWriteBehind {
-    return new SessionWriteBehind({
-      maxDelayMs: this.writeBatchMaxDelayMs,
-      write: async (batch) => {
-        await ready()
-        await this.serialize(session.header.id, () => this.appendLiveBatch(session.header.id, batch))
-      },
-      reportBackgroundFailure: (error) => {
-        this.ctx.logger.warn(`${this.backend.name}: background write for session "${session.id}" failed (buffered events retained): ${String(error)}`)
-      },
-    })
-  }
-
-  /** Append one controller-owned prefix after filtering events initialization already stored. */
-  private async appendLiveBatch(id: SessionId, batch: readonly SessionEvent[]): Promise<void> {
-    const state = this.states.get(id)
-    /* v8 ignore next -- state is always set by the awaited initialization */
-    const cursor = state?.cursor ?? 0
-    const fresh = batch.filter(e => e.seq >= cursor)
-    await this.appendCore(id, fresh)
-  }
-}
diff --git a/packages/session/session-persistence/src/errors.ts b/packages/session/session-persistence/src/errors.ts
index 0731b0edc7..62e232741e 100644
--- a/packages/session/session-persistence/src/errors.ts
+++ b/packages/session/session-persistence/src/errors.ts
@@ -1,8 +1,15 @@
-/** Stable failures exposed by the session-persistence service. */
+/**
+ * Stable failures exposed by the session-persistence service and its handles,
+ * including the format refusals shared by every backend: a stored log this
+ * build cannot faithfully interpret is refused, never misread, and the
+ * refusal points at the raw artifact when the backend keeps one per session.
+ * @module @deepseek-ai/dsh-session-persistence/errors
+ */
 
+import { SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 
-/** The requested Session identity has no materialized durable log. */
+/** The requested Session identity has no durable log visible to this caller. */
 export class SessionPersistenceNotFoundError extends Error {
   /** @param sessionId - absent durable Session identity. */
   constructor(readonly sessionId: SessionId) {
@@ -10,3 +17,121 @@ export class SessionPersistenceNotFoundError extends Error {
     this.name = 'SessionPersistenceNotFoundError'
   }
 }
+
+/** `create` targeted a Session identity that already exists in this backend. */
+export class SessionAlreadyExistsError extends Error {
+  /** @param sessionId - the occupied durable Session identity. */
+  constructor(readonly sessionId: SessionId) {
+    super(`session "${sessionId}" already exists`)
+    this.name = 'SessionAlreadyExistsError'
+  }
+}
+
+/** A write open found the session already bound to an active write handle. */
+export class SessionAlreadyOwnedError extends Error {
+  /** @param sessionId - the session whose write ownership is taken. */
+  constructor(readonly sessionId: SessionId) {
+    super(`session "${sessionId}" is already owned by an active write handle`)
+    this.name = 'SessionAlreadyOwnedError'
+  }
+}
+
+/** A mutation (`append`/`flush`) was called on a read handle. */
+export class SessionReadOnlyError extends Error {
+  /**
+   * @param sessionId - the session the read handle observes.
+   * @param operation - the refused mutating operation name.
+   */
+  constructor(readonly sessionId: SessionId, operation: string) {
+    super(`session "${sessionId}": ${operation} is not available on a read handle`)
+    this.name = 'SessionReadOnlyError'
+  }
+}
+
+/**
+ * A write handle's ownership is permanently gone: its lease expired, a renewal
+ * failed, or the durable ownership record no longer names this handle. The
+ * handle never re-acquires ownership — close it and reopen for write.
+ *
+ * Declared for the cross-process lease layer; the shipped in-process backends
+ * never throw it yet.
+ */
+export class SessionOwnershipLostError extends Error {
+  /** @param sessionId - the session whose write ownership this handle lost. */
+  constructor(readonly sessionId: SessionId) {
+    super(`session "${sessionId}": write ownership was lost; close this handle and reopen`)
+    this.name = 'SessionOwnershipLostError'
+  }
+}
+
+/** An operation was called on a handle after `close()` was called. */
+export class SessionHandleClosedError extends Error {
+  /**
+   * @param sessionId - the session the closed handle addressed.
+   * @param operation - the refused operation name.
+   */
+  constructor(readonly sessionId: SessionId, operation: string) {
+    super(`session "${sessionId}": ${operation} on a closed handle`)
+    this.name = 'SessionHandleClosedError'
+  }
+}
+
+/**
+ * A backend-resolved, per-session local artifact location. Carried only by
+ * refusal diagnostics ({@link SessionFormatUnsupportedError}) so a user can
+ * find the raw log a build refused to interpret; it is not a consumer-facing
+ * query — log access goes through a session handle's `read`.
+ */
+export interface SessionLocation {
+  /** Backend-specific artifact kind, for example `jsonl`. */
+  readonly kind: string
+  /** Absolute path to this session's backend-owned artifact. */
+  readonly path: string
+}
+
+/** Durable session contents failed validation after a successful backend read. */
+export class SessionPersistenceCorruptionError extends Error {
+  /**
+   * @param message - stable corruption context.
+   * @param options - original validation failure.
+   */
+  constructor(message: string, options: ErrorOptions) {
+    super(message, options)
+    this.name = 'SessionPersistenceCorruptionError'
+  }
+}
+
+/**
+ * The stored log is intact but this runtime cannot faithfully interpret it:
+ * the header carries an unsupported format version, or an event's type is
+ * unknown to this build. Distinct from {@link SessionPersistenceCorruptionError}
+ * — nothing is damaged; the raw log remains readable at {@link location} when
+ * the backend keeps one artifact per session.
+ */
+export class SessionFormatUnsupportedError extends Error {
+  /**
+   * @param message - stable reason the log cannot be interpreted, already
+   *   including the raw-log path when one exists.
+   * @param location - the backend's artifact location, when one exists.
+   */
+  constructor(message: string, readonly location?: SessionLocation) {
+    super(message)
+    this.name = 'SessionFormatUnsupportedError'
+  }
+}
+
+/**
+ * Direction-aware refusal text for a stored session whose format version this
+ * build does not read. Shared by load-time checks and by backends that must
+ * refuse BEFORE decoding version-dependent structure (a future format may not
+ * satisfy this build's structural checks at all, and the user must see
+ * "upgrade the harness", never "corrupt").
+ * @param id - the stored session id, for message context.
+ * @param version - the stored format version.
+ * @returns the stable refusal text, without a raw-log path suffix.
+ */
+export function sessionFormatVersionRefusal(id: string, version: number): string {
+  return version > SESSION_FORMAT_VERSION
+    ? `session "${id}" uses log format v${version}, but this harness reads only v${SESSION_FORMAT_VERSION}: the log was written by a newer harness — upgrade the harness to open it`
+    : `session "${id}" uses log format v${version}, older than the supported v${SESSION_FORMAT_VERSION}, and this build ships no upgrade path for it`
+}
diff --git a/packages/session/session-persistence/src/handle.ts b/packages/session/session-persistence/src/handle.ts
new file mode 100644
index 0000000000..a583bc8615
--- /dev/null
+++ b/packages/session/session-persistence/src/handle.ts
@@ -0,0 +1,106 @@
+/**
+ * The per-session storage handle: one open channel onto a stored session's
+ * append-only event log, returned by `SessionPersistence.create`/`open`.
+ * @module @deepseek-ai/dsh-session-persistence/handle
+ */
+
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
+
+/**
+ * Log access granted by an open. `write` is read-write: the session's single
+ * mutator, which also reads its own log. `read` only observes — it never
+ * takes ownership and works while another handle or process holds `write`.
+ */
+export type SessionAccess = 'read' | 'write'
+
+/** Options for {@link SessionHandle.read}. */
+export interface SessionHandleReadOptions {
+  /** Optional cancellation for backend read work. */
+  readonly signal?: AbortSignal
+}
+
+/** Options for {@link SessionHandle.append}. */
+export interface SessionHandleAppendOptions {
+  /** Optional cancellation observed before the write starts. */
+  readonly signal?: AbortSignal
+}
+
+/** Options for {@link SessionHandle.flush}. */
+export interface SessionHandleFlushOptions {
+  /** Optional cancellation observed before the barrier starts. */
+  readonly signal?: AbortSignal
+}
+
+/**
+ * One open channel onto a stored session. A handle is single-owner state, not
+ * a shared service: `read` never backtracks below what this handle already
+ * observed, a `write` handle reads its own successful appends, and `close()`
+ * is the one teardown (idempotent, uncancellable; `Symbol.asyncDispose`
+ * delegates to it). Every operation on a closed handle rejects with
+ * `SessionHandleClosedError`.
+ *
+ * Freshness across handles: once an `append` or `flush` resolves on a write
+ * handle, every read STARTED afterwards on the same backend instance — on any
+ * handle, or through `stat`/`list` — observes at least that prefix.
+ * Reads concurrent with a mutation carry no ordering promise beyond the valid
+ * contiguous prefix.
+ */
+export interface SessionHandle extends AsyncDisposable {
+  /** The stored session this handle addresses. */
+  readonly id: SessionId
+  /** The immutable stored header, fixed at `create`/`open`. */
+  readonly header: SessionHeader
+  /**
+   * Exact fork-inherited prefix length stored with the log; `0` when
+   * `header.isSeeded` is false. Storage metadata paired with the header for
+   * every body read, never part of the replayable event log.
+   */
+  readonly inheritedEventCount: SessionLogOffset
+  /** Whether this handle may mutate the log. */
+  readonly access: SessionAccess
+
+  /**
+   * Read a slice of the valid contiguous logical log. The slice is a legal log
+   * prefix segment: a torn physical tail is never returned, and repeated reads
+   * on this handle never observe an older state than a prior read.
+   * @param offset - first logical event seq to include; defaults to `0`.
+   * @param length - maximum number of events to return; defaults to the rest
+   *   of the log. An offset at or past the end returns an empty list.
+   * @param options - optional cancellation.
+   * @returns the events with `seq >= offset`, at most `length` of them.
+   */
+  read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<readonly SessionEvent[]>
+
+  /**
+   * Append a contiguous batch continuing the current logical end. The first
+   * event's `seq` MUST equal the stored next-seq; committed events are never
+   * rewritten. Persistence is best-effort: on resolution the batch is
+   * accepted, ordered, and visible to reads on this backend instance, but
+   * only a resolved {@link flush} promises it survives a crash — a backend
+   * may buffer or batch physical writes behind append. Rejects with
+   * `SessionReadOnlyError` on a read handle and `SessionOwnershipLostError`
+   * when write ownership is gone.
+   * @param events - the contiguous batch, in seq order.
+   * @param options - optional cancellation observed before the write starts.
+   */
+  append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>
+
+  /**
+   * The durability barrier — the one operation that promises storage: on
+   * resolution every acknowledged append is durable and the session is
+   * materialized for other processes; an empty created session becomes
+   * durably listable here. Callers that must survive a crash flush; a backend
+   * whose `append` already persists on resolution treats this as
+   * materialize-if-needed. Rejects with `SessionReadOnlyError` on a read
+   * handle.
+   * @param options - optional cancellation observed before the barrier starts.
+   */
+  flush(options?: SessionHandleFlushOptions): Promise<void>
+
+  /**
+   * Release the handle: a read handle frees local resources; a write handle
+   * completes pending durability and releases write ownership. Idempotent,
+   * asynchronous, and deliberately not cancellable.
+   */
+  close(): Promise<void>
+}
diff --git a/packages/session/session-persistence/src/index.ts b/packages/session/session-persistence/src/index.ts
index d110703d3a..154e4f04e8 100644
--- a/packages/session/session-persistence/src/index.ts
+++ b/packages/session/session-persistence/src/index.ts
@@ -1,34 +1,79 @@
 /**
  * Durable session-persistence Service Definition (`ctx.sessionPersistence`). Backends store
  * {@link SessionEvent}s as the event-sourced log and carry non-replayable
- * {@link SessionHeader} metadata separately.
+ * {@link SessionHeader} metadata separately; callers address one stored
+ * session through a {@link SessionHandle} obtained from `create`/`open`.
  * @module @deepseek-ai/dsh-session-persistence
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import { SessionPreparation, SessionLogOffset } from '@deepseek-ai/dsh-session'
-import type {
-  Session,
-  SessionEvent,
-  SessionId,
-  SessionHeader,
-} from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionHandle, SessionAccess } from './handle.ts'
 import type { SessionPersistenceRevision } from './revision.ts'
 
 // Re-export the metadata vocabulary so Consumers import it from the Service Definition.
 export type { SessionHeader } from '@deepseek-ai/dsh-session'
 export { SessionPersistenceRevision } from './revision.ts'
-export { SessionPersistenceNotFoundError } from './errors.ts'
+export type {
+  SessionAccess,
+  SessionHandle,
+  SessionHandleAppendOptions,
+  SessionHandleFlushOptions,
+  SessionHandleReadOptions,
+} from './handle.ts'
+export {
+  SessionAlreadyExistsError,
+  SessionAlreadyOwnedError,
+  SessionFormatUnsupportedError,
+  SessionHandleClosedError,
+  SessionOwnershipLostError,
+  SessionPersistenceCorruptionError,
+  SessionPersistenceNotFoundError,
+  SessionReadOnlyError,
+  sessionFormatVersionRefusal,
+} from './errors.ts'
+export type { SessionLocation } from './errors.ts'
+export {
+  assertContiguous,
+  assertStoredId,
+  assertVersion,
+  materializeAppendBatch,
+  materializeCreateHeader,
+  validateStoredEvents,
+} from './storage-contract.ts'
 
-/** Lightweight immutable source identity returned without loading a full log. */
+/**
+ * Lightweight stored-session observation returned by {@link SessionPersistence.stat}
+ * and {@link SessionPersistence.list} without reading the full event log.
+ */
 export interface SessionPersistenceSnapshot {
-  /** Detached metadata for one materialized session. */
-  header: SessionHeader
-  /** Opaque source-qualified token that changes whenever this stored log changes. */
-  revision: SessionPersistenceRevision
+  /** Detached metadata for one stored session. */
+  readonly header: SessionHeader
+  /** Opaque change token; see {@link SessionPersistence.stat}. */
+  readonly revision: SessionPersistenceRevision
+  /** Logical event count, when the backend can provide it cheaply from metadata; otherwise absent. */
+  readonly eventCount?: number
+  /** Physical artifact byte size, when the backend can provide it cheaply (JSONL); otherwise absent. */
+  readonly sizeBytes?: number
 }
 
-/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
+/** Options for {@link SessionPersistence.create}. */
+export interface SessionPersistenceCreateOptions {
+  /** Optional cancellation observed before backend work starts. */
+  readonly signal?: AbortSignal
+  /**
+   * Exact fork-inherited prefix length. Required when `header.isSeeded` is
+   * true and must be omitted (or `0`) otherwise; the backend refuses a
+   * mismatch at create.
+   */
+  readonly inheritedEventCount?: SessionLogOffset
+}
+
+/**
+ * Logical Session header paired with its exact inherited cut for body-bearing
+ * storage operations. `isSeeded` marks fork lineage on the header; the
+ * numeric cut travels beside it, never inside the replayable event log.
+ */
 export interface SessionStorageMetadata {
   /** Validated immutable Session header. */
   readonly meta: SessionHeader
@@ -36,64 +81,29 @@ export interface SessionStorageMetadata {
   readonly inheritedEventCount: SessionLogOffset
 }
 
-/** Immutable logical session prepared from persistence or a live owner. */
+/** Immutable logical session read: storage metadata plus the complete validated event log. */
 export interface SessionInspection extends SessionStorageMetadata {
-  /** Validated contiguous logical event log. */
+  /** Contiguous validated events from seq 0. */
   readonly events: readonly SessionEvent[]
 }
 
-/** Detached logical suffix returned by one explicit stored-log offset read. */
-export interface SessionEventSuffix extends SessionStorageMetadata {
-  /** First requested log offset; {@link events} contains only seqs at or after it. */
-  readonly fromSeq: SessionLogOffset
-  /** Valid contiguous stored events at or after {@link fromSeq}; not a complete Session log when the offset is nonzero. */
-  readonly events: readonly SessionEvent[]
+/** Options for {@link SessionPersistence.open}. */
+export interface SessionPersistenceOpenOptions {
+  /** Optional cancellation observed before backend work starts. */
+  readonly signal?: AbortSignal
 }
 
-/** A borrowed exact Session source returned from a cold materialization or concurrent live owner. */
-export type BorrowedSessionSource = Disposable & (
-  | {
-    /** A reusable unpublished Session is pinned until this observation is disposed. */
-    readonly source: 'prepared'
-    /** Immutable header and logical event prefix observed together. */
-    readonly inspection: SessionInspection
-    /** Durable revision represented by the prepared source. */
-    readonly revision: SessionPersistenceRevision
-    /** Exact unpublished Session retained for a later {@link prepare}. */
-    readonly preparedSession: Session
-  }
-  | {
-    /** A live Session won source resolution while the persistence read was starting. */
-    readonly source: 'live'
-    /** Immutable live header and event prefix observed together. */
-    readonly inspection: SessionInspection
-  }
-)
-
-/** A backend's own raw artifact text for one session, verbatim. */
-export interface SessionRawArtifact extends SessionStorageMetadata {
-  /** The artifact's base filename on disk, without any physical encoding suffix. */
-  readonly filename: string
-  /** The artifact's full text content, decoded from the backend's physical encoding. */
-  readonly content: string
+/** Options for {@link SessionPersistence.stat}. */
+export interface SessionPersistenceStatOptions {
+  /** Optional cancellation for backend metadata reads. */
+  readonly signal?: AbortSignal
 }
 
-// The backend-agnostic write-path orchestration first-party backends compose.
-export {
-  DEFAULT_PREPARED_SESSION_CACHE_SIZE,
-  DEFAULT_WRITE_BATCH_MAX_DELAY_MS,
-  MAX_WRITE_BATCH_DELAY_MS,
-  PersistenceCoordinator,
-  SessionFormatUnsupportedError,
-  SessionPersistenceCorruptionError,
-  sessionFormatVersionRefusal,
-} from './coordinator.ts'
-export type {
-  PersistenceBackend,
-  PersistenceCoordinatorOptions,
-  StoredPrefix,
-  StoredSuffix,
-} from './coordinator.ts'
+/** Options for {@link SessionPersistence.list}. */
+export interface SessionPersistenceListOptions {
+  /** Optional cancellation for backend listing work. */
+  readonly signal?: AbortSignal
+}
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -102,22 +112,24 @@ declare module '@deepseek-ai/cordis' {
 }
 
 /**
- * A backend-resolved, per-session local artifact location. The path is an
- * absolute target path and can name an artifact that has not materialized yet.
- * Consumers must treat it as a location hint, never as an authorization token.
- */
-export interface SessionLocation {
-  /** Backend-specific artifact kind, for example `jsonl`. */
-  readonly kind: string
-  /** Absolute path to this session's backend-owned artifact. */
-  readonly path: string
-}
-
-/**
- * Durable append-only session storage. Implementations preserve contiguous,
- * losslessly JSON-serializable events; {@link append} resolves only after
- * durability, and {@link load} balances a complete interrupted tail without
- * rewriting committed events.
+ * Durable append-only session storage addressed through per-session handles.
+ *
+ * Storage semantics shared by every backend: events are contiguous from seq 0
+ * and never rewritten; a torn physical tail is never returned to a reader and
+ * is truncated by the write path before its first append; reads validate
+ * current-format records only and refuse unknown vocabulary fail-closed.
+ * `append` persists best-effort; `flush` — per handle or service-wide — is
+ * the durability barrier.
+ *
+ * Visibility: a created session is observable through `stat`/`list`/`open`
+ * in this process from the moment `create` resolves, even while a backend
+ * defers physical materialization (a pure optimization); other processes see
+ * the session only once it materializes, and a session that never
+ * materialized before a crash never existed. `SessionHandle.flush` forces
+ * materialization.
+ *
+ * Freshness: once an `append` or `flush` resolves, reads started afterwards
+ * on this backend instance observe at least that prefix.
  */
 export abstract class SessionPersistence extends Service {
   constructor(ctx: Context) {
@@ -125,183 +137,64 @@ export abstract class SessionPersistence extends Service {
   }
 
   /**
-   * Resolve this backend's independent local artifact for a session without
-   * reading, creating, flushing, or otherwise materializing it. A backend
-   * that does not own one artifact per Session returns `undefined`.
-   * @param meta - the immutable session header whose artifact is requested.
-   * @returns the backend-specific absolute location, when one exists.
+   * Create a new stored session and take its write ownership.
+   * @param header - the immutable header (id, version, cwd, lineage) to store.
+   * @param options - optional cancellation.
+   * @returns a `write` handle owned by the caller; close it to release ownership.
+   * @throws {SessionAlreadyExistsError} when the id already exists.
    */
-  abstract locate(meta: SessionHeader): SessionLocation | undefined
+  abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>
 
   /**
-   * Whether this backend exposes one verbatim raw artifact per session.
-   * A backend that declares `true` must override {@link readRaw}.
-   */
-  abstract readonly supportsRawArtifacts: boolean
-
-  /**
-   * Read a session's backend-owned artifact text verbatim — the exact durable
-   * bytes the backend wrote (decoded from its physical encoding, e.g. a
-   * decompressed JSONL). The returned `content` is the raw text, not a
-   * reconstruction from parsed events, so it preserves backend-specific
-   * serialization (chunk packing, key order, line breaks). Callers first test
-   * {@link supportsRawArtifacts}; `undefined` then means only that the requested
-   * session has no materialized artifact.
-   * @param _id - the persisted session to read (unused by the default: no
-   * per-session artifact).
-   * @param signal - optional cancellation for backend read work.
-   * @returns the raw artifact plus its parsed header, or `undefined` when the
-   * session is absent.
-   * @throws when this backend does not expose per-session raw artifacts.
-   */
-  readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined> {
-    if (signal?.aborted === true) {
-      return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'))
-    }
-    return Promise.reject(new Error('this session persistence backend does not expose raw artifacts'))
-  }
-
-  /**
-   * Register a new session's metadata. A backend MAY defer the physical write
-   * until the first {@link append} (lazy materialization), in which case a
-   * created-but-never-appended session is absent from {@link list}
-   * — abandoned sessions leave nothing behind.
-   * @param meta - the immutable header (id, version, cwd, lineage) to record.
-   * @param inheritedEventCount - exact fork-inherited prefix length. Required
-   * for a seeded header and omitted only for an unseeded header.
-   */
-  abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>
-
-  /**
-   * Ensure a live session has a durable header even when it has no events.
-   * Ordinary sessions remain lazily materialized; lifecycle frontends call
-   * this only when an empty session itself is a durable resumable resource.
-   * @param _session - exact live session whose registered header is materialized.
-   */
-  ensureMaterialized(_session: Session): Promise<void> {
-    return Promise.reject(new Error('this session persistence backend cannot materialize an empty session'))
-  }
-
-  /**
-   * Durably persist a batch of events. Honors the append-only and contiguous-
-   * seq contracts: the first event's `seq` MUST equal the stored next-seq
-   * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
-   * serializable `event.data` with an error naming the offending event type.
-   * A seeded session's first materializing batch must reach its complete
-   * inherited prefix.
-   * @param id - the session the batch belongs to.
-   * @param events - the contiguous batch to persist, in seq order.
-   */
-  abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
-
-  /**
-   * Prepare the exact unpublished Session used by resume. Implementations may
-   * reuse object graphs retained by an earlier {@link inspect} after confirming
-   * their durable revision is still current; disposal releases an unpublished
-   * reservation. Revision retries require the durable log to remain unchanged
-   * for one read/check round trip; continuous external writers may delay completion.
-   * @param id - persisted session to prepare.
-   * @param signal - optional cancellation for preparation work.
-   * @returns one owned unpublished Session preparation.
-   */
-  async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation> {
-    signal?.throwIfAborted()
-    const loaded = await this.load(id)
-    signal?.throwIfAborted()
-    const sessions = this.ctx.get('sessions')
-    if (sessions === undefined) {
-      throw new Error('cannot prepare a session: SessionStore is not configured')
-    }
-    return SessionPreparation.create(sessions.prepare(id, {
-      seed: loaded.events.map(event => structuredClone(event)),
-      meta: structuredClone(loaded.meta),
-      inheritedEventCount: SessionLogOffset(loaded.inheritedEventCount),
-      seedSource: 'persistence',
-    }))
-  }
-
-  /**
-   * Load an immutable balanced logical view and commit any required cold
-   * recovery. A complete interrupted final turn is preserved and durably
-   * closed with missing tool errors plus any open step and turn boundaries;
-   * only a torn final record is discarded. Unknown versions and corruption in
-   * the committed prefix reject. Implementations MUST NOT crash-repair an
-   * identity still bound to a live Session: a balanced live log may return as a
-   * durable snapshot, while an open live turn rejects. Returned values may be
-   * shared with immutable live or prepared state and must not be mutated.
-   * Revision-based implementations may wait for one stable read/check round trip.
-   * @param id - the persisted session to reload.
-   * @returns the header and a log ending on a balanced `turn/end`.
-   */
-  abstract load(id: SessionId): Promise<SessionInspection>
-
-  /**
-   * Inspect an immutable logical session without committing recovery or
-   * publishing it. A cold complete interrupted turn receives synthetic closers
-   * in memory and a torn physical tail remains untouched. An already-live
-   * Session instead yields its current immutable snapshot, which may contain an
-   * open turn and its `session/end-seed` boundary. Coordinator-backed
-   * implementations retain the exact cold unpublished Session for bounded
-   * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
-   * already committing or reserved for resume remains exclusive, and inspection
-   * may borrow its immutable view. Callers borrow only the immutable header and
-   * log. Continuous external writers may delay revision convergence.
-   * @param id - the persisted session to inspect.
-   * @param signal - optional cancellation for queued and backend read work.
-   * @returns the validated header and current logical event log.
-   */
-  abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
-
-  /**
-   * Borrow one exact inspection while retaining any reusable prepared source.
-   * A cold observation must pin the exact prepared Session that a later
-   * {@link prepare} reserves. Implementations must not degrade this operation
-   * to a detached {@link inspect} result.
-   * @param id - persisted session to observe.
-   * @param signal - optional cancellation for preparation work.
-   * @returns a disposable immutable observation.
-   */
-  abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>
-
-  /**
-   * Read the stored events from `fromSeq` onward — the read-from-seq
-   * primitive for read models that resume from a watermark (e.g. a persisted
-   * projection cache folding only the tail past its checkpoint). Unlike
-   * {@link inspect}, it is a detached physical suffix read: no preparation
-   * cache, torn-tail truncation, synthetic closers, or coordinator-state
-   * publication. Only events from the valid contiguous stored prefix are
-   * returned, so a torn fragment never reaches the caller. `fromSeq` at or
-   * beyond the stored prefix returns an empty event list (never an error).
-   * A backend whose medium can seek by seq may read only the suffix;
-   * sequential media such as JSONL still parse the whole artifact and skip
-   * forward. The primitive bounds what is returned and refolded, not every
-   * backend's physical read.
-   * @param id - the persisted session to read.
-   * @param fromSeq - first event offset to include.
-   * @param signal - optional cancellation for queued and backend read work.
-   * @returns storage metadata, the requested offset, and stored events with `seq >= fromSeq`.
-   */
-  abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal):
-  Promise<SessionEventSuffix>
-
-  /**
-   * Lightweight listing from metadata, without a full-log parse.
-   * @param signal - optional cancellation for backend listing work.
-   * @returns one header per materialized session.
-   */
-  abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
-
-  /**
-   * List materialized sessions with cheap per-log change tokens.
+   * Open an existing stored session.
    *
-   * Repeated observations of an unchanged log return the same revision. A
-   * successful mutating {@link load} repair changes the next listed revision.
-   * Revisions also distinguish independently backed stores so backend-local
-   * counters cannot compare equal across different persistence sources.
-   * @param signal - optional cancellation for backend snapshot-listing work.
-   * @returns one header and opaque revision per materialized session without loading full logs.
+   * `read` never takes ownership and works while another handle (or process)
+   * holds write ownership. `write` atomically claims single-writer ownership;
+   * an existing active owner rejects.
+   * @param id - the stored session to open.
+   * @param access - `read` or `write`.
+   * @param options - optional cancellation.
+   * @returns the open handle.
+   * @throws {SessionPersistenceNotFoundError} when the session does not exist.
+   * @throws {SessionAlreadyOwnedError} for `write` when ownership is taken.
    */
-  abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+  abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>
+
+  /**
+   * Flush every active write handle owned by this service instance in one
+   * durability barrier: each handle's routed live events drain durably and
+   * its session materializes, exactly as that handle's own
+   * `SessionHandle.flush` would. Read handles buffer nothing and are
+   * untouched. A handle closed concurrently counts as flushed — close itself
+   * drains durably.
+   * @returns resolution once every write handle active at the call has flushed.
+   * @throws {AggregateError} naming each session whose flush failed; the
+   *   remaining handles still flush.
+   */
+  abstract flush(): Promise<void>
+
+  /**
+   * Observe one stored session without reading its event log or taking
+   * ownership.
+   *
+   * The snapshot's `revision` is an opaque change token comparable only
+   * against revisions from the same service instance and session id: equal
+   * revisions may be treated as an unchanged log; unequal revisions promise
+   * nothing. Write-ownership churn does not change a revision. It exists for
+   * derived read-model caches keyed off `stat`/`list`; it plays no part in
+   * open, read, or resume.
+   * @param id - the stored session to observe.
+   * @param options - optional cancellation.
+   * @returns the snapshot, or `undefined` when the session does not exist.
+   */
+  abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>
+
+  /**
+   * List every stored session visible to this process, in no promised order.
+   * @param options - optional cancellation.
+   * @returns one snapshot per stored session.
+   */
+  abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>
 }
 
 export default SessionPersistence
diff --git a/packages/session/session-persistence/src/preparations.ts b/packages/session/session-persistence/src/preparations.ts
deleted file mode 100644
index 96ad4352f7..0000000000
--- a/packages/session/session-persistence/src/preparations.ts
+++ /dev/null
@@ -1,401 +0,0 @@
-/**
- * Bounded sharing and exclusive reservation of unpublished Sessions.
- * @module @deepseek-ai/dsh-session-persistence/preparations
- */
-
-import type { Session, SessionId } from '@deepseek-ai/dsh-session'
-
-interface PreparedSource {
-  readonly session: Session
-}
-
-type PreparationPhase = 'loading' | 'ready' | 'committing' | 'reserved'
-
-interface PreparationEntry<Source, CommitState> {
-  readonly id: SessionId
-  readonly result: Promise<Source>
-  phase: PreparationPhase
-  source?: Source
-  reservation?: SessionPreparationReservation<Source, CommitState>
-  reservationSettled?: Promise<void>
-  settleReservation?: () => void
-  pins: number
-}
-
-/** A borrowed prepared source that remains outside ready-entry eviction until released. */
-export interface PreparationLease<Source> extends Disposable {
-  /** Shared immutable prepared source. */
-  readonly source: Source
-}
-
-/** One exclusively held prepared source and its committed persistence state. */
-export interface SessionPreparationReservation<Source, CommitState> {
-  readonly entry: PreparationEntry<Source, CommitState>
-  readonly source: Source
-  readonly state: CommitState
-}
-
-/** Per-coordinator cold-read sharing, exclusive reservation, and ready-entry LRU. */
-export class SessionPreparations<Source extends PreparedSource, CommitState> {
-  private readonly entries = new Map<SessionId, PreparationEntry<Source, CommitState>>()
-
-  constructor(private readonly capacity: number) {}
-
-  /**
-   * Whether this pool currently knows about an unpublished identity.
-   * @param id - session identity.
-   * @returns whether an entry exists for the identity.
-   */
-  has(id: SessionId): boolean {
-    return this.entries.has(id)
-  }
-
-  /**
-   * Observe one prepared source, sharing an in-flight read for the same id.
-   * @param id - session identity.
-   * @param load - cold loader used when no entry exists.
-   * @param signal - optional cancellation signal while waiting.
-   * @returns the shared prepared source.
-   */
-  async inspect(
-    id: SessionId,
-    load: () => Promise<Source>,
-    signal?: AbortSignal,
-  ): Promise<Source> {
-    const entry = this.entryFor(id, load)
-    const loaded = signal === undefined
-      ? await entry.result
-      : await observeQueuedAbort(entry.result, signal)
-    const source = entry.source ?? loaded
-    if (this.entries.get(id) === entry && entry.phase === 'ready') this.touch(entry)
-    return source
-  }
-
-  /**
-   * Borrow one prepared source and pin its ready entry against LRU eviction.
-   * @param id - session identity.
-   * @param load - cold loader used when no entry exists.
-   * @param signal - optional cancellation signal while waiting.
-   * @returns a caller-owned observation lease.
-   */
-  async borrow(
-    id: SessionId,
-    load: () => Promise<Source>,
-    signal?: AbortSignal,
-  ): Promise<PreparationLease<Source>> {
-    const entry = this.entryFor(id, load)
-    const pinned = this.entries.get(id) === entry
-    if (pinned) entry.pins += 1
-    let loaded: Source
-    try {
-      loaded = signal === undefined
-        ? await entry.result
-        : await observeQueuedAbort(entry.result, signal)
-    } catch (error: unknown) {
-      if (pinned && this.entries.get(id) === entry) {
-        entry.pins -= 1
-        if (entry.phase === 'ready') this.touch(entry)
-      }
-      throw error
-    }
-    const source = entry.source ?? loaded
-    if (this.entries.get(id) !== entry) {
-      return { source, [Symbol.dispose]: () => {} }
-    }
-    if (entry.phase === 'ready') this.touch(entry)
-    let released = false
-    return {
-      source,
-      [Symbol.dispose]: () => {
-        if (released) return
-        released = true
-        if (this.entries.get(id) !== entry) return
-        entry.pins -= 1
-        if (entry.phase === 'ready') this.touch(entry)
-      },
-    }
-  }
-
-  /**
-   * Reserve one ready source after committing its pending durable repair.
-   * @param id - session identity.
-   * @param load - cold loader used when no entry exists.
-   * @param commit - durable repair and cursor-state commit.
-   * @param signal - optional cancellation signal while waiting.
-   * @returns the exclusive reservation, or undefined if its entry was invalidated.
-   */
-  async reserve(
-    id: SessionId,
-    load: () => Promise<Source>,
-    commit: (source: Source) => Promise<{ source: Source; state: CommitState } | undefined>,
-    signal?: AbortSignal,
-  ): Promise<SessionPreparationReservation<Source, CommitState> | undefined> {
-    const entry = this.entryFor(id, load)
-    await (signal === undefined ? entry.result : observeQueuedAbort(entry.result, signal))
-    while (this.entries.get(id) === entry && entry.phase !== 'ready') {
-      const settled = entry.reservationSettled
-      /* v8 ignore next -- committing/reserved transitions install this waiter synchronously. */
-      if (settled === undefined) throw new Error(`session "${id}" preparation lost its reservation waiter`)
-      if (signal === undefined) await settled
-      else await observeQueuedAbort(settled, signal)
-    }
-    if (this.entries.get(id) !== entry) return undefined
-    const source = entry.source as Source
-    const reservationSettled = Promise.withResolvers<void>()
-    entry.phase = 'committing'
-    entry.reservationSettled = reservationSettled.promise
-    entry.settleReservation = reservationSettled.resolve
-    let committed: { source: Source; state: CommitState } | undefined
-    try {
-      committed = await commit(source)
-    } catch (error: unknown) {
-      this.remove(entry)
-      throw error
-    }
-    if (committed === undefined) {
-      this.remove(entry)
-      return undefined
-    }
-    entry.source = committed.source
-    try {
-      signal?.throwIfAborted()
-    } catch (error: unknown) {
-      this.makeReady(entry)
-      throw error
-    }
-    if (this.entries.get(id) !== entry) return undefined
-    const reservation: SessionPreparationReservation<Source, CommitState> = {
-      entry,
-      source: committed.source,
-      state: committed.state,
-    }
-    entry.phase = 'reserved'
-    entry.reservation = reservation
-    return reservation
-  }
-
-  /**
-   * Return the exact reservation for Session publication, rejecting aliases.
-   * @param session - exact Session candidate for publication.
-   * @returns its reservation, or undefined when no preparation exists.
-   */
-  reservationFor(session: Session): SessionPreparationReservation<Source, CommitState> | undefined {
-    const entry = this.entries.get(session.id)
-    if (entry === undefined) return undefined
-    if (entry.phase === 'reserved'
-      && entry.source?.session === session
-      && entry.reservation !== undefined) {
-      return entry.reservation
-    }
-    throw new Error(`cannot publish session "${session.id}": persisted state already owns this identity`)
-  }
-
-  /**
-   * Consume a reservation after its exact Session has attached.
-   * @param reservation - reservation to consume.
-   */
-  attach(reservation: SessionPreparationReservation<Source, CommitState>): void {
-    const { entry } = reservation
-    if (this.entries.get(entry.id) !== entry || entry.reservation !== reservation) {
-      throw new Error(`session "${entry.id}" preparation is no longer reserved`)
-    }
-    this.remove(entry)
-  }
-
-  /**
-   * Consume a reservation whose caller only needs the committed inspection.
-   * @param reservation - reservation to consume.
-   */
-  discard(reservation: SessionPreparationReservation<Source, CommitState>): void {
-    const { entry } = reservation
-    if (this.entries.get(entry.id) !== entry || entry.reservation !== reservation) return
-    this.remove(entry)
-  }
-
-  /**
-   * Return a reusable unpublished reservation to the ready LRU.
-   * @param reservation - reservation to release.
-   * @param reusable - whether the source remains valid for reuse.
-   */
-  release(
-    reservation: SessionPreparationReservation<Source, CommitState>,
-    reusable: boolean,
-  ): void {
-    const { entry } = reservation
-    if (this.entries.get(entry.id) !== entry
-      || entry.reservation !== reservation
-      || entry.phase !== 'reserved') return
-    if (!reusable) {
-      this.remove(entry)
-      return
-    }
-    delete entry.reservation
-    this.makeReady(entry)
-  }
-
-  /**
-   * Discard a prepared view after the durable log changes.
-   * @param id - changed session identity.
-   */
-  invalidate(id: SessionId): void {
-    const entry = this.entries.get(id)
-    if (entry !== undefined) this.remove(entry)
-  }
-
-  /**
-   * Discard an exact stale ready source without disturbing an exclusive owner.
-   * @param id - changed session identity.
-   * @param expected - exact source observed before its revision check.
-   * @returns whether the source was discarded, retained by a reservation, or is absent.
-   */
-  discardReady(id: SessionId, expected: Source): 'discarded' | 'retained' | 'missing' {
-    const entry = this.entries.get(id)
-    if (entry === undefined || entry.source !== expected) return 'missing'
-    if (entry.phase !== 'ready') return 'retained'
-    this.remove(entry)
-    return 'discarded'
-  }
-
-  /**
-   * Reject writes while an unpublished Session exclusively reserves the id.
-   * @param id - session identity to check.
-   */
-  assertWritable(id: SessionId): void {
-    const phase = this.entries.get(id)?.phase
-    if (phase === 'committing' || phase === 'reserved') {
-      throw new Error(`cannot append session "${id}" while its persisted preparation is reserved`)
-    }
-  }
-
-  /**
-   * Remove a completed entry for an already-serialized append adoption.
-   * @param id - adopted session identity.
-   * @returns the prepared source, or undefined when no ready entry exists.
-   */
-  takeReady(id: SessionId): Source | undefined {
-    const entry = this.entries.get(id)
-    if (entry === undefined || entry.phase !== 'ready' || entry.source === undefined) return undefined
-    this.remove(entry)
-    return entry.source
-  }
-
-  private entryFor(
-    id: SessionId,
-    load: () => Promise<Source>,
-  ): PreparationEntry<Source, CommitState> {
-    const existing = this.entries.get(id)
-    if (existing !== undefined) return existing
-    const deferred = Promise.withResolvers<Source>()
-    const entry: PreparationEntry<Source, CommitState> = {
-      id,
-      result: deferred.promise,
-      phase: 'loading',
-      pins: 0,
-    }
-    this.entries.set(id, entry)
-    let loading: Promise<Source>
-    try {
-      // Start immediately so a same-tick serialized append queues behind this
-      // read. The deferred result settles only after the entry becomes ready.
-      loading = load()
-    } catch (error: unknown) {
-      this.remove(entry)
-      deferred.reject(error)
-      return entry
-    }
-    void loading.then((source) => {
-      if (this.entries.get(id) === entry) {
-        entry.source = source
-        this.makeReady(entry)
-      }
-      deferred.resolve(source)
-    }, (error: unknown) => {
-      this.remove(entry)
-      deferred.reject(error)
-    })
-    return entry
-  }
-
-  private makeReady(entry: PreparationEntry<Source, CommitState>): void {
-    if (this.entries.get(entry.id) !== entry) return
-    entry.phase = 'ready'
-    const settle = entry.settleReservation
-    delete entry.reservationSettled
-    delete entry.settleReservation
-    settle?.()
-    this.touch(entry)
-  }
-
-  private remove(entry: PreparationEntry<Source, CommitState>): void {
-    if (this.entries.get(entry.id) !== entry) return
-    this.entries.delete(entry.id)
-    const settle = entry.settleReservation
-    delete entry.reservationSettled
-    delete entry.settleReservation
-    settle?.()
-  }
-
-  private touch(entry: PreparationEntry<Source, CommitState>): void {
-    this.entries.delete(entry.id)
-    this.entries.set(entry.id, entry)
-    let readyCount = 0
-    for (const candidate of this.entries.values()) {
-      if (candidate.phase === 'ready') readyCount += 1
-    }
-    if (readyCount <= this.capacity) return
-    for (const [id, candidate] of this.entries) {
-      if (candidate.phase !== 'ready' || candidate.pins > 0) continue
-      this.entries.delete(id)
-      return
-    }
-  }
-}
-
-/**
- * Give a queued observer a prompt cancellation view without cancelling shared work.
- * @param operation - shared operation whose settlement remains authoritative.
- * @param signal - observer-local cancellation signal.
- * @param started - whether the operation has crossed its cancellation cutoff.
- * @returns the operation result or the observer's prompt cancellation.
- */
-export function observeQueuedAbort<T>(
-  operation: Promise<T>,
-  signal: AbortSignal,
-  started: () => boolean = () => false,
-): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    let settled = false
-    const finish = (callback: () => void): void => {
-      if (settled) return
-      settled = true
-      signal.removeEventListener('abort', onAbort)
-      callback()
-    }
-    const onAbort = (): void => {
-      if (started()) return
-      finish(() => {
-        try {
-          signal.throwIfAborted()
-        } catch (reason: unknown) {
-          rejectObservation(reject, reason)
-          return
-        }
-        /* v8 ignore next -- a native AbortSignal emits abort only after becoming aborted. */
-        reject(new Error('queued observation abort event lacked an aborted signal'))
-      })
-    }
-    signal.addEventListener('abort', onAbort, { once: true })
-    operation.then(
-      (value) => { finish(() => { resolve(value) }) },
-      (reason: unknown) => {
-        finish(() => { rejectObservation(reject, reason) })
-      },
-    )
-    if (signal.aborted) onAbort()
-  })
-}
-
-/** Preserve an exact loader or AbortSignal reason, including legacy non-Error values. */
-function rejectObservation(reject: (reason?: unknown) => void, reason: unknown): void {
-  reject(reason)
-}
diff --git a/packages/session/session-persistence/src/storage-contract.ts b/packages/session/session-persistence/src/storage-contract.ts
new file mode 100644
index 0000000000..d921f00064
--- /dev/null
+++ b/packages/session/session-persistence/src/storage-contract.ts
@@ -0,0 +1,148 @@
+/**
+ * Backend-shared storage validation: the version gate, the fail-closed event
+ * vocabulary, append-batch materialization, and contiguity — one place so
+ * every backend refuses the same inputs identically.
+ * @module @deepseek-ai/dsh-session-persistence/storage-contract
+ */
+
+import {
+  adoptSessionEvent,
+  KNOWN_SESSION_EVENT_TYPES,
+  SESSION_FORMAT_VERSION,
+} from '@deepseek-ai/dsh-session'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-util-values'
+import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import {
+  SessionFormatUnsupportedError,
+  SessionPersistenceCorruptionError,
+  sessionFormatVersionRefusal,
+  type SessionLocation,
+} from './errors.ts'
+
+/** Build a format refusal that points at the raw artifact when the backend has one. */
+function unsupported(reason: string, location: SessionLocation | undefined): SessionFormatUnsupportedError {
+  return new SessionFormatUnsupportedError(
+    location === undefined ? reason : `${reason} (raw log: ${location.path})`,
+    location,
+  )
+}
+
+/**
+ * Refuse stored metadata that is not bound to the requested session id.
+ * @param id - the requested session id.
+ * @param meta - the stored header.
+ */
+export function assertStoredId(id: SessionId, meta: SessionHeader): void {
+  if (meta.id !== id) {
+    throw new Error(`stored session identity mismatch: requested "${id}", header contains "${meta.id}"`)
+  }
+}
+
+/**
+ * Refuse a stored header whose format version this build does not read.
+ * @param meta - the stored header.
+ * @param location - the backend's artifact location for the refusal, when one exists.
+ */
+export function assertVersion(meta: SessionHeader, location?: SessionLocation): void {
+  if (meta.version !== SESSION_FORMAT_VERSION) {
+    throw unsupported(sessionFormatVersionRefusal(meta.id, meta.version), location)
+  }
+}
+
+/**
+ * Validate one exclusively owned stored event array in place: adopt each
+ * record (validating and freezing it) and refuse any event type this build
+ * does not know, unless its writer marked it `ignorable: true` — silently
+ * skipping an unknown required event could reconstruct a wrong session (the
+ * envelope contract on `SessionEvent.ignorable`). Both newer vocabularies and
+ * retired pre-release shapes refuse here; this build ships no migration.
+ * @param meta - the stored header the events belong to.
+ * @param events - exclusively owned decoded events; validated in place.
+ * @param location - the backend's artifact location for refusals, when one exists.
+ * @returns the same array, validated and frozen.
+ * @throws {SessionFormatUnsupportedError} for unknown event types.
+ * @throws {SessionPersistenceCorruptionError} for records that fail validation.
+ */
+export function validateStoredEvents(
+  meta: SessionHeader,
+  events: SessionEvent[],
+  location?: SessionLocation,
+): SessionEvent[] {
+  for (const event of events) {
+    if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable !== true) {
+      throw unsupported(
+        `session "${meta.id}" contains event type "${event.type}" (seq ${event.seq}) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness`,
+        location,
+      )
+    }
+    // The one retired shape hiding under a known type: the removed delta codec's
+    // full-header "fallback" reason. Everything else retired was a whole type.
+    if (event.type === 'request/header') {
+      const data: unknown = event.data
+      if (typeof data === 'object' && data !== null
+        && (data as Record<string, unknown>)['reason'] === 'fallback') {
+        throw unsupported(
+          `session "${meta.id}" contains a request/header event (seq ${event.seq}) with the unsupported legacy reason "fallback"; refusing to interpret the log — it was written by a retired pre-release harness`,
+          location,
+        )
+      }
+    }
+  }
+  try {
+    for (const [index, event] of events.entries()) events[index] = adoptSessionEvent(event)
+  } catch (error: unknown) {
+    if (error instanceof SessionFormatUnsupportedError) throw error
+    throw new SessionPersistenceCorruptionError(
+      `stored session "${meta.id}" failed validation: ${String(error)}`,
+      { cause: error },
+    )
+  }
+  return events
+}
+
+/**
+ * Validate and deep-snapshot a header passed to `create` in one traversal.
+ * @param header - the caller's header.
+ * @returns the detached lossless-JSON header.
+ * @throws {TypeError} for non-JSON metadata or an invalid `createdAt`.
+ */
+export function materializeCreateHeader(header: SessionHeader): SessionHeader {
+  const snapshot = snapshotJsonValue(header)
+  if (snapshot === undefined) {
+    throw new TypeError('session metadata must be losslessly JSON-serializable')
+  }
+  if (!Number.isSafeInteger(snapshot.createdAt) || snapshot.createdAt < 0) {
+    throw new TypeError('session metadata createdAt must be a non-negative safe integer')
+  }
+  return snapshot
+}
+
+/**
+ * Validate and deep-snapshot one append batch in a single traversal, so the
+ * checked value is exactly the value persisted (a check followed by a copy
+ * could reread accessors into a different record).
+ * @param events - the caller's batch.
+ * @returns the detached lossless-JSON batch.
+ * @throws {TypeError} when any event data is not losslessly JSON-serializable.
+ */
+export function materializeAppendBatch(events: readonly SessionEvent[]): readonly SessionEvent[] {
+  const batch = snapshotJsonValue(events)
+  if (batch === undefined) {
+    throw new TypeError('session event batch is not losslessly JSON-serializable because it contains non-JSON-serializable data')
+  }
+  return batch
+}
+
+/**
+ * Refuse a batch that does not contiguously continue the stored log.
+ * @param id - the session the batch belongs to.
+ * @param events - the batch, in seq order.
+ * @param cursor - the stored next-seq.
+ */
+export function assertContiguous(id: SessionId, events: readonly SessionEvent[], cursor: number): void {
+  for (const [index, event] of events.entries()) {
+    if (event.seq !== cursor + index) {
+      throw new Error(`append seq mismatch for "${id}": expected ${cursor + index} at index ${index}, got ${event.seq}`)
+    }
+  }
+}
diff --git a/packages/session/session-persistence/src/write-behind.ts b/packages/session/session-persistence/src/write-behind.ts
deleted file mode 100644
index 97797732f6..0000000000
--- a/packages/session/session-persistence/src/write-behind.ts
+++ /dev/null
@@ -1,159 +0,0 @@
-/**
- * Bounded per-session write batching for the shared persistence coordinator.
- * @module @deepseek-ai/dsh-session-persistence/write-behind
- */
-
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
-
-/** Dependencies and scheduling policy for one live session's write controller. */
-export interface SessionWriteBehindOptions {
-  /** Maximum intentional batching wait after an idle queue receives work. */
-  readonly maxDelayMs: number
-  /** Persist one stable ordered prefix; resolves only after backend durability. */
-  readonly write: (events: readonly SessionEvent[]) => Promise<void>
-  /** Observe a detached background write failure without rejecting the producer. */
-  readonly reportBackgroundFailure: (error: unknown) => void
-}
-
-/**
- * Owns one live session's pending events, fixed batching deadline, active write,
- * failure retention, and explicit quiescence barrier.
- */
-export class SessionWriteBehind {
-  private pending: SessionEvent[] = []
-  private timer: ReturnType<typeof setTimeout> | undefined
-  private active: Promise<void> | undefined
-  private barrier: Promise<void> | undefined
-  private deadlineExpired = false
-  private automaticPaused = false
-
-  /**
-   * @param options - fixed scheduling policy and durable batch sink.
-   */
-  constructor(private readonly options: SessionWriteBehindOptions) {}
-
-  /** Whether this controller owns queued events or an active durable write. */
-  get hasWork(): boolean {
-    return this.pending.length > 0 || this.active !== undefined
-  }
-
-  /**
-   * Copy one event into the persistence-owned queue and start a fixed deadline
-   * when the automatic path is idle.
-   * @param event - frozen live event to retain independently of its producer.
-   */
-  enqueue(event: SessionEvent): void {
-    const wasEmpty = this.pending.length === 0
-    this.pending.push(structuredClone(event))
-    if (this.barrier !== undefined) return
-    if (this.automaticPaused) {
-      this.automaticPaused = false
-      this.deadlineExpired = false
-      this.armTimer()
-    } else if (wasEmpty) {
-      this.armTimer()
-    }
-  }
-
-  /**
-   * Cancel the batching wait and durably drain through a quiescent point.
-   * Concurrent callers join the same barrier.
-   * @returns a promise that rejects if the barrier's durable retry fails.
-   */
-  flush(): Promise<void> {
-    if (this.barrier !== undefined) return this.barrier
-    this.cancelTimer()
-    this.deadlineExpired = false
-    this.automaticPaused = false
-    const barrier = Promise.withResolvers<void>()
-    this.barrier = barrier.promise
-    void this.drainBarrier(barrier.resolve, barrier.reject)
-    return barrier.promise
-  }
-
-  /** Cancel the current automatic deadline without draining retained work. */
-  cancelAutomaticWait(): void {
-    this.cancelTimer()
-    this.deadlineExpired = false
-  }
-
-  /** Start the one fixed window for the current pending prefix. */
-  private armTimer(): void {
-    this.timer = setTimeout(() => { this.onDeadline() }, this.options.maxDelayMs)
-  }
-
-  /** Cancel any pending automatic deadline. */
-  private cancelTimer(): void {
-    if (this.timer === undefined) return
-    clearTimeout(this.timer)
-    this.timer = undefined
-  }
-
-  /** Start a background write now, or remember that an active write used the budget. */
-  private onDeadline(): void {
-    this.timer = undefined
-    if (this.active !== undefined) {
-      this.deadlineExpired = true
-      return
-    }
-    this.startBackground()
-  }
-
-  /** Start one detached write whose failure is reported and retained. */
-  private startBackground(): void {
-    const active = this.startWrite(true)
-    void active.then(() => { this.continueAutomatic() }, () => {})
-  }
-
-  /** Continue immediately after an over-budget active write, otherwise keep its timer. */
-  private continueAutomatic(): void {
-    if (this.barrier !== undefined || this.pending.length === 0) return
-    if (this.deadlineExpired) {
-      this.deadlineExpired = false
-      this.startBackground()
-    }
-  }
-
-  /** Await overlapping work, drain to quiescence, and settle the shared barrier. */
-  private async drainBarrier(resolve: () => void, reject: (reason?: unknown) => void): Promise<void> {
-    try {
-      const overlapping = this.active
-      if (overlapping !== undefined) {
-        await Promise.allSettled([overlapping])
-        this.automaticPaused = false
-      }
-      while (this.pending.length > 0) await this.startWrite(false)
-    } catch (error: unknown) {
-      this.barrier = undefined
-      reject(error)
-      return
-    }
-    // Close admission to this barrier in the same job that observes the empty
-    // queue, before resolving callers. A later enqueue therefore starts its own
-    // automatic window instead of being stranded behind a settled barrier.
-    this.barrier = undefined
-    resolve()
-  }
-
-  /** Start one stable pending prefix, retaining it in order if durability fails. */
-  private startWrite(background: boolean): Promise<void> {
-    const batch = this.pending.splice(0)
-    this.cancelTimer()
-    this.deadlineExpired = false
-    const operation = Promise.resolve().then(() => this.options.write(batch))
-    const active = operation
-      .catch((error: unknown) => {
-        this.pending = batch.concat(this.pending)
-        this.cancelTimer()
-        this.deadlineExpired = false
-        this.automaticPaused = true
-        if (background) this.options.reportBackgroundFailure(error)
-        throw error
-      })
-      .finally(() => {
-        this.active = undefined
-      })
-    this.active = active
-    return active
-  }
-}
diff --git a/packages/session/session-persistence/tests/contract.ts b/packages/session/session-persistence/tests/contract.ts
index b8f611eebb..aaafa649bc 100644
--- a/packages/session/session-persistence/tests/contract.ts
+++ b/packages/session/session-persistence/tests/contract.ts
@@ -1,47 +1,60 @@
 /**
- * Reusable contract test for any {@link SessionPersistence} backend. A backend
- * package imports {@link runPersistenceContract} and calls it with a factory
- * that yields a fresh, empty backend (and a teardown), so every backend is held
- * to the same append-only / contiguous-seq / lazy-materialization / crash
- * semantics. The JSONL backend's own spec adds file-specific tests on top.
+ * Reusable handle contract test for any {@link SessionPersistence} backend. A
+ * backend package imports {@link runPersistenceContract} and calls it with a
+ * factory that yields a fresh, empty backend (plus teardown, an optional
+ * same-storage reopen, and an optional physical tail corruptor), so every
+ * backend is held to the same create/open/handle semantics: append-only
+ * contiguous seqs, single-writer ownership, lazy materialization, fail-closed
+ * vocabulary, freshness, and torn-tail repair. Backend-specific behavior
+ * (file layout, encodings, artifact export) stays in each backend's own spec.
  *
  * @module @deepseek-ai/dsh-session-persistence/tests/contract
  */
 
 import { describe, expect, it } from 'vitest'
+import { SessionSeq, SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import { MessageId, freezeMessage } from '@deepseek-ai/dsh-llm'
 import {
-  SESSION_FORMAT_VERSION,
-  Session,
-  SessionId,
-  SessionLogOffset,
-  SessionSeq,
-  TOOL_NOT_STARTED,
-  TOOL_OUTCOME_UNKNOWN,
-} from '@deepseek-ai/dsh-session'
-import type {
-  SessionEvent,
-  SessionHeader,
-  SessionLogOffset as SessionLogOffsetType,
-  SurfaceEventType,
-  SurfaceIntent,
-} from '@deepseek-ai/dsh-session'
-import { ToolCallId, MessageId, createMessage, freezeMessage } from '@deepseek-ai/dsh-llm'
-import type { SessionPersistence } from '../src/index.ts'
+  SessionAlreadyExistsError,
+  SessionAlreadyOwnedError,
+  SessionFormatUnsupportedError,
+  SessionHandleClosedError,
+  SessionPersistenceNotFoundError,
+  SessionReadOnlyError,
+} from '../src/index.ts'
+import type { SessionHandle, SessionPersistence } from '../src/index.ts'
 
-/** A backend under test plus its teardown. */
-export interface ContractBackend {
+/** One backend service instance under test plus its teardown. */
+interface ContractBackendInstance {
   persistence: SessionPersistence
   dispose: () => Promise<void>
 }
 
+/** A backend under test: the primary instance plus optional storage-level capabilities. */
+export interface ContractBackend extends ContractBackendInstance {
+  /**
+   * Open a FRESH backend instance over the SAME storage, as another process
+   * would after this one exits. Enables the cross-instance visibility and
+   * reopen-continuation tests; a backend without shared storage omits it and
+   * those tests self-skip.
+   */
+  reopen?: () => Promise<ContractBackendInstance>
+  /**
+   * Inject a torn physical tail after the committed log of one stored session,
+   * simulating a crash mid-write. Enables the torn-tail tests.
+   */
+  corruptTail?: (id: SessionId, cwd: string | undefined) => Promise<void>
+}
+
 /** Build a minimal {@link SessionHeader} for a session id. */
 export function meta(id: string, cwd?: string): SessionHeader {
   return {
     version: SESSION_FORMAT_VERSION,
     id: SessionId(id),
     createdAt: 1000,
-    ...cwd !== undefined ? { cwd } : {},
     isSeeded: false,
+    ...cwd !== undefined ? { cwd } : {},
   }
 }
 
@@ -72,422 +85,487 @@ export function oneTurnLog(): SessionEvent[] {
   ]
 }
 
-/**
- * Append recorded events to a live session while forwarding surface metadata verbatim. The broad
- * `SessionEvent` union makes the typed marker optional, but the runtime guard must still reject a
- * surface event whose fixture omitted it; this helper never synthesizes a default.
- */
-export function appendLog(session: Session, events: readonly SessionEvent[]): void {
-  for (const e of events) {
-    const se = e as SessionEvent<SurfaceEventType>
-    if (se.surfaceOp !== undefined) {
-      const intent: SurfaceIntent = {
-        surfaceOp: se.surfaceOp,
-        ...se.sourceEventSeqs !== undefined ? { sourceEventSeqs: se.sourceEventSeqs } : {},
-      }
-      session.append(e.type, e.data, intent)
-    } else {
-      session.append(e.type, e.data)
-    }
-  }
+
+/** A contiguous second-turn batch continuing {@link oneTurnLog}. */
+function secondTurn(startSeq = 6): SessionEvent[] {
+  return [
+    { type: 'turn/start', seq: SessionSeq(startSeq), time: 9, data: { turn: 2 } },
+    { type: 'turn/end', seq: SessionSeq(startSeq + 1), time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
+  ]
 }
 
 /**
- * Run the backend-agnostic contract suite. `make()` MUST return a fresh, empty
- * backend each call.
+ * Run the backend-agnostic handle contract suite. `make()` MUST return a
+ * fresh backend over fresh, empty storage each call.
+ * @param name - suite label, e.g. `jsonl-none` / `sqlite`.
+ * @param make - factory producing one fresh {@link ContractBackend} per test.
  */
 export function runPersistenceContract(name: string, make: () => Promise<ContractBackend>): void {
   describe(`SessionPersistence contract: ${name}`, () => {
-    it('round-trips a session: create + append → load returns identical meta and byte-identical events', async () => {
+    it('round-trips through one write handle: append, self-read, offset/length defaults', async () => {
       const { persistence, dispose } = await make()
       try {
-        const m = meta('s1', '/work')
+        const m = meta('round-trip', '/work')
         const log = oneTurnLog()
-        await persistence.create(m)
-        await persistence.append(m.id, log)
+        const handle = await persistence.create(m)
+        expect(handle.access).toBe('write')
+        expect(handle.id).toBe(m.id)
+        expect(handle.header).toMatchObject(m)
 
-        const loaded = await persistence.load(m.id)
-        expect(loaded.meta).toMatchObject({ version: SESSION_FORMAT_VERSION, id: m.id, cwd: '/work' })
-        expect(loaded.events).toEqual(log)
+        await handle.append(log)
+        // An empty batch is a no-op, not an error.
+        await handle.append([])
+        // A write handle reads its own successful appends.
+        expect(await handle.read()).toEqual(log)
+        expect(await handle.read(3)).toEqual(log.slice(3))
+        expect(await handle.read(0, 2)).toEqual(log.slice(0, 2))
+        expect(await handle.read(1, 3)).toEqual(log.slice(1, 4))
+        // At/past the stored end: an empty list, never an error.
+        expect(await handle.read(log.length)).toEqual([])
+        expect(await handle.read(log.length + 100)).toEqual([])
+        // flush after a durable append is a satisfied barrier, not an error.
+        await handle.flush()
+        await handle.close()
       } finally {
         await dispose()
       }
     })
 
-    it('rejects a fractional creation timestamp without reserving its session id', async () => {
+    it('read rejects negative or fractional offsets and lengths', async () => {
       const { persistence, dispose } = await make()
       try {
-        const m = { ...meta('fractional-created-at'), createdAt: 1.5 }
-        await expect(persistence.create(m))
-          .rejects.toThrow('session metadata createdAt must be a non-negative safe integer')
-
-        const valid = meta('fractional-created-at')
-        await persistence.create(valid)
-        await persistence.append(valid.id, oneTurnLog())
-        expect((await persistence.load(valid.id)).meta.createdAt).toBe(valid.createdAt)
+        const handle = await persistence.create(meta('read-args'))
+        await expect(handle.read(-1)).rejects.toThrow(/non-negative safe integer/)
+        await expect(handle.read(1.5)).rejects.toThrow(/non-negative safe integer/)
+        await expect(handle.read(0, -1)).rejects.toThrow(/non-negative safe integer/)
+        await handle.close()
       } finally {
         await dispose()
       }
     })
 
-    it('requires an explicit inherited cut exactly when the header is seeded', async () => {
+    it('duplicate create rejects against a live pending session and allows the id after an erasing close', async () => {
       const { persistence, dispose } = await make()
       try {
-        const seeded = { ...meta('seeded-create'), isSeeded: true }
-        await expect(persistence.create(seeded))
-          .rejects.toThrow('seeded session metadata requires an inherited event count')
-        await expect(persistence.create(meta('unseeded-nonzero'), SessionLogOffset(1)))
-          .rejects.toThrow('unseeded session metadata inherited event count must be 0')
-
-        await persistence.create(seeded, SessionLogOffset(0))
-        await persistence.append(seeded.id, oneTurnLog())
-        await expect(persistence.load(seeded.id)).resolves.toMatchObject({
-          meta: { isSeeded: true },
-          inheritedEventCount: 0,
-        })
+        const first = await persistence.create(meta('dup-pending'))
+        await expect(persistence.create(meta('dup-pending'))).rejects.toBeInstanceOf(SessionAlreadyExistsError)
+        // Closing the creator without ever appending erases the session, so
+        // the id is free again.
+        await first.close()
+        const second = await persistence.create(meta('dup-pending'))
+        await second.close()
       } finally {
         await dispose()
       }
     })
 
-    it('does not materialize a seeded artifact before its complete inherited prefix', async () => {
+    it('concurrent duplicate creates: one wins, the loser rejects SessionAlreadyExistsError', async () => {
       const { persistence, dispose } = await make()
       try {
-        const seeded = { ...meta('seeded-partial-create'), isSeeded: true }
-        await persistence.create(seeded, SessionLogOffset(2))
-        await expect(persistence.append(seeded.id, oneTurnLog().slice(0, 1)))
-          .rejects.toThrow('cannot materialize before its inherited prefix is complete')
-        expect((await persistence.list()).map(header => header.id)).not.toContain(seeded.id)
-
-        await persistence.append(seeded.id, oneTurnLog())
-        await expect(persistence.load(seeded.id)).resolves.toMatchObject({
-          inheritedEventCount: 2,
-        })
+        const m = meta('dup-race')
+        // Both calls pass the stored-existence check before either registers,
+        // so the loser is refused at the claim, still as a duplicate create.
+        const results = await Promise.allSettled([persistence.create(m), persistence.create(m)])
+        const winners = results.filter(r => r.status === 'fulfilled')
+        const losers = results.filter(r => r.status === 'rejected')
+        expect(winners).toHaveLength(1)
+        expect(losers).toHaveLength(1)
+        expect((losers[0] as PromiseRejectedResult).reason).toBeInstanceOf(SessionAlreadyExistsError)
+        await (winners[0] as PromiseFulfilledResult<SessionHandle>).value.close()
       } finally {
         await dispose()
       }
     })
 
-    it('crash recovery: load preserves an interrupted (unclosed) turn and closes it with turn/end {interrupted}', async () => {
-      const { persistence, dispose } = await make()
+    it('duplicate create rejects against a materialized artifact seen by a fresh instance', async () => {
+      const backend = await make()
       try {
-        const m = meta('interrupted')
-        await persistence.create(m)
-        await persistence.append(m.id, oneTurnLog()) // turn 1, committed (seqs 0..5)
-        // A second turn that crashed mid-flight: turn/start + step/start were
-        // durably written, but no step/end / turn/end ever arrived.
-        await persistence.append(m.id, [
-          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-          { type: 'step/start', seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
-        ])
-        const beforeRepair = (await persistence.listSnapshots())
-          .find(snapshot => snapshot.header.id === m.id)?.revision
+        if (backend.reopen === undefined) return
+        const m = meta('dup-stored', '/work')
+        const handle = await backend.persistence.create(m)
+        await handle.append(oneTurnLog())
+        await handle.close()
 
-        const inspected = await persistence.inspect(m.id)
-        const afterInspect = (await persistence.listSnapshots())
-          .find(snapshot => snapshot.header.id === m.id)?.revision
-        expect(afterInspect).toBe(beforeRepair)
-        expect(inspected.events.map(e => e.type)).toEqual([
-          'turn/start', 'user/message', 'step/start', 'assistant/message', 'step/end', 'turn/end',
-          'turn/start', 'step/start', 'step/end', 'turn/end',
-        ])
-
-        // load PRESERVES the interrupted turn's events (a turn can be huge — they
-        // must not be truncated) and closes the orphaned turn with synthetic
-        // boundary events: step/end (the step was open) then turn/end {interrupted}.
-        const loaded = await persistence.load(m.id)
-        const afterRepair = (await persistence.listSnapshots())
-          .find(snapshot => snapshot.header.id === m.id)?.revision
-        expect(afterRepair).not.toBe(beforeRepair)
-        expect(loaded.events.map(e => e.type)).toEqual([
-          'turn/start', 'user/message', 'step/start', 'assistant/message', 'step/end', 'turn/end', // turn 1
-          'turn/start', 'step/start', 'step/end', 'turn/end', // turn 2: real events + synthetic closers
-        ])
-        expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
-        const last = loaded.events.at(-1)!
-        expect(last.type === 'turn/end' && last.data.reason).toEqual({ kind: 'interrupted' })
-
-        // The closed log is durable and continuable: a fresh append continues at
-        // the balanced length (seq 10), and a reload round-trips identically.
-        await persistence.append(m.id, [
-          { type: 'turn/start', seq: SessionSeq(10), time: 9, data: { turn: 3 } },
-          { type: 'turn/end', seq: SessionSeq(11), time: 10, data: { turn: 3, reason: { kind: 'completed' } } },
-        ])
-        const reloaded = await persistence.load(m.id)
-        expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
-      } finally {
-        await dispose()
-      }
-    })
-
-    it('crash recovery: an unstarted assistant tool request gets a retryable synthetic result', async () => {
-      const { persistence, dispose } = await make()
-      try {
-        const m = meta('interrupted-toolcall')
-        await persistence.create(m)
-        await persistence.append(m.id, oneTurnLog()) // turn 1, committed (seqs 0..5)
-        // Turn 2 crashed AFTER the assistant message asked for a tool call but
-        // BEFORE the tool/result was written (the loop runs tools after logging
-        // the assistant message — a process killed mid-tool lands exactly here).
-        await persistence.append(m.id, [
-          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-          { type: 'step/start', seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
-          { type: 'assistant/message', seq: SessionSeq(8), time: 9, data: {
-            turn: 2, step: 1,
-            message: createMessage({
-              role: 'assistant',
-              content: [
-                { type: 'tool-call', id: ToolCallId('call-x'), name: 'bash', arguments: '{}' },
-              ],
-              source: {
-                kind: 'model',
-                ...{ provider: 'mock', model: 'mock' },
-              },
-            }),
-          }, surfaceOp: 'append' },
-        ])
-
-        const loaded = await persistence.load(m.id)
-        // The orphaned call is answered by a synthetic error tool/result BEFORE
-        // step/end + turn/end {interrupted}, so the step (and turn) are balanced
-        // and a resumed session derives a valid transcript (no dangling call).
-        expect(loaded.events.map(e => e.type)).toEqual([
-          'turn/start', 'user/message', 'step/start', 'assistant/message', 'step/end', 'turn/end', // turn 1
-          'turn/start', 'step/start', 'assistant/message', 'tool/result', 'step/end', 'turn/end', // turn 2
-        ])
-        const synthetic = loaded.events.find(e => e.type === 'tool/result')
-        expect(synthetic?.type === 'tool/result' && synthetic.data).toMatchObject({
-          message: {
-            source: { kind: 'tool', callId: ToolCallId('call-x') },
-            content: [{ type: 'tool-result', toolCallId: ToolCallId('call-x'), isError: true }],
-          },
-          error: { code: TOOL_NOT_STARTED },
-        })
-        // The synthetic result carries the SAME callId as the orphaned tool-call,
-        // so deriveMessages() pairs them — no provider-invalid dangling call.
-        const call = loaded.events.findLast(e => e.type === 'assistant/message')
-        const callId = call?.type === 'assistant/message'
-          && call.data.message.content.find(b => b.type === 'tool-call')
-        expect(callId && callId.type === 'tool-call' && callId.id).toBe(ToolCallId('call-x'))
-      } finally {
-        await dispose()
-      }
-    })
-
-    it('crash recovery: a recorded tool call with no result tells the model to assess retry risk', async () => {
-      const { persistence, dispose } = await make()
-      try {
-        const m = meta('unknown-tool-outcome')
-        await persistence.create(m)
-        await persistence.append(m.id, [
-          { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
-          { type: 'step/start', seq: SessionSeq(1), time: 2, data: { turn: 1, step: 1 } },
-          { type: 'assistant/message', seq: SessionSeq(2), time: 3, data: {
-            turn: 1, step: 1,
-            message: createMessage({
-              role: 'assistant',
-              content: [
-                { type: 'tool-call', id: ToolCallId('call-risk'), name: 'write', arguments: '{}' },
-              ],
-              source: {
-                kind: 'model',
-                ...{ provider: 'mock', model: 'mock' },
-              },
-            }),
-          }, surfaceOp: 'append' },
-          { type: 'tool/call', seq: SessionSeq(3), time: 4, data: { turn: 1, step: 1, callId: ToolCallId('call-risk'), name: 'write', arguments: '{}' } },
-        ])
-
-        const loaded = await persistence.load(m.id)
-        const synthetic = loaded.events.find(e => e.type === 'tool/result')
-        expect(synthetic?.type === 'tool/result' && synthetic.data.error).toEqual({
-          name: 'ToolOutcomeUnknownError', code: TOOL_OUTCOME_UNKNOWN,
-        })
-        if (synthetic?.type !== 'tool/result' || synthetic.data.message.content[0].content[0]?.type !== 'text') {
-          throw new Error('expected a text tool result')
+        const reopened = await backend.reopen()
+        try {
+          await expect(reopened.persistence.create(meta('dup-stored', '/work')))
+            .rejects.toBeInstanceOf(SessionAlreadyExistsError)
+        } finally {
+          await reopened.dispose()
         }
-        expect(synthetic.data.message.content[0].content[0].text).toContain('retry only if the operation is read-only or idempotent')
-        expect(synthetic.data.message.content[0].content[0].text).toContain('if it may have side effects, first verify external state or ask the user')
-        const resumed = Session.create(m.id, loaded.events, loaded.meta)
-        const resumedResult = resumed.deriveMessages().find(message => message.content.some(block => block.type === 'tool-result'))
-        expect(resumedResult?.content[0]).toMatchObject({
-          type: 'tool-result', toolCallId: ToolCallId('call-risk'), isError: true,
-        })
+      } finally {
+        await backend.dispose()
+      }
+    })
+
+    it('open of an absent session rejects with SessionPersistenceNotFoundError for both accesses', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        await expect(persistence.open(SessionId('absent'), 'read')).rejects.toBeInstanceOf(SessionPersistenceNotFoundError)
+        await expect(persistence.open(SessionId('absent'), 'write')).rejects.toBeInstanceOf(SessionPersistenceNotFoundError)
       } finally {
         await dispose()
       }
     })
 
-    it('list() excludes a created-but-never-appended (zero-event) session', async () => {
+    it('write ownership is single-holder per instance and released by close', async () => {
       const { persistence, dispose } = await make()
       try {
-        await persistence.create(meta('empty'))
-        expect((await persistence.list()).map(m => m.id)).not.toContain(SessionId('empty'))
-        expect((await persistence.listSnapshots()).map(snapshot => snapshot.header.id))
-          .not.toContain(SessionId('empty'))
+        const m = meta('owned')
+        const creator = await persistence.create(m)
+        // The creator holds ownership even before materialization.
+        await expect(persistence.open(m.id, 'write')).rejects.toBeInstanceOf(SessionAlreadyOwnedError)
+        await creator.append(oneTurnLog())
+        await expect(persistence.open(m.id, 'write')).rejects.toBeInstanceOf(SessionAlreadyOwnedError)
+        await creator.close()
+
+        // After close, a new write handle continues at the stored next-seq.
+        const writer = await persistence.open(m.id, 'write')
+        await writer.append(secondTurn())
+        expect((await writer.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+        await writer.close()
       } finally {
         await dispose()
       }
     })
 
-    it('rejects pre-aborted observation reads with the exact cancellation reason', async () => {
+    it('a read handle refuses append and flush with SessionReadOnlyError', async () => {
       const { persistence, dispose } = await make()
       try {
-        const reason = new Error('persistence observation cancelled')
-        const controller = new AbortController()
-        await expect(persistence.listSnapshots(controller.signal)).resolves.toEqual([])
-        controller.abort(reason)
+        const m = meta('read-only')
+        const writer = await persistence.create(m)
+        await writer.append(oneTurnLog())
+        await writer.close()
 
-        await expect(persistence.list(controller.signal)).rejects.toBe(reason)
-        await expect(persistence.listSnapshots(controller.signal)).rejects.toBe(reason)
-        await expect(persistence.inspect(SessionId('cancelled-inspect'), controller.signal))
-          .rejects.toBe(reason)
-        await expect(persistence.readFrom(
-          SessionId('cancelled-read-from'),
-          SessionLogOffset(0),
-          controller.signal,
-        ))
-          .rejects.toBe(reason)
+        const reader = await persistence.open(m.id, 'read')
+        expect(reader.access).toBe('read')
+        await expect(reader.append(secondTurn())).rejects.toBeInstanceOf(SessionReadOnlyError)
+        await expect(reader.flush()).rejects.toBeInstanceOf(SessionReadOnlyError)
+        // The refusals mutated nothing.
+        expect(await reader.read()).toEqual(oneTurnLog())
+        await reader.close()
       } finally {
         await dispose()
       }
     })
 
-    it('readFrom returns exactly the stored suffix from the requested seq, without mutating the log', async () => {
+    it('operations on a closed handle reject; close is idempotent; asyncDispose releases ownership', async () => {
       const { persistence, dispose } = await make()
       try {
-        const m = meta('read-from', '/work')
-        const log = oneTurnLog()
-        await persistence.create(m)
-        await persistence.append(m.id, log)
+        const m = meta('closed')
+        const handle = await persistence.create(m)
+        await handle.append(oneTurnLog())
+        await handle.close()
+        await handle.close()
+        await expect(handle.read()).rejects.toBeInstanceOf(SessionHandleClosedError)
+        await expect(handle.append(secondTurn())).rejects.toBeInstanceOf(SessionHandleClosedError)
+        await expect(handle.flush()).rejects.toBeInstanceOf(SessionHandleClosedError)
 
-        const whole = await persistence.readFrom(m.id, SessionLogOffset(0))
-        expect(whole.meta).toMatchObject({ id: m.id, cwd: '/work' })
-        expect(whole.fromSeq).toBe(0)
-        expect(whole.events).toEqual(log)
-
-        const suffix = await persistence.readFrom(m.id, SessionLogOffset(3))
-        expect(suffix.fromSeq).toBe(3)
-        expect(suffix.events).toEqual(log.slice(3))
-        expect(suffix.events[0]?.seq).toBe(3)
-
-        // At/past the stored end: an empty tail, never an error.
-        await expect(persistence.readFrom(m.id, SessionLogOffset(log.length)))
-          .resolves.toMatchObject({ fromSeq: log.length, events: [] })
-        await expect(persistence.readFrom(m.id, SessionLogOffset(log.length + 100)))
-          .resolves.toMatchObject({ fromSeq: log.length + 100, events: [] })
-
-        // Non-mutating: an interrupted-turn log is served as stored, no closers.
-        await persistence.append(m.id, [
-          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-        ])
-        const tail = await persistence.readFrom(m.id, SessionLogOffset(6))
-        expect(tail.events.map(event => event.type)).toEqual(['turn/start'])
-
-        await expect(persistence.readFrom(SessionId('absent-read-from'), SessionLogOffset(0)))
-          .rejects.toThrow('not found')
-        await expect(persistence.readFrom(m.id, -1 as SessionLogOffsetType))
-          .rejects.toThrow('non-negative safe integer')
-        await expect(persistence.readFrom(m.id, 1.5 as SessionLogOffsetType))
-          .rejects.toThrow('non-negative safe integer')
+        {
+          await using writer = await persistence.open(m.id, 'write')
+          await writer.append(secondTurn())
+        }
+        // Leaving the block disposed the handle, so ownership is free again.
+        const reopened = await persistence.open(m.id, 'write')
+        await reopened.close()
       } finally {
         await dispose()
       }
     })
 
-    it('lists stable lightweight revisions that change after an append', async () => {
+    it('service-level flush materializes every active write handle and counts a closing one as flushed', async () => {
+      const backend = await make()
+      try {
+        const materialized = await backend.persistence.create(meta('flush-all'))
+        const abandoned = await backend.persistence.create(meta('flush-all-closing'))
+        // Close starts before the barrier: the swept handle refuses its flush,
+        // which counts as flushed — close itself drained durably.
+        const closing = abandoned.close()
+        await backend.persistence.flush()
+        await closing
+
+        if (backend.reopen !== undefined) {
+          const reopened = await backend.reopen()
+          try {
+            // The barrier materialized the empty session durably...
+            expect(await reopened.persistence.stat(SessionId('flush-all'))).toBeDefined()
+            // ...while the one that closed unappended never existed.
+            expect(await reopened.persistence.stat(SessionId('flush-all-closing'))).toBeUndefined()
+          } finally {
+            await reopened.dispose()
+          }
+        }
+        await materialized.close()
+      } finally {
+        await backend.dispose()
+      }
+    })
+
+    it('a created-but-unappended session is visible to this instance and invisible to a fresh one', async () => {
+      const backend = await make()
+      try {
+        const m = meta('lazy', '/work')
+        const creator = await backend.persistence.create(m)
+        // The creator's own reads see the empty log before materialization.
+        expect(await creator.read()).toEqual([])
+
+        const snapshot = await backend.persistence.stat(m.id)
+        expect(snapshot?.header).toMatchObject(m)
+        expect((await backend.persistence.list()).map(s => s.header.id)).toContain(m.id)
+        const reader = await backend.persistence.open(m.id, 'read')
+        expect(await reader.read()).toEqual([])
+        await reader.close()
+
+        if (backend.reopen !== undefined) {
+          const reopened = await backend.reopen()
+          try {
+            expect(await reopened.persistence.stat(m.id)).toBeUndefined()
+            expect((await reopened.persistence.list()).map(s => s.header.id)).not.toContain(m.id)
+            await expect(reopened.persistence.open(m.id, 'read')).rejects.toBeInstanceOf(SessionPersistenceNotFoundError)
+          } finally {
+            await reopened.dispose()
+          }
+        }
+        await creator.close()
+      } finally {
+        await backend.dispose()
+      }
+    })
+
+    it('close without an append erases the created session from this instance', async () => {
       const { persistence, dispose } = await make()
       try {
-        const m = meta('s2')
-        await persistence.create(m)
-        await persistence.append(m.id, oneTurnLog())
-        expect((await persistence.list()).map(x => x.id)).toContain(m.id)
-        const first = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
-        const repeated = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
-        expect(first).toBeDefined()
-        expect(repeated?.revision).toBe(first?.revision)
+        const m = meta('never-was')
+        const creator = await persistence.create(m)
+        await creator.close()
 
-        await persistence.append(m.id, [{
-          type: 'turn/start',
-          seq: SessionSeq(6),
-          time: 7,
-          data: { turn: 2 },
-        }])
-        const changed = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
-        expect(changed?.revision).not.toBe(first?.revision)
+        expect(await persistence.stat(m.id)).toBeUndefined()
+        expect((await persistence.list()).map(s => s.header.id)).not.toContain(m.id)
+        await expect(persistence.open(m.id, 'read')).rejects.toBeInstanceOf(SessionPersistenceNotFoundError)
       } finally {
         await dispose()
       }
     })
 
-    it('append rejects a batch whose first seq does not match the stored next-seq', async () => {
+    it('flush materializes an empty session durably for a fresh instance', async () => {
+      const backend = await make()
+      try {
+        if (backend.reopen === undefined) return
+        const m = meta('durable-empty', '/work')
+        const creator = await backend.persistence.create(m)
+        await creator.flush()
+        await creator.close()
+
+        const reopened = await backend.reopen()
+        try {
+          expect((await reopened.persistence.list()).map(s => s.header.id)).toContain(m.id)
+          expect((await reopened.persistence.stat(m.id))?.header).toMatchObject(m)
+          const reader = await reopened.persistence.open(m.id, 'read')
+          expect(await reader.read()).toEqual([])
+          await reader.close()
+        } finally {
+          await reopened.dispose()
+        }
+      } finally {
+        await backend.dispose()
+      }
+    })
+
+    it('freshness: reads started after an append resolves observe that prefix on any handle', async () => {
       const { persistence, dispose } = await make()
       try {
-        const m = meta('s3')
-        await persistence.create(m)
-        await persistence.append(m.id, oneTurnLog()) // seqs 0..5, next-seq = 6
-        // A re-append of an already-stored seq must be rejected, not duplicated.
-        const restated = oneTurnLog()
-        await expect(persistence.append(m.id, restated)).rejects.toThrow()
+        const m = meta('fresh')
+        const writer = await persistence.create(m)
+        await writer.append(oneTurnLog())
+
+        const before = await persistence.open(m.id, 'read')
+        expect(await before.read()).toEqual(oneTurnLog())
+
+        await writer.append(secondTurn())
+        // Both a pre-existing read handle and a freshly opened one observe the
+        // append once it has resolved.
+        expect((await before.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+        const after = await persistence.open(m.id, 'read')
+        expect((await after.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+        await before.close()
+        await after.close()
+        await writer.close()
       } finally {
         await dispose()
       }
     })
 
-    it('append rejects a mid-batch seq gap', async () => {
+    it('a fresh instance continues the stored log at the committed next-seq', async () => {
+      const backend = await make()
+      try {
+        if (backend.reopen === undefined) return
+        const m = meta('continue', '/work')
+        const creator = await backend.persistence.create(m)
+        await creator.append(oneTurnLog())
+        await creator.close()
+
+        const reopened = await backend.reopen()
+        try {
+          const writer = await reopened.persistence.open(m.id, 'write')
+          await writer.append(secondTurn())
+          expect((await writer.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+          await writer.close()
+        } finally {
+          await reopened.dispose()
+        }
+      } finally {
+        await backend.dispose()
+      }
+    })
+
+    it('append rejects a batch that does not contiguously continue the log, naming the expected seq', async () => {
       const { persistence, dispose } = await make()
       try {
-        const m = meta('s4')
-        await persistence.create(m)
+        const m = meta('contiguity')
+        const handle = await persistence.create(m)
+        await handle.append(oneTurnLog()) // seqs 0..5, next-seq = 6
+        // A re-append of an already-stored seq is rejected, not duplicated.
+        await expect(handle.append(oneTurnLog())).rejects.toThrow(/expected 6/)
+        // A mid-batch gap is rejected as a whole.
         const gapped: SessionEvent[] = [
-          { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
-          { type: 'step/start', seq: SessionSeq(2), time: 2, data: { turn: 1, step: 1 } }, // gap: missing seq 1
+          { type: 'turn/start', seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+          { type: 'turn/end', seq: SessionSeq(8), time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
         ]
-        await expect(persistence.append(m.id, gapped)).rejects.toThrow()
+        await expect(handle.append(gapped)).rejects.toThrow(/expected 7/)
+        // Neither rejection changed the stored log.
+        expect((await handle.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5])
+        await handle.close()
       } finally {
         await dispose()
       }
     })
 
-    it('append rejects non-JSON-serializable event data, naming the event type', async () => {
+    it('append rejects non-JSON-serializable event data without storing anything', async () => {
       const { persistence, dispose } = await make()
       try {
-        // Every value `isJsonValue` rejects must be rejected by the backend, not just BigInt —
-        // otherwise a backend could pass this contract while still accepting values that
-        // corrupt the durable round-trip. Each value is carried in a plugin-added field on one
-        // user message so the contract covers the complete JSON-value boundary.
-        const cyclic: Record<string, unknown> = { type: 'text', text: 'x' }
-        cyclic['self'] = cyclic
-        const badValues: unknown[] = [
-          1n,                  // BigInt
-          undefined,           // dropped by JSON.stringify
-          Infinity,            // → null
-          () => 0,             // function
-          Symbol('s'),         // symbol
-          new Map(),           // exotic object
-          cyclic,              // circular ref
-        ]
-        for (const [i, bad] of badValues.entries()) {
-          // A fresh session per value isolates each rejection (a rejected append
-          // must leave no state behind, but isolating keeps the assertion clean).
-          const mi = meta(`s5-${i}`)
-          await persistence.create(mi)
-          const events = [
-            {
-              type: 'user/message',
-              seq: SessionSeq(0),
-              time: 1,
-              data: {
-                id: MessageId(`invalid-json-${i}`),
-                role: 'user',
-                content: [{ type: 'text', text: 'x' }],
-                source: { kind: 'user' },
-                extra: bad,
-              },
-            },
-          ] as unknown as SessionEvent[]
-          await expect(persistence.append(mi.id, events)).rejects.toThrow(/losslessly JSON-serializable/)
+        const m = meta('non-json')
+        const handle = await persistence.create(m)
+        const bad = (extra: unknown): SessionEvent[] => [{
+          type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1, extra },
+        }] as unknown as SessionEvent[]
+        await expect(handle.append(bad(1n))).rejects.toThrow(TypeError)
+        await expect(handle.append(bad(1n))).rejects.toThrow(/losslessly JSON-serializable/)
+        await expect(handle.append(bad(undefined))).rejects.toThrow(/losslessly JSON-serializable/)
+        // The rejected batches left no events behind: seq 0 is still free.
+        await handle.append(oneTurnLog())
+        expect(await handle.read()).toEqual(oneTurnLog())
+        await handle.close()
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('vocabulary fail-closed: an unknown stored event type refuses reads and write opens', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('foreign-vocabulary')
+        const handle = await persistence.create(m)
+        // The append side is permissive — a newer producer's event type is
+        // stored verbatim…
+        await handle.append(oneTurnLog())
+        await handle.append([
+          { type: 'mystery/event', seq: SessionSeq(6), time: 7, data: { payload: true } },
+        ] as unknown as SessionEvent[])
+        await handle.close()
+
+        // …but this build refuses to interpret the stored log: a write open
+        // rejects, and a read handle (or its first read) rejects.
+        await expect(persistence.open(m.id, 'write')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
+        // The failed write open released its ownership claim: retrying yields
+        // the same refusal, never SessionAlreadyOwnedError.
+        await expect(persistence.open(m.id, 'write')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
+        const readFailure = await persistence.open(m.id, 'read').then(
+          async (reader) => {
+            try {
+              return await reader.read().then(() => undefined, (error: unknown) => error)
+            } finally {
+              await reader.close()
+            }
+          },
+          (error: unknown) => error,
+        )
+        expect(readFailure).toBeInstanceOf(SessionFormatUnsupportedError)
+        expect((readFailure as Error).message).toContain('mystery/event')
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('a torn physical tail is never served and is durably truncated by the write path', async () => {
+      const backend = await make()
+      try {
+        if (backend.reopen === undefined || backend.corruptTail === undefined) return
+        const m = meta('torn', '/work')
+        const creator = await backend.persistence.create(m)
+        await creator.append(oneTurnLog())
+        await creator.close()
+        await backend.corruptTail(m.id, m.cwd)
+
+        // A reader over the corrupted artifact serves only the committed prefix.
+        const readerInstance = await backend.reopen()
+        try {
+          const reader = await readerInstance.persistence.open(m.id, 'read')
+          expect(await reader.read()).toEqual(oneTurnLog())
+          await reader.close()
+
+          // A write open + first append durably truncates the torn tail and
+          // continues at the committed next-seq.
+          const writer = await readerInstance.persistence.open(m.id, 'write')
+          await writer.append(secondTurn())
+          expect((await writer.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+          await writer.close()
+        } finally {
+          await readerInstance.dispose()
         }
+
+        // The repaired log is intact for the next instance.
+        const verifyInstance = await backend.reopen()
+        try {
+          const verify = await verifyInstance.persistence.open(m.id, 'read')
+          expect((await verify.read()).map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+          await verify.close()
+        } finally {
+          await verifyInstance.dispose()
+        }
+      } finally {
+        await backend.dispose()
+      }
+    })
+
+    it('stat and list agree on stable revisions that change after an append', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('revisions', '/work')
+        const writer = await persistence.create(m)
+        await writer.append(oneTurnLog())
+
+        const statFirst = await persistence.stat(m.id)
+        const statAgain = await persistence.stat(m.id)
+        const listFirst = (await persistence.list()).find(s => s.header.id === m.id)
+        expect(statFirst).toBeDefined()
+        expect(statAgain?.revision).toBe(statFirst?.revision)
+        expect(listFirst?.revision).toBe(statFirst?.revision)
+
+        await writer.append(secondTurn())
+        const statChanged = await persistence.stat(m.id)
+        expect(statChanged?.revision).not.toBe(statFirst?.revision)
+        const listChanged = (await persistence.list()).find(s => s.header.id === m.id)
+        expect(listChanged?.revision).toBe(statChanged?.revision)
+
+        // Snapshot headers carry the stored header, identically everywhere.
+        const reader = await persistence.open(m.id, 'read')
+        expect(statChanged?.header).toEqual(reader.header)
+        expect(listChanged?.header).toEqual(reader.header)
+        expect(statChanged?.header).toMatchObject(m)
+        await reader.close()
+        await writer.close()
+
+        expect(await persistence.stat(SessionId('absent-stat'))).toBeUndefined()
       } finally {
         await dispose()
       }
diff --git a/packages/session/session-persistence/tests/coordinator-contract.ts b/packages/session/session-persistence/tests/coordinator-contract.ts
deleted file mode 100644
index 587d7ff1c3..0000000000
--- a/packages/session/session-persistence/tests/coordinator-contract.ts
+++ /dev/null
@@ -1,1593 +0,0 @@
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
-/**
- * Shared write-path orchestration contract for backends using {@link PersistenceCoordinator}.
- * Unlike the public storage-semantics suite in `contract.ts`, it covers SessionStore event wiring,
- * lazy creation, fork seed persistence, four adoption/collision cases, crash-tail repair, reload,
- * flush, and disposal quiescence through public APIs rather than storage primitives.
- *
- * Each real backend supplies a shared storage scope and optional torn-tail injector; backend specs
- * retain only storage-mechanics tests, while these scenarios run once per backend.
- * @module @deepseek-ai/dsh-session-persistence/tests/coordinator-contract
- */
-
-import { describe, expect, it, vi } from 'vitest'
-import { Context, type Fiber } from '@deepseek-ai/cordis'
-import { scopeTarget } from '@deepseek-ai/dsh-scope'
-import SessionStore, {
-  SESSION_FORMAT_VERSION,
-  Session,
-  SessionId,
-  SessionLogOffset,
-  SessionSeq,
-} from '@deepseek-ai/dsh-session'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { meta, oneTurnLog, appendLog } from './contract.ts'
-
-/**
- * The backend-specific capabilities the orchestration suite needs beyond the
- * public service API. A fresh fixture is created per test (isolated storage);
- * the suite mounts/disposes backend instances on it and cleans it up at the end.
- */
-export interface CoordinatorFixture {
-  /** Mount the real backend through `ctx.plugin` over shared storage and return only that fiber. */
-  mount: (ctx: Context) => Promise<Fiber>
-
-  /**
-   * Inject a never-committed partial record after the durable region so `loadCore` reaches
-   * `commitRepair`. Omit only when the backend structurally cannot produce torn tails.
-   */
-  corruptTail?: (id: SessionId, cwd: string | undefined) => Promise<void>
-
-  /** Tear down the storage scope (remove the temp dir / file). */
-  cleanup: () => Promise<void>
-}
-
-/** A constant absolute cwd; JSONL keys directories off it and memory ignores it. */
-const WORK = '/w'
-const OTHER = '/other'
-
-/** Append a whole event log to a live session, event by event (drives session/event). */
-function send(session: Session, events: readonly SessionEvent[]): void {
-  appendLog(session, events)
-}
-
-/** A valid persisted log from immediately before messages gained wrappers and identities. */
-export function legacyMessageLog(): SessionEvent[] {
-  return [
-    { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
-    {
-      type: 'user/message',
-      seq: 1,
-      time: 2,
-      data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } },
-      surfaceOp: 'append',
-    },
-    { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
-    {
-      type: 'assistant/message',
-      seq: 3,
-      time: 4,
-      data: {
-        turn: 1,
-        step: 1,
-        content: [{ type: 'tool-call', id: 'call-1', name: 'read', arguments: '{}' }],
-        provenance: { provider: 'mock', model: 'mock' },
-      },
-      surfaceOp: 'append',
-    },
-    {
-      type: 'tool/call',
-      seq: 4,
-      time: 5,
-      data: { turn: 1, step: 1, callId: 'call-1', name: 'read', arguments: '{}' },
-    },
-    {
-      type: 'tool/result',
-      seq: 5,
-      time: 6,
-      data: {
-        turn: 1,
-        step: 1,
-        callId: 'call-1',
-        content: [{ type: 'text', text: 'full result' }],
-        isError: false,
-      },
-      sourceEventSeqs: [4],
-      surfaceOp: 'append',
-    },
-    {
-      type: 'tool/result',
-      seq: 6,
-      time: 8,
-      data: {
-        turn: 1,
-        step: 1,
-        callId: 'call-1',
-        content: [{ type: 'text', text: 'pruned' }],
-        isError: false,
-      },
-      sourceEventSeqs: [5],
-      surfaceOp: { op: 'replace', start: 5, end: 5 },
-    },
-    { type: 'step/end', seq: 7, time: 9, data: { turn: 1, step: 1 } },
-    { type: 'turn/end', seq: 8, time: 10, data: { turn: 1, reason: { kind: 'completed' } } },
-  ] as unknown as SessionEvent[]
-}
-
-/** A complete log in the durable event vocabulary of the react-loop refactor base. */
-export function preReactLoopLog(): SessionEvent[] {
-  const prompt = createUserMessage({
-    content: [{ type: 'text', text: 'old prompt' }],
-    source: { kind: 'user' },
-  })
-  const steering = createUserMessage({
-    content: [{ type: 'text', text: 'old steering' }],
-    source: { kind: 'user' },
-  })
-  return [
-    {
-      type: 'turn/start', seq: 0, time: 1,
-      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
-    },
-    { type: 'user/message', seq: 1, time: 2, data: prompt, surfaceOp: 'append' },
-    { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
-    {
-      type: 'steering/message', seq: 3, time: 4,
-      data: { turn: 1, message: steering },
-      surfaceOp: 'append',
-    },
-    { type: 'step/end', seq: 4, time: 5, data: { turn: 1, step: 1 } },
-    { type: 'turn/end', seq: 5, time: 6, data: { turn: 1, reason: { kind: 'completed' } } },
-    { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'retry' } } },
-    { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } },
-    { type: 'step/end', seq: 8, time: 9, data: { turn: 2, step: 1 } },
-    {
-      type: 'turn/end', seq: 9, time: 10,
-      data: {
-        turn: 2,
-        reason: {
-          kind: 'error',
-          step: 1,
-          failure: { message: 'old provider failure', code: 'SERVER' },
-        },
-      },
-    },
-    {
-      type: 'turn/start', seq: 10, time: 11,
-      data: { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } },
-    },
-    { type: 'turn/end', seq: 11, time: 12, data: { turn: 3, reason: { kind: 'aborted' } } },
-    {
-      type: 'turn/start', seq: 12, time: 13,
-      data: { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } },
-    },
-    { type: 'turn/end', seq: 13, time: 14, data: { turn: 4, reason: { kind: 'disposed' } } },
-    {
-      type: 'turn/start', seq: 14, time: 15,
-      data: { turn: 5, trigger: { kind: 'message', source: { kind: 'user' } } },
-    },
-    { type: 'step/start', seq: 15, time: 16, data: { turn: 5, step: 1 } },
-    { type: 'step/end', seq: 16, time: 17, data: { turn: 5, step: 1 } },
-    {
-      type: 'turn/end', seq: 17, time: 18,
-      data: { turn: 5, reason: { kind: 'error', step: 1, message: 'old thrown value' } },
-    },
-    {
-      type: 'turn/start', seq: 18, time: 19,
-      data: { turn: 6, trigger: { kind: 'message', source: { kind: 'user' } } },
-    },
-    {
-      type: 'turn/end', seq: 19, time: 20,
-      data: {
-        turn: 6,
-        reason: {
-          kind: 'error',
-          step: 0,
-          failure: {
-            message: 'old detailed provider failure',
-            code: 'RATE_LIMIT',
-            status: 429,
-            providerRetryAfterMs: 1000,
-            requestId: 'request-1',
-          },
-        },
-      },
-    },
-    {
-      type: 'turn/start', seq: 20, time: 21,
-      data: { turn: 7, trigger: { kind: 'message', source: { kind: 'user' } } },
-    },
-    {
-      type: 'turn/end', seq: 21, time: 22,
-      data: { turn: 7, reason: { kind: 'error', step: 0, message: 'old coded error', code: 'CODED' } },
-    },
-  ] as unknown as SessionEvent[]
-}
-
-/** A live session created inside its OWN fiber, so it survives a backend reload. */
-async function liveSessionInFiber(
-  ctx: Context, id: string, cwd: string | undefined,
-): Promise<Session> {
-  let session!: Session
-  await ctx.plugin(Object.assign((inner: Context) => {
-    session = inner.sessions.create(SessionId(id), cwd !== undefined ? { meta: { cwd } } : undefined)
-  }, { inject: ['sessions'] }))
-  return session
-}
-
-/**
- * Run the coordinator orchestration suite against a backend. `makeFixture()`
- * MUST return a fresh fixture (isolated storage) each call.
- */
-export function runCoordinatorContract(name: string, makeFixture: () => Promise<CoordinatorFixture>): void {
-  describe(`PersistenceCoordinator orchestration: ${name}`, () => {
-    /** Mount SessionStore + a backend instance on a fresh context over the fixture's storage. */
-    async function freshCtx(fix: CoordinatorFixture): Promise<{ ctx: Context; fiber: Fiber }> {
-      const ctx = new Context()
-      await ctx.plugin(SessionStore)
-      const fiber = await fix.mount(ctx)
-      return { ctx, fiber }
-    }
-
-    // --- write path: live session → flush → reload ---
-
-    it('persists a live session driven through the store, surviving reload', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const session = ctx.sessions.create(SessionId('live'), { meta: { cwd: WORK } })
-        send(session, oneTurnLog())
-        await ctx.sessions.flush(session)
-
-        const loaded = await ctx.sessionPersistence.load(SessionId('live'))
-        expect(loaded.events).toHaveLength(6)
-        expect(loaded.meta.cwd).toBe(WORK)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('rejects crash-repair load while a live session owns the persisted prefix', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      let session!: Session
-      const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        session = inner.sessions.create(SessionId('live-load'), { meta: { cwd: WORK } })
-      }, { inject: ['sessions'] }))
-      try {
-        session.append('turn/start', { turn: 1 })
-        await ctx.sessions.flush(session)
-
-        await expect(ctx.sessionPersistence.load(session.id))
-          .rejects.toThrow(`cannot load session "${session.id}" while its live turn is open`)
-
-        send(session, oneTurnLog().slice(1))
-        await ctx.sessions.flush(session)
-        await sessionFiber.dispose()
-
-        await vi.waitFor(async () => {
-          const loaded = await ctx.sessionPersistence.load(session.id)
-          expect(loaded.events.map(event => event.type)).toEqual(oneTurnLog().map(event => event.type))
-          expect(loaded.events.at(-1)).toMatchObject({
-            type: 'turn/end',
-            data: { reason: { kind: 'completed' } },
-          })
-        })
-      } finally {
-        await sessionFiber.dispose()
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('rechecks live ownership after a cold load enters the per-id chain', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const id = SessionId('queued-load-live-race')
-        const header = meta(id, WORK)
-        const start: SessionEvent = {
-          type: 'turn/start',
-          seq: SessionSeq(0),
-          time: 1,
-          data: { turn: 1 },
-        }
-        await ctx.sessionPersistence.create(header)
-        await ctx.sessionPersistence.append(id, [start])
-
-        const loading = ctx.sessionPersistence.load(id)
-        const live = ctx.sessions.create(id, { seed: [start], meta: header })
-        await expect(loading).rejects.toThrow(/live turn is open/)
-
-        live.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(live)
-        const loaded = await ctx.sessionPersistence.load(id)
-        // The constructor's end-seed event persisted between the stored
-        // turn/start and the turn/end appended live.
-        expect(loaded.events.map(event => event.type)).toEqual(['turn/start', 'session/end-seed', 'turn/end'])
-        expect(loaded.events.at(-1)).toMatchObject({
-          type: 'turn/end',
-          data: { reason: { kind: 'completed' } },
-        })
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('does not load an unmaterialized empty live session', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const session = ctx.sessions.create(SessionId('empty-live'), { meta: { cwd: WORK } })
-        await expect(ctx.sessionPersistence.load(session.id)).rejects.toThrow(/not found/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('preserves the exact inherited cut through load, inspect, suffix read, prepare, and reopen', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      const inherited = oneTurnLog()
-      try {
-        let session!: Session
-        const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
-          session = inner.sessions.create(SessionId('forked-child'), {
-            seed: inherited,
-            inheritedEventCount: SessionLogOffset(inherited.length),
-            meta: { cwd: WORK, isSeeded: true },
-          })
-        }, { inject: ['sessions'] }))
-        await ctx.sessions.flush(session)
-        await sessionFiber.dispose()
-
-        const loaded = await ctx.sessionPersistence.load(SessionId('forked-child'))
-        expect(loaded.meta.isSeeded).toBe(true)
-        expect(loaded.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
-        expect((await ctx.sessionPersistence.inspect(SessionId('forked-child'))).inheritedEventCount)
-          .toBe(SessionLogOffset(inherited.length))
-        const suffix = await ctx.sessionPersistence.readFrom(
-          SessionId('forked-child'),
-          SessionLogOffset(3),
-        )
-        expect(suffix.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
-        expect(suffix.fromSeq).toBe(3)
-        expect(suffix.events[0]?.seq).toBe(3)
-        const preparation = await ctx.sessionPersistence.prepare(SessionId('forked-child'))
-        expect(preparation.session.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
-        preparation[Symbol.dispose]()
-
-        await fiber.dispose()
-        const reopened = await freshCtx(fix)
-        try {
-          const reopenedLoad = await reopened.ctx.sessionPersistence.load(SessionId('forked-child'))
-          expect(reopenedLoad.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
-          const reopenedPreparation = await reopened.ctx.sessionPersistence.prepare(SessionId('forked-child'))
-          expect(reopenedPreparation.session.inheritedEventCount).toBe(SessionLogOffset(inherited.length))
-          reopenedPreparation[Symbol.dispose]()
-        } finally {
-          await reopened.fiber.dispose()
-        }
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('round-trips the delegation depth through persistence', async () => {
-      // A subagent child's recursion budget lives in its header; a reload that
-      // dropped it would reset the child to top-level and un-bound maxDepth
-      // The backend must preserve it in stored metadata.
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        let session!: Session
-        const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
-          session = inner.sessions.create(SessionId('delegated-child'), {
-            meta: { cwd: WORK, parentSession: SessionId('root'), delegationDepth: 2 },
-          })
-        }, { inject: ['sessions'] }))
-        send(session, oneTurnLog())
-        await ctx.parallel('session/flush', session)
-        await sessionFiber.dispose()
-
-        const loaded = await ctx.sessionPersistence.load(SessionId('delegated-child'))
-        expect(loaded.meta.delegationDepth).toBe(2)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('source-frozen events cannot be mutated after buffering and persist unchanged', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const session = ctx.sessions.create(SessionId('mutate'), { meta: { cwd: WORK } })
-        session.append('turn/start', { turn: 1 })
-        const ev = session.append('user/message', createUserMessage({
-          content: [{ type: 'text', text: 'original' }], source: { kind: 'user' },
-        }), { surfaceOp: 'append' })
-        expect(() => {
-          ;(ev.data as { content: { type: 'text'; text: string }[] }).content[0]!.text = 'HACKED'
-        }).toThrow(TypeError)
-        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(session)
-
-        const loaded = await ctx.sessionPersistence.load(SessionId('mutate'))
-        const message = loaded.events.find(event => event.type === 'user/message')
-        expect(message?.type === 'user/message' && (message.data.content[0] as { text: string }).text).toBe('original')
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('load and inspect return immutable identified-message snapshots', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const id = SessionId('immutable-read')
-        const session = ctx.sessions.create(id, { meta: { cwd: WORK } })
-        send(session, oneTurnLog())
-        await ctx.sessions.flush(session)
-
-        for (const snapshot of [
-          await ctx.sessionPersistence.load(id),
-          await ctx.sessionPersistence.inspect(id),
-        ]) {
-          const event = snapshot.events.find(candidate => candidate.type === 'user/message')
-          if (event?.type !== 'user/message') throw new Error('fixture lacks user/message')
-          expect(Object.isFrozen(event.data)).toBe(true)
-          expect(Object.isFrozen(event.data.content)).toBe(true)
-          expect(() => {
-            ;(event.data as { id: string }).id = 'rewritten'
-          }).toThrow(TypeError)
-          expect(() => {
-            ;(event.data.content[0] as { type: 'text'; text: string }).text = 'rewritten'
-          }).toThrow(TypeError)
-        }
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('loads pre-identity message logs into resumable current sessions', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const id = SessionId('legacy-message-load')
-        await ctx.sessionPersistence.create(meta(id, WORK))
-        await ctx.sessionPersistence.append(id, legacyMessageLog())
-
-        for (const snapshot of [
-          await ctx.sessionPersistence.inspect(id),
-          await ctx.sessionPersistence.load(id),
-        ]) {
-          const messages: { id: string }[] = []
-          for (const event of snapshot.events) {
-            if (event.type === 'user/message') messages.push(event.data)
-            else if (event.type === 'assistant/message'
-              || event.type === 'tool/result') messages.push(event.data.message)
-          }
-          expect(messages.map(message => message.id)).toEqual([
-            `legacy-message:${id}:1`,
-            `legacy-message:${id}:3`,
-            `legacy-message:${id}:5`,
-            `legacy-message:${id}:5`,
-          ])
-          expect(messages.every(message => Object.isFrozen(message))).toBe(true)
-
-          const resumed = Session.create(id, snapshot.events, snapshot.meta)
-          expect(resumed.deriveMessages().map(message => message.id)).toEqual([
-            `legacy-message:${id}:1`,
-            `legacy-message:${id}:3`,
-            `legacy-message:${id}:5`,
-          ])
-        }
-
-        const replacementSuffix = await ctx.sessionPersistence.readFrom(id, SessionLogOffset(6))
-        expect(replacementSuffix.events[0]).toMatchObject({
-          type: 'tool/result',
-          seq: 6,
-          data: { message: { id: `legacy-message:${id}:5` } },
-        })
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('loads pre-react-loop session logs into resumable current sessions', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const id = SessionId('pre-react-loop-load')
-        const log = preReactLoopLog()
-        const legacySteering = log[3] as unknown as { data: { message: { id: string } } }
-        await ctx.sessionPersistence.create(meta(id, WORK))
-        await ctx.sessionPersistence.append(id, log)
-
-        const snapshots = [
-          await ctx.sessionPersistence.inspect(id),
-          await ctx.sessionPersistence.readFrom(id, SessionLogOffset(0)),
-          await ctx.sessionPersistence.load(id),
-        ]
-        for (const snapshot of snapshots) {
-          expect(snapshot.events.some(event => (event.type as string) === 'steering/message')).toBe(false)
-          expect(snapshot.events.filter(event => event.type === 'turn/start').map(event => event.data))
-            .toEqual([
-              { turn: 1 }, { turn: 2 }, { turn: 3 }, { turn: 4 }, { turn: 5 }, { turn: 6 }, { turn: 7 },
-            ])
-          expect(snapshot.events.filter(event => event.type === 'turn/end').map(event => event.data)).toEqual([
-            { turn: 1, reason: { kind: 'completed' } },
-            {
-              turn: 2,
-              reason: { kind: 'error', error: { message: 'old provider failure', code: 'SERVER' } },
-            },
-            { turn: 3, reason: { kind: 'aborted', reason: { kind: 'legacy' } } },
-            { turn: 4, reason: { kind: 'aborted', reason: { kind: 'disposed' } } },
-            {
-              turn: 5,
-              reason: { kind: 'error', error: { message: 'old thrown value', code: 'UNKNOWN' } },
-            },
-            {
-              turn: 6,
-              reason: {
-                kind: 'error',
-                error: {
-                  message: 'old detailed provider failure',
-                  code: 'RATE_LIMIT',
-                  status: 429,
-                  providerRetryAfterMs: 1000,
-                  requestId: 'request-1',
-                },
-              },
-            },
-            {
-              turn: 7,
-              reason: { kind: 'error', error: { message: 'old coded error', code: 'CODED' } },
-            },
-          ])
-
-          const resumed = Session.create(id, snapshot.events, snapshot.meta)
-          expect(resumed.deriveMessages().map(message => message.content)).toEqual([
-            [{ type: 'text', text: 'old prompt' }],
-            [{ type: 'text', text: 'old steering' }],
-          ])
-        }
-
-        const suffix = await ctx.sessionPersistence.readFrom(id, SessionLogOffset(3))
-        expect(suffix.events[0]).toMatchObject({
-          type: 'user/message',
-          seq: 3,
-          data: { id: legacySteering.data.message.id },
-        })
-        expect(suffix.events.filter(event => event.type === 'turn/end')
-          .every(event => !Object.hasOwn(event.data, 'step'))).toBe(true)
-
-        const flatId = SessionId('pre-react-loop-flat-steering')
-        await ctx.sessionPersistence.create(meta(flatId, WORK))
-        await ctx.sessionPersistence.append(flatId, [{
-          type: 'steering/message',
-          seq: 0,
-          time: 1,
-          data: {
-            turn: 1,
-            content: [{ type: 'text', text: 'flat steering' }],
-            source: { kind: 'user' },
-          },
-          surfaceOp: 'append',
-        } as unknown as SessionEvent])
-        expect((await ctx.sessionPersistence.inspect(flatId)).events[0]).toMatchObject({
-          type: 'user/message',
-          data: {
-            id: `legacy-message:${flatId}:0`,
-            role: 'user',
-            content: [{ type: 'text', text: 'flat steering' }],
-          },
-        })
-
-        const extendedId = SessionId('current-extended-turn-end')
-        await ctx.sessionPersistence.create(meta(extendedId, WORK))
-        await ctx.sessionPersistence.append(extendedId, [
-          { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } },
-          {
-            type: 'turn/end', seq: 1, time: 2,
-            data: { turn: 1, reason: { kind: 'extension-reason' } },
-          } as unknown as SessionEvent,
-        ])
-        expect((await ctx.sessionPersistence.inspect(extendedId)).events[1]).toMatchObject({
-          type: 'turn/end',
-          data: { reason: { kind: 'extension-reason' } },
-        })
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('rejects malformed persisted message events before returning them', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const id = SessionId('invalid-message-read')
-        await ctx.sessionPersistence.create(meta(id, WORK))
-        await ctx.sessionPersistence.append(id, [{
-          type: 'user/message',
-          seq: 0,
-          time: 1,
-          surfaceOp: 'append',
-          data: {
-            id: 'wrong-role',
-            role: 'assistant',
-            content: [{ type: 'text', text: 'wrong' }],
-            source: { kind: 'user' },
-          },
-        } as unknown as SessionEvent])
-
-        await expect(ctx.sessionPersistence.inspect(id))
-          .rejects.toThrow('message must have role "user"')
-        await expect(ctx.sessionPersistence.load(id))
-          .rejects.toThrow('message must have role "user"')
-
-        const malformedLegacy: { id: string; event: SessionEvent; message: string }[] = [
-          {
-            id: 'invalid-old-turn-start',
-            event: {
-              type: 'turn/start', seq: 0, time: 1,
-              data: { turn: 1, trigger: null },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop turn/start',
-          },
-          {
-            id: 'invalid-old-steering',
-            event: {
-              type: 'steering/message', seq: 0, time: 1, surfaceOp: 'append',
-              data: { turn: 1, content: [], source: { kind: 'user' }, extra: true },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop steering/message',
-          },
-          {
-            id: 'invalid-old-steering-data',
-            event: {
-              type: 'steering/message', seq: 0, time: 1, surfaceOp: 'append', data: null,
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop steering/message',
-          },
-          {
-            id: 'invalid-old-turn-end',
-            event: {
-              type: 'turn/end', seq: 0, time: 1,
-              data: { turn: 1, reason: { kind: 'completed', extra: true } },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop turn/end',
-          },
-          {
-            id: 'invalid-old-turn-end-reason',
-            event: {
-              type: 'turn/end', seq: 0, time: 1,
-              data: { turn: 1, reason: null },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop turn/end',
-          },
-          {
-            id: 'unsupported-intermediate-turn-end-step',
-            event: {
-              type: 'turn/end', seq: 0, time: 1,
-              data: { turn: 1, step: 1, reason: { kind: 'completed' } },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop turn/end',
-          },
-          {
-            id: 'invalid-old-turn-end-aborted',
-            event: {
-              type: 'turn/end', seq: 0, time: 1,
-              data: { turn: 1, reason: { kind: 'aborted', extra: true } },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop turn/end',
-          },
-          {
-            id: 'invalid-old-turn-end-disposed',
-            event: {
-              type: 'turn/end', seq: 0, time: 1,
-              data: { turn: 1, reason: { kind: 'disposed', extra: true } },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop turn/end',
-          },
-          {
-            id: 'invalid-old-turn-end-error-step',
-            event: {
-              type: 'turn/end', seq: 0, time: 1,
-              data: { turn: 1, reason: { kind: 'error', step: -1, message: 'bad step' } },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop turn/end',
-          },
-          {
-            id: 'invalid-old-turn-end-error-code',
-            event: {
-              type: 'turn/end', seq: 0, time: 1,
-              data: { turn: 1, reason: { kind: 'error', step: 0, message: 'bad code', code: 1 } },
-            } as unknown as SessionEvent,
-            message: 'malformed pre-react-loop turn/end',
-          },
-        ]
-        for (const malformed of malformedLegacy) {
-          const malformedId = SessionId(malformed.id)
-          await ctx.sessionPersistence.create(meta(malformedId, WORK))
-          await ctx.sessionPersistence.append(malformedId, [malformed.event])
-          await expect(ctx.sessionPersistence.inspect(malformedId)).rejects.toThrow(malformed.message)
-          await expect(ctx.sessionPersistence.readFrom(malformedId, SessionLogOffset(0)))
-            .rejects.toThrow(malformed.message)
-        }
-
-        const malformedReplacementId = SessionId('invalid-old-tool-result-replacement')
-        await ctx.sessionPersistence.create(meta(malformedReplacementId, WORK))
-        await ctx.sessionPersistence.append(malformedReplacementId, [{
-          type: 'tool/result',
-          seq: 0,
-          time: 1,
-          surfaceOp: { op: 'replace', start: -1, end: -1 },
-          data: {
-            turn: 1,
-            step: 1,
-            callId: 'call',
-            content: [{ type: 'text', text: 'result' }],
-            isError: false,
-          },
-        } as unknown as SessionEvent])
-        await expect(ctx.sessionPersistence.inspect(malformedReplacementId))
-          .rejects.toThrow('invalid replace surfaceOp')
-
-        for (const type of ['tool/result'] as const) {
-          const malformedId = SessionId(`invalid-${type}`)
-          await ctx.sessionPersistence.create(meta(malformedId, WORK))
-          await ctx.sessionPersistence.append(malformedId, [{
-            type,
-            seq: 0,
-            time: 1,
-            surfaceOp: 'append',
-            data: { message: null },
-          } as unknown as SessionEvent])
-          await expect(ctx.sessionPersistence.inspect(malformedId))
-            .rejects.toThrow('lacks an identified message')
-        }
-
-        // An out-of-repo event type passes only with the envelope's ignorable
-        // marker (unknown-type refusal otherwise), and its non-object data is
-        // not message-validated.
-        const pluginId = SessionId('non-object-plugin-event')
-        await ctx.sessionPersistence.create(meta(pluginId, WORK))
-        await ctx.sessionPersistence.append(pluginId, [{
-          type: 'plugin/test',
-          seq: 0,
-          time: 1,
-          data: null,
-          ignorable: true,
-        } as unknown as SessionEvent])
-        await expect(ctx.sessionPersistence.inspect(pluginId))
-          .resolves.toMatchObject({ events: [{ type: 'plugin/test', data: null, ignorable: true }] })
-        await expect(ctx.sessionPersistence.readFrom(pluginId, SessionLogOffset(0)))
-          .resolves.toMatchObject({ events: [{ type: 'plugin/test', data: null, ignorable: true }] })
-
-        for (const type of ['user/message', 'assistant/message'] as const) {
-          const missingContentId = SessionId(`invalid-${type}-without-content`)
-          await ctx.sessionPersistence.create(meta(missingContentId, WORK))
-          await ctx.sessionPersistence.append(missingContentId, [{
-            type,
-            seq: 0,
-            time: 1,
-            surfaceOp: 'append',
-            data: {},
-          } as unknown as SessionEvent])
-          await expect(ctx.sessionPersistence.readFrom(missingContentId, SessionLogOffset(0)))
-            .rejects.toThrow('lacks an identified message')
-        }
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('append snapshots the batch: mutating the caller array/events after the call is ignored', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const m = meta('snapshot', WORK)
-        await ctx.sessionPersistence.create(m)
-        const events = structuredClone(oneTurnLog()) // seqs 0..5
-        const userMsg = events[1] // the user/message event
-        const p = ctx.sessionPersistence.append(m.id, events)
-        // Mutate the caller's array AND an event object after the call but before
-        // the queued op runs: the snapshot taken at call time must shield the copy.
-        events.push({ type: 'turn/start', seq: SessionSeq(6), time: 99, data: { turn: 2 } })
-        if (userMsg?.type === 'user/message') {
-          (userMsg.data as { content: unknown[] }).content = [{ type: 'text', text: 'MUTATED' }]
-        }
-        await p
-        const loaded = await ctx.sessionPersistence.load(m.id)
-        expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5]) // not 0..6
-        const persisted = JSON.stringify(loaded.events)
-        expect(persisted).toContain('hi') // original content
-        expect(persisted).not.toContain('MUTATED')
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    // --- fork / resume ---
-
-    it('fork: a seeded new session persists its seed once (no double-write on a no-op flush)', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const seed = oneTurnLog()
-        // A fork: a brand-new id whose seed came from elsewhere.
-        const forked = ctx.sessions.create(SessionId('forked'), { seed, meta: { cwd: WORK } })
-        await ctx.sessions.flush(forked) // onCreated persisted the seed
-        const loaded = await ctx.sessionPersistence.load(SessionId('forked'))
-        // Fork is where the marker earns its keep: the inherited prefix may
-        // carry a bracket the still-running parent owns.
-        expect(loaded.events.slice(0, seed.length)).toEqual(seed)
-        expect(loaded.events.at(-1)).toMatchObject({ type: 'session/end-seed', seq: seed.length })
-        // A flush with no NEW events must not double-write.
-        await ctx.sessions.flush(forked)
-        const reloaded = await ctx.sessionPersistence.load(SessionId('forked'))
-        expect(reloaded.events).toEqual(loaded.events)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('resume: a re-created session seeded with the loaded log does not re-append its seed and continues the seq', async () => {
-      // Separate backend lifecycles distinguish persisted-seed adoption from an in-memory continuation.
-      const fix = await makeFixture()
-      const first = await freshCtx(fix)
-      try {
-        const s1 = first.ctx.sessions.create(SessionId('resumed'), { meta: { cwd: WORK } })
-        send(s1, oneTurnLog())
-        await first.ctx.sessions.flush(s1)
-      } finally {
-        await first.fiber.dispose()
-      }
-
-      const second = await freshCtx(fix)
-      try {
-        const loaded = await second.ctx.sessionPersistence.load(SessionId('resumed'))
-        const s2 = second.ctx.sessions.create(SessionId('resumed'), { seed: loaded.events, meta: { cwd: WORK } })
-        await second.ctx.sessions.flush(s2) // let onCreated adopt
-        s2.append('turn/start', { turn: 2 })
-        s2.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
-        await second.ctx.sessions.flush(s2)
-
-        const reloaded = await second.ctx.sessionPersistence.load(SessionId('resumed'))
-        // 0-5 the resumed seed, 6 end-seed, 7-8 the new turn.
-        expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8])
-        expect(reloaded.events[6]).toMatchObject({ type: 'session/end-seed' })
-      } finally {
-        await second.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    // --- HMR ---
-
-    it('HMR: applying the plugin seeds existing live sessions', async () => {
-      const fix = await makeFixture()
-      const ctx = new Context()
-      await ctx.plugin(SessionStore)
-      // A session exists BEFORE the persistence plugin is applied.
-      const session = ctx.sessions.create(SessionId('pre-existing'), { meta: { cwd: WORK } })
-      session.append('turn/start', { turn: 1 })
-      session.append('user/message', createUserMessage({
-        content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
-      }), { surfaceOp: 'append' })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-
-      const fiber = await fix.mount(ctx)
-      try {
-        // The plugin seeded it on apply; a subsequent flush persists its events.
-        await ctx.sessions.flush(session)
-        const loaded = await ctx.sessionPersistence.load(SessionId('pre-existing'))
-        expect(loaded.events.length).toBeGreaterThanOrEqual(2)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('HMR: dispose drains remaining buffers', async () => {
-      const fix = await makeFixture()
-      const ctx = new Context()
-      await ctx.plugin(SessionStore)
-      const fiber = await fix.mount(ctx)
-      const session = await liveSessionInFiber(ctx, 'drain', WORK)
-      session.append('turn/start', { turn: 1 })
-      session.append('user/message', createUserMessage({
-        content: [{ type: 'text', text: 'buffered' }], source: { kind: 'user' },
-      }), { surfaceOp: 'append' })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      // No explicit flush — dispose must drain.
-      await fiber.dispose()
-
-      // A fresh backend instance reads what the disposed one drained.
-      const second = await freshCtx(fix)
-      try {
-        const loaded = await second.ctx.sessionPersistence.load(SessionId('drain'))
-        expect(loaded.events.length).toBeGreaterThanOrEqual(2)
-      } finally {
-        await second.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('HMR: reloading the backend adopts a still-live, already-materialized session', async () => {
-      const fix = await makeFixture()
-      const ctx = new Context()
-      await ctx.plugin(SessionStore)
-      // The session lives in its OWN fiber so it survives the backend reload.
-      const session = await liveSessionInFiber(ctx, 'hmr-adopt', WORK)
-      try {
-        // Backend instance 1 materializes the session.
-        const backend1 = await fix.mount(ctx)
-        session.append('turn/start', { turn: 1 })
-        session.append('user/message', createUserMessage({
-          content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
-        }), { surfaceOp: 'append' })
-        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(session)
-
-        // Hot-reload: dispose instance 1, mount instance 2 over the same storage while the
-        // session stays live. The new instance has no coordinator state but must adopt the
-        // materialized prefix, then persist another turn rather than rejecting it as a collision.
-        await backend1.dispose()
-        await fix.mount(ctx)
-        session.append('turn/start', { turn: 2 })
-        session.append('user/message', createUserMessage({
-          content: [{ type: 'text', text: 'again' }], source: { kind: 'user' },
-        }), { surfaceOp: 'append' })
-        session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
-        await expect(ctx.sessions.flush(session)).resolves.not.toThrow()
-
-        const loaded = await ctx.sessionPersistence.load(SessionId('hmr-adopt'))
-        expect(loaded.events.filter(e => e.type === 'turn/start')).toHaveLength(2)
-      } finally {
-        await ctx.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('HMR: adoption persists the live SUFFIX that was ahead of the stored prefix', async () => {
-      const fix = await makeFixture()
-      const ctx = new Context()
-      await ctx.plugin(SessionStore)
-      const session = await liveSessionInFiber(ctx, 'hmr-suffix', WORK)
-      try {
-        // Instance 1 flushes turn 1.
-        const backend1 = await fix.mount(ctx)
-        session.append('turn/start', { turn: 1 })
-        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(session)
-
-        // Append turn 2 to the LIVE session, then dispose instance 1 WITHOUT
-        // flushing turn 2: it is now ONLY in the live session's events; the new
-        // backend never buffered it via session/event.
-        await backend1.dispose()
-        session.append('turn/start', { turn: 2 })
-        session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
-
-        // Instance 2 adopts the stored prefix (turn 1) and MUST also persist the
-        // live suffix (turn 2) carried in the session's events.
-        await fix.mount(ctx)
-        await ctx.sessions.flush(session)
-        const loaded = await ctx.sessionPersistence.load(SessionId('hmr-suffix'))
-        expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3])
-        expect(loaded.events.filter(e => e.type === 'turn/start')).toHaveLength(2)
-      } finally {
-        await ctx.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('HMR adoption does NOT crash-repair an active open turn as interrupted (truncate without closers)', async () => {
-      const fix = await makeFixture()
-      const ctx = new Context()
-      await ctx.plugin(SessionStore)
-      const session = await liveSessionInFiber(ctx, 'hmr-open', WORK)
-      try {
-        const first = await fix.mount(ctx)
-        session.append('turn/start', { turn: 1 })
-        session.append('step/start', { turn: 1, step: 1 })
-        await ctx.sessions.flush(session)
-
-        // Crash-tail a torn fragment past the (open) committed turn, then reload.
-        await first.dispose()
-        if (fix.corruptTail) await fix.corruptTail(SessionId('hmr-open'), WORK)
-        const second = await fix.mount(ctx)
-        // The live session is still the authority: it appends the REAL step/turn
-        // end. Adoption must truncate the torn tail but NOT synthesize closers.
-        session.append('step/end', { turn: 1, step: 1 })
-        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(session)
-
-        const loaded = await ctx.sessionPersistence.load(SessionId('hmr-open'))
-        expect(loaded.events.map(e => e.type)).toEqual(['turn/start', 'step/start', 'step/end', 'turn/end'])
-        expect(loaded.events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'completed' } } })
-        await second.dispose()
-      } finally {
-        await ctx.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    // --- collision / id reuse ---
-
-    it('a NEW live session colliding on a persisted id is rejected, not silently adopted', async () => {
-      const fix = await makeFixture()
-      const first = await freshCtx(fix)
-      try {
-        const s1 = first.ctx.sessions.create(SessionId('collide'), { meta: { cwd: WORK } })
-        send(s1, oneTurnLog())
-        await first.ctx.sessions.flush(s1)
-      } finally {
-        await first.fiber.dispose()
-      }
-
-      // A fresh backend + a NEW live session with the same id but NO explicit resume. onCreated
-      // treats it as new; create() rejects because a log already exists, and `flush()` surfaces
-      // that initialization rejection.
-      const second = await freshCtx(fix)
-      try {
-        const s2 = second.ctx.sessions.create(SessionId('collide'), { meta: { cwd: WORK } })
-        s2.append('turn/start', { turn: 1 })
-        await expect(second.ctx.sessions.flush(s2))
-          .rejects.toThrow(/already has a persisted log|id collision/)
-      } finally {
-        await second.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('an abandoned lazy session (never materialized) releases its id for reuse', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        // A live session created then disposed BEFORE its first append: cursor 0,
-        // never materialized. A new live session reusing the id must reclaim it.
-        let firstSession!: Session
-        const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
-          firstSession = inner.sessions.create(SessionId('abandoned'), { meta: { cwd: WORK } })
-        }, { inject: ['sessions'] }))
-        await ctx.sessions.flush(firstSession) // register the lazy state
-        await firstFiber.dispose() // disposed before any append → never materialized
-
-        let reuse!: Session
-        await ctx.plugin(Object.assign((inner: Context) => {
-          reuse = inner.sessions.create(SessionId('abandoned'), { meta: { cwd: WORK } })
-        }, { inject: ['sessions'] }))
-        await expect(ctx.sessions.flush(reuse)).resolves.toBe(true)
-        reuse.append('turn/start', { turn: 1 })
-        reuse.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(reuse)
-        const loaded = await ctx.sessionPersistence.load(SessionId('abandoned'))
-        expect(loaded.events.map(e => e.seq)).toEqual([0, 1])
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('session disposal drains buffered events before retiring ownership', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        let first!: Session
-        const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
-          first = inner.sessions.create(SessionId('buffered'), { meta: { cwd: WORK } })
-        }, { inject: ['sessions'] }))
-        await ctx.sessions.flush(first)
-        // Append a turn but do NOT flush — events sit in the write-behind buffer.
-        first.append('turn/start', { turn: 1 })
-        first.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await firstFiber.dispose()
-
-        // Disposal is an observe-only notification. Poll storage rather than
-        // assuming the owning fiber awaits the coordinator's detached drain.
-        await vi.waitFor(async () => {
-          expect((await ctx.sessionPersistence.list()).map(meta => meta.id)).toContain(SessionId('buffered'))
-        })
-        expect((await ctx.sessionPersistence.load(SessionId('buffered'))).events.map(event => event.seq)).toEqual([0, 1])
-
-        let reuse!: Session
-        await ctx.plugin(Object.assign((inner: Context) => {
-          reuse = inner.sessions.create(SessionId('buffered'), { meta: { cwd: WORK } })
-        }, { inject: ['sessions'] }))
-        await expect(ctx.sessions.flush(reuse)).rejects.toThrow(/persisted log|id collision/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('initFor is idempotent: re-emitting session/created does not re-initialize', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const session = ctx.sessions.create(SessionId('idem'), { meta: { cwd: WORK } })
-        session.append('turn/start', { turn: 1 })
-        session.append('user/message', createUserMessage({
-          content: [{ type: 'text', text: 'x' }], source: { kind: 'user' },
-        }), { surfaceOp: 'append' })
-        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(session)
-        // Re-emit session/created for the SAME live session (idempotent initFor).
-        ctx.emit(scopeTarget(session, undefined), 'session/created', session)
-        await ctx.sessions.flush(session)
-        const loaded = await ctx.sessionPersistence.load(SessionId('idem'))
-        expect(loaded.events).toHaveLength(3) // not doubled
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    // --- ownerless-state claim (public create()/load() then a live session arrives) ---
-
-    it('a live session claims cursor-0 ownerless state created via the public API and persists its seed', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        // create() registers ownerless state with cursor 0 (lazy, nothing persisted).
-        await ctx.sessionPersistence.create(meta('lazy-claim', WORK))
-        // A live session with that id arrives and claims it (cursor 0 matches
-        // trivially), persisting its seed.
-        const live = ctx.sessions.create(SessionId('lazy-claim'), { seed: oneTurnLog(), meta: { cwd: WORK } })
-        await expect(ctx.sessions.flush(live)).resolves.toBe(true)
-        const loaded = await ctx.sessionPersistence.load(SessionId('lazy-claim'))
-        // Seeded 0-5 plus the constructor's end-seed event at 6.
-        expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6])
-        expect(loaded.events.at(-1)).toMatchObject({ type: 'session/end-seed' })
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('a fresh session reusing a previously-loaded id is rejected (ownerless guard)', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        // Materialize a log, then load() it WITHOUT a live session — ownerless
-        // state, cursor at the persisted length.
-        await ctx.sessionPersistence.create(meta('preview', WORK))
-        await ctx.sessionPersistence.append(SessionId('preview'), oneTurnLog())
-        await ctx.sessionPersistence.load(SessionId('preview'))
-
-        // A FRESH (empty-seed) live session reusing that id must be rejected: its
-        // seq 0..cursor-1 events would otherwise be filtered as already-persisted.
-        let fresh!: Session
-        await ctx.plugin(Object.assign((inner: Context) => {
-          fresh = inner.sessions.create(SessionId('preview'), { meta: { cwd: WORK } })
-        }, { inject: ['sessions'] }))
-        await expect(ctx.sessions.flush(fresh))
-          .rejects.toThrow(/do not match this live session|already has a persisted log|id collision/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('a live session whose complete seed matches loaded ownerless state claims it without appending', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const id = SessionId('claim-exact')
-        const completeSeed = [
-          ...oneTurnLog(),
-          { type: 'session/end-seed', seq: 6, time: 7, data: {} },
-        ] as SessionEvent[]
-        await ctx.sessionPersistence.create(meta(id, WORK))
-        await ctx.sessionPersistence.append(id, completeSeed)
-        const { events } = await ctx.sessionPersistence.load(id)
-
-        const live = ctx.sessions.create(id, { seed: events, meta: { cwd: WORK } })
-        await expect(ctx.sessions.flush(live)).resolves.toBe(true)
-        expect((await ctx.sessionPersistence.load(id)).events).toEqual(events)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('a live session whose seed matches the loaded prefix claims ownerless state and persists the suffix', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        // Materialize and load (ownerless, cursor = 6).
-        const storedMeta = meta('claim', WORK)
-        await ctx.sessionPersistence.create(storedMeta)
-        await ctx.sessionPersistence.append(SessionId('claim'), oneTurnLog())
-        const { events, meta: durableMeta } = await ctx.sessionPersistence.load(SessionId('claim'))
-
-        // A live session SEEDED with the loaded log PLUS a new turn claims the
-        // ownerless state and persists only the suffix.
-        let cont!: Session
-        const contFiber = await ctx.plugin(Object.assign((inner: Context) => {
-          cont = inner.sessions.create(SessionId('claim'), { seed: [
-            ...events,
-            { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-            { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-          ], meta: { cwd: WORK, createdAt: 2000 } })
-        }, { inject: ['sessions'] }))
-        await ctx.sessions.flush(cont)
-        const loaded = await ctx.sessionPersistence.load(SessionId('claim'))
-        // 6-7 the claimed suffix; 8 end-seed after the whole seed.
-        expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8])
-        expect(loaded.events.at(-1)).toMatchObject({ type: 'session/end-seed' })
-        expect(loaded.meta).toEqual(durableMeta)
-        expect(loaded.meta.createdAt).toBe(1000)
-
-        await contFiber.dispose()
-        await vi.waitFor(async () => {
-          expect((await ctx.sessionPersistence.load(SessionId('claim'))).meta).toEqual(durableMeta)
-        })
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('a live session at a DIFFERENT cwd cannot claim cursor-0 ownerless state (cwd scope)', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        // create() registers ownerless state at cwd /a (cursor 0 — claims would
-        // otherwise match trivially on the seed).
-        await ctx.sessionPersistence.create(meta('wrong-cwd-claim', OTHER))
-        // A live session reusing the id but at cwd WORK must NOT claim it — the
-        // cwd scope is the fence (without it, WORK events would append under the
-        // OTHER header). Rejected as a collision.
-        const live = ctx.sessions.create(SessionId('wrong-cwd-claim'), { seed: oneTurnLog(), meta: { cwd: WORK } })
-        await expect(ctx.sessions.flush(live)).rejects.toThrow(/different cwd|id collision/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('a live session cannot claim ownerless state with a different inherited cut', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const id = SessionId('wrong-cut-claim')
-        await ctx.sessionPersistence.create(
-          { ...meta(id, WORK), isSeeded: true },
-          SessionLogOffset(0),
-        )
-        const live = ctx.sessions.create(id, {
-          seed: oneTurnLog(),
-          inheritedEventCount: SessionLogOffset(1),
-          meta: { cwd: WORK, isSeeded: true },
-        })
-
-        await expect(ctx.sessions.flush(live))
-          .rejects.toThrow(/different inherited event count|id collision/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('a live session cannot adopt a stored prefix with a different inherited cut', async () => {
-      const fix = await makeFixture()
-      const id = SessionId('wrong-cut-adoption')
-      const first = await freshCtx(fix)
-      try {
-        await first.ctx.sessionPersistence.create(
-          { ...meta(id, WORK), isSeeded: true },
-          SessionLogOffset(0),
-        )
-        await first.ctx.sessionPersistence.append(id, oneTurnLog())
-      } finally {
-        await first.fiber.dispose()
-      }
-
-      const second = await freshCtx(fix)
-      try {
-        const live = second.ctx.sessions.create(id, {
-          seed: oneTurnLog(),
-          inheritedEventCount: SessionLogOffset(1),
-          meta: { cwd: WORK, isSeeded: true },
-        })
-
-        await expect(second.ctx.sessions.flush(live))
-          .rejects.toThrow(/different inherited event count|id collision/)
-      } finally {
-        await second.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('a live session at a DIFFERENT cwd cannot claim loaded-prefix ownerless state (cwd scope)', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        // Materialize + load at cwd OTHER (ownerless, cursor = 6).
-        await ctx.sessionPersistence.create(meta('wrong-cwd-load', OTHER))
-        await ctx.sessionPersistence.append(SessionId('wrong-cwd-load'), oneTurnLog())
-        const { events } = await ctx.sessionPersistence.load(SessionId('wrong-cwd-load'))
-        // A live session whose SEED matches the loaded prefix but whose cwd is
-        // WORK must still be rejected — the cwd guard runs before the seed check.
-        const live = ctx.sessions.create(SessionId('wrong-cwd-load'), { seed: events, meta: { cwd: WORK } })
-        await expect(ctx.sessions.flush(live)).rejects.toThrow(/different cwd|id collision/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('a no-cwd ownerless state cannot be claimed by a live session WITH a cwd (cwd scope, undefined side)', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        // Ownerless state created WITHOUT a cwd (the `_no-cwd` project directory).
-        await ctx.sessionPersistence.create(meta('no-cwd-state'))
-        // A live session reusing the id but WITH cwd WORK is a cwd mismatch
-        // (undefined vs WORK) and must be rejected.
-        const live = ctx.sessions.create(SessionId('no-cwd-state'), { seed: oneTurnLog(), meta: { cwd: WORK } })
-        await expect(ctx.sessions.flush(live)).rejects.toThrow(/different cwd|id collision/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    // --- append adopts a storage-only session (fresh instance, no prior create/load) ---
-
-    it('append adopts a storage-only session (fresh instance) and continues the seq', async () => {
-      const fix = await makeFixture()
-      const first = await freshCtx(fix)
-      try {
-        const m = meta('adopt-append', WORK)
-        await first.ctx.sessionPersistence.create(m)
-        await first.ctx.sessionPersistence.append(m.id, oneTurnLog())
-      } finally {
-        await first.fiber.dispose()
-      }
-
-      // A fresh instance appends a second turn WITHOUT a prior create/load: append
-      // must adopt the stored session (cursor = stored length) and continue.
-      const second = await freshCtx(fix)
-      try {
-        await second.ctx.sessionPersistence.append(SessionId('adopt-append'), [
-          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-          { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-        ])
-        const loaded = await second.ctx.sessionPersistence.load(SessionId('adopt-append'))
-        expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
-      } finally {
-        await second.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    // --- small public-API edges that the coordinator owns uniformly ---
-
-    it('append of an empty batch is a no-op (stays lazy)', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const m = meta('empty-batch', WORK)
-        await ctx.sessionPersistence.create(m)
-        await ctx.sessionPersistence.append(m.id, [])
-        expect((await ctx.sessionPersistence.list()).map(h => h.id)).not.toContain(m.id)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('load and inspect reject a missing session', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        await expect(ctx.sessionPersistence.load(SessionId('nope'))).rejects.toThrow(/not found/)
-        await expect(ctx.sessionPersistence.inspect(SessionId('nope'))).rejects.toThrow(/not found/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('create rejects a duplicate id (in memory and on a persisted log)', async () => {
-      const fix = await makeFixture()
-      const first = await freshCtx(fix)
-      try {
-        const m = meta('dup', WORK)
-        await first.ctx.sessionPersistence.create(m)
-        // Same in-memory state.
-        await expect(first.ctx.sessionPersistence.create(m)).rejects.toThrow(/already exists in this backend/)
-        await first.ctx.sessionPersistence.append(m.id, oneTurnLog())
-      } finally {
-        await first.fiber.dispose()
-      }
-
-      // A fresh instance over the same storage sees the persisted log.
-      const second = await freshCtx(fix)
-      try {
-        await expect(second.ctx.sessionPersistence.create(meta('dup', WORK)))
-          .rejects.toThrow(/already has a persisted log on disk/)
-      } finally {
-        await second.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('rejects a newer format version on load, naming the upgrade direction', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const m = { version: 99, id: SessionId('v99'), createdAt: 1, cwd: WORK, isSeeded: false }
-        await ctx.sessionPersistence.create(m)
-        await ctx.sessionPersistence.append(m.id, oneTurnLog())
-        const failure = await ctx.sessionPersistence.load(m.id).then(() => undefined, (error: unknown) => error as Error)
-        expect(failure?.name).toBe('SessionFormatUnsupportedError')
-        expect(failure?.message).toMatch(/written by a newer harness.*upgrade the harness/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('rejects an older format version on load without claiming an upgrade path', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const m = { version: -1, id: SessionId('v-older'), createdAt: 1, cwd: WORK, isSeeded: false }
-        await ctx.sessionPersistence.create(m)
-        await ctx.sessionPersistence.append(m.id, oneTurnLog())
-        const failure = await ctx.sessionPersistence.load(m.id).then(() => undefined, (error: unknown) => error as Error)
-        expect(failure?.name).toBe('SessionFormatUnsupportedError')
-        expect(failure?.message).toMatch(/older than the supported v0.*no upgrade path/)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('rejects an unknown event type on load unless the event is marked ignorable', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const required = meta('unknown-required', WORK)
-        await ctx.sessionPersistence.create(required)
-        await ctx.sessionPersistence.append(required.id, [
-          ...oneTurnLog(),
-          { type: 'future/event', seq: oneTurnLog().length, time: 99, data: { payload: 1 } } as unknown as SessionEvent,
-        ])
-        const failure = await ctx.sessionPersistence.load(required.id).then(() => undefined, (error: unknown) => error as Error)
-        expect(failure?.name).toBe('SessionFormatUnsupportedError')
-        expect(failure?.message).toMatch(/event type "future\/event".*not marked ignorable/)
-
-        const skippable = meta('unknown-ignorable', WORK)
-        await ctx.sessionPersistence.create(skippable)
-        await ctx.sessionPersistence.append(skippable.id, [
-          ...oneTurnLog(),
-          { type: 'future/event', seq: oneTurnLog().length, time: 99, data: { payload: 1 }, ignorable: true } as unknown as SessionEvent,
-        ])
-        const loaded = await ctx.sessionPersistence.load(skippable.id)
-        expect(loaded.events.some(event => (event.type as string) === 'future/event')).toBe(true)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('round-trips a header with parentSession (fork lineage)', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        const m = {
-          version: SESSION_FORMAT_VERSION,
-          id: SessionId('forked-child'),
-          createdAt: 1,
-          cwd: WORK,
-          parentSession: SessionId('the-parent'),
-          isSeeded: false,
-        }
-        await ctx.sessionPersistence.create(m)
-        await ctx.sessionPersistence.append(m.id, oneTurnLog())
-        const loaded = await ctx.sessionPersistence.load(m.id)
-        expect(loaded.meta.parentSession).toBe('the-parent')
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    it('flush before init resolves uses cursor 0', async () => {
-      const fix = await makeFixture()
-      const { ctx, fiber } = await freshCtx(fix)
-      try {
-        // Append directly to a live session and flush IMMEDIATELY, before the
-        // async onCreated init has necessarily set state (exercises the
-        // state-undefined cursor path).
-        const session = ctx.sessions.create(SessionId('flush-nostate'), { meta: { cwd: WORK } })
-        session.append('turn/start', { turn: 1 })
-        session.append('user/message', createUserMessage({
-          content: [{ type: 'text', text: 'q' }], source: { kind: 'user' },
-        }), { surfaceOp: 'append' })
-        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(session)
-        const loaded = await ctx.sessionPersistence.load(SessionId('flush-nostate'))
-        expect(loaded.events).toHaveLength(3)
-      } finally {
-        await fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-
-    // --- crash-tail repair THROUGH the coordinator (real storage torn tail) ---
-
-    it('torn-tail load: a never-committed tail is truncated and the open turn closed during load (commitRepair w/ tornMarker)', async () => {
-      const fix = await makeFixture()
-      if (!fix.corruptTail) {
-        // A memory-style store has no torn tails (every write is atomic in RAM),
-        // so there is no tornMarker path to exercise. Assert that explicitly
-        // instead of silently skipping, then bail.
-        expect(fix.corruptTail).toBeUndefined()
-        await fix.cleanup()
-        return
-      }
-      const first = await freshCtx(fix)
-      try {
-        const m = meta('torn', WORK)
-        await first.ctx.sessionPersistence.create(m)
-        await first.ctx.sessionPersistence.append(m.id, oneTurnLog()) // committed 0..5 (balanced)
-        // A second turn whose real events are durable but never closed (open turn).
-        await first.ctx.sessionPersistence.append(m.id, [
-          { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-          { type: 'step/start', seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
-        ])
-      } finally {
-        await first.fiber.dispose()
-      }
-      // Inject a torn fragment past the committed region (never-committed tail).
-      await fix.corruptTail(SessionId('torn'), WORK)
-
-      // A FRESH instance loads: the torn tail is truncated (tornMarker !==
-      // undefined) AND the open turn 2 is closed with synthetic step/end +
-      // turn/end {interrupted} — commitRepair runs with BOTH a torn marker and
-      // closers. The preserved real events (0..7) are never truncated.
-      const second = await freshCtx(fix)
-      try {
-        const loaded = await second.ctx.sessionPersistence.load(SessionId('torn'))
-        expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
-        expect(loaded.events.map(e => e.type)).toEqual([
-          'turn/start', 'user/message', 'step/start', 'assistant/message', 'step/end', 'turn/end', // turn 1
-          'turn/start', 'step/start', 'step/end', 'turn/end', // turn 2: real + synthetic closers
-        ])
-        const last = loaded.events.at(-1)!
-        expect(last.type === 'turn/end' && last.data.reason).toEqual({ kind: 'interrupted' })
-
-        // The repair is durable: the next append continues at the balanced length
-        // (seq 10) and a reload round-trips identically.
-        await second.ctx.sessionPersistence.append(SessionId('torn'), [
-          { type: 'turn/start', seq: SessionSeq(10), time: 9, data: { turn: 3 } },
-          { type: 'turn/end', seq: SessionSeq(11), time: 10, data: { turn: 3, reason: { kind: 'completed' } } },
-        ])
-        const reloaded = await second.ctx.sessionPersistence.load(SessionId('torn'))
-        expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
-      } finally {
-        await second.fiber.dispose()
-        await fix.cleanup()
-      }
-    })
-  })
-}
diff --git a/packages/session/session-persistence/tests/live-write-contract.ts b/packages/session/session-persistence/tests/live-write-contract.ts
new file mode 100644
index 0000000000..c0f57ba9fa
--- /dev/null
+++ b/packages/session/session-persistence/tests/live-write-contract.ts
@@ -0,0 +1,275 @@
+/**
+ * Shared live-write-path contract for any {@link SessionPersistence} backend:
+ * published live events route by session id into the active write handle,
+ * `session/flush` is the durability and error-observation barrier,
+ * `session/disposed` drains and closes, and `close()` itself drains the
+ * routed buffer — including through backend teardown with no cross-fiber
+ * ordering. Each provider owns its storage runtime; this suite pins the
+ * equivalent observable behavior the seam requires.
+ *
+ * @module @deepseek-ai/dsh-session-persistence/tests/live-write-contract
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { Context } from '@deepseek-ai/cordis'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '../src/index.ts'
+
+/** One mounted backend under a session store, plus same-storage remount support. */
+export interface LiveWriteBackend {
+  /** Context with SessionStore and the persistence backend mounted. */
+  readonly ctx: Context
+  /** Mount a FRESH context over the SAME storage, as after a process restart. */
+  readonly remount: () => Promise<Context>
+}
+
+async function readAll(persistence: SessionPersistence, id: ReturnType<typeof SessionId>): Promise<readonly SessionEvent[]> {
+  const reader = await persistence.open(id, 'read')
+  try {
+    return await reader.read()
+  } finally {
+    await reader.close()
+  }
+}
+
+/**
+ * Run the backend-agnostic live-write-path suite.
+ * @param name - suite label, e.g. `jsonl` / `sqlite`.
+ * @param batchDelayMs - the provider's fixed live batching window.
+ * @param make - factory producing one fresh mounted backend per test; every
+ *   created context is disposed by the test that made it.
+ */
+export function runLiveWritePathContract(
+  name: string,
+  batchDelayMs: number,
+  make: () => Promise<LiveWriteBackend>,
+): void {
+  describe(`live session write path: ${name}`, () => {
+    it('routes published events into the active write handle within one batching window', async () => {
+      const { ctx } = await make()
+      const session = ctx.sessions.create(SessionId('routed'))
+      const handle = await ctx.sessionPersistence.create(session.header)
+      vi.useFakeTimers()
+      try {
+        session.append('turn/start', { turn: 1 })
+        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+        await vi.advanceTimersByTimeAsync(batchDelayMs - 1)
+        // One tick short of the window: nothing stored yet (in-process
+        // visibility serves the created-but-empty session).
+        expect(await readAll(ctx.sessionPersistence, session.id)).toEqual([])
+        await vi.advanceTimersByTimeAsync(1)
+      } finally {
+        vi.useRealTimers()
+      }
+      // The deadline started a background write; wait for its durability.
+      await vi.waitFor(async () => {
+        expect((await readAll(ctx.sessionPersistence, session.id)).map(event => [event.type, event.seq])).toEqual([
+          ['turn/start', 0],
+          ['turn/end', 1],
+        ])
+      })
+      await handle.close()
+      await ctx.fiber.dispose()
+    })
+
+    it('a session without an active write handle persists nothing', async () => {
+      const { ctx } = await make()
+      const session = ctx.sessions.create(SessionId('unrouted'))
+      session.append('turn/start', { turn: 1 })
+      await ctx.sessions.flush(session)
+      await expect(ctx.sessionPersistence.stat(session.id)).resolves.toBeUndefined()
+      await ctx.fiber.dispose()
+    })
+
+    it('session/flush drains immediately and surfaces a retained background failure', async () => {
+      const { ctx } = await make()
+      const session = ctx.sessions.create(SessionId('flush-surfaces'))
+      const handle = await ctx.sessionPersistence.create(session.header)
+      const warned = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+      const failure = new Error('backend write refused')
+      // Inject at the service's storage primitive: the routed drain writes
+      // through the handle's internal chain, not the public append.
+      const persist = vi.spyOn(ctx.sessionPersistence as unknown as { persistBatch: () => Promise<void> }, 'persistBatch')
+        .mockRejectedValue(failure)
+
+      vi.useFakeTimers()
+      session.append('turn/start', { turn: 1 })
+      await vi.advanceTimersByTimeAsync(batchDelayMs)
+      vi.useRealTimers()
+      await vi.waitFor(() => {
+        expect(warned.mock.calls.join('\n')).toContain('background write for session "flush-surfaces" failed')
+      })
+
+      // The barrier retries the retained batch and rejects loudly...
+      await expect(ctx.sessions.flush(session)).rejects.toBe(failure)
+      // ...and once the backend recovers, the same events land exactly once.
+      persist.mockRestore()
+      await expect(ctx.sessions.flush(session)).resolves.toBe(true)
+      expect((await readAll(ctx.sessionPersistence, session.id)).map(event => event.seq)).toEqual([0])
+      warned.mockRestore()
+      await handle.close()
+      await ctx.fiber.dispose()
+    })
+
+    it('service-level flush drains every active handle and aggregates the failures', async () => {
+      const { ctx } = await make()
+      const healthy = ctx.sessions.create(SessionId('flush-all-healthy'))
+      const failing = ctx.sessions.create(SessionId('flush-all-failing'))
+      const healthyHandle = await ctx.sessionPersistence.create(healthy.header)
+      const failingHandle = await ctx.sessionPersistence.create(failing.header)
+      const service = ctx.sessionPersistence as unknown as {
+        persistBatch: (header: { id: string }, ...rest: unknown[]) => Promise<void>
+      }
+      const original = service.persistBatch.bind(service)
+      const failure = new Error('backend write refused')
+      const persist = vi.spyOn(service, 'persistBatch').mockImplementation((header, ...rest) =>
+        header.id === failing.id ? Promise.reject(failure) : original(header, ...rest))
+
+      vi.useFakeTimers()
+      try {
+        healthy.append('turn/start', { turn: 1 })
+        failing.append('turn/start', { turn: 1 })
+        // No batching window elapses: the service barrier itself drains both
+        // buffers and reports the one failure without abandoning the sweep.
+        await expect(ctx.sessionPersistence.flush()).rejects.toSatisfy((error: unknown) =>
+          error instanceof AggregateError && error.errors.length === 1 && error.errors[0] === failure)
+      } finally {
+        vi.useRealTimers()
+      }
+      // The healthy session flushed durably despite its neighbor's failure...
+      expect((await readAll(ctx.sessionPersistence, healthy.id)).map(event => event.seq)).toEqual([0])
+      // ...and the failed batch is retained: a recovered backend flushes it exactly once.
+      persist.mockRestore()
+      await ctx.sessionPersistence.flush()
+      expect((await readAll(ctx.sessionPersistence, failing.id)).map(event => event.seq)).toEqual([0])
+      await healthyHandle.close()
+      await failingHandle.close()
+      await ctx.fiber.dispose()
+    })
+
+    it('session/disposed drains buffered events and closes the handle', async () => {
+      const { ctx } = await make()
+      let session: ReturnType<Context['sessions']['create']> | undefined
+      const owner = await ctx.plugin(Object.assign((inner: Context) => {
+        session = inner.sessions.create(SessionId('disposed-drains'))
+      }, { inject: ['sessions'] }))
+      if (session === undefined) throw new Error('session was not created')
+      const handle = await ctx.sessionPersistence.create(session.header)
+      session.append('turn/start', { turn: 1 })
+      // Buffered, not yet written: disposal must drain before the close.
+      await owner.dispose()
+      await vi.waitFor(async () => {
+        expect((await readAll(ctx.sessionPersistence, SessionId('disposed-drains'))).map(event => event.seq)).toEqual([0])
+      })
+      await expect(handle.append([])).rejects.toThrow(/closed handle/)
+      await ctx.fiber.dispose()
+    })
+
+    it('a failing final drain on disposal is warned, not thrown', async () => {
+      const { ctx } = await make()
+      let session: ReturnType<Context['sessions']['create']> | undefined
+      const owner = await ctx.plugin(Object.assign((inner: Context) => {
+        session = inner.sessions.create(SessionId('disposed-drain-fails'))
+      }, { inject: ['sessions'] }))
+      if (session === undefined) throw new Error('session was not created')
+      const handle = await ctx.sessionPersistence.create(session.header)
+      const warned = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+      vi.spyOn(handle, 'close').mockRejectedValue(new Error('drain exploded'))
+      session.append('turn/start', { turn: 1 })
+      await owner.dispose()
+      await vi.waitFor(() => {
+        expect(warned.mock.calls.join('\n')).toContain('final drain for session "disposed-drain-fails" failed')
+      })
+      warned.mockRestore()
+      await ctx.fiber.dispose()
+    })
+
+    it('backend teardown drains buffered events through the close sweep', async () => {
+      const backend = await make()
+      const { ctx } = backend
+      const session = ctx.sessions.create(SessionId('teardown-drains'))
+      const handle = await ctx.sessionPersistence.create(session.header)
+      session.append('turn/start', { turn: 1 })
+      // Root disposal closes the still-open handle; close drains the buffer.
+      await ctx.fiber.dispose()
+      await expect(handle.append([])).rejects.toThrow(/closed handle/)
+
+      const verify = await backend.remount()
+      expect((await readAll(verify.sessionPersistence, session.id)).map(event => event.seq)).toEqual([0])
+      await verify.fiber.dispose()
+    })
+
+    it('close itself surfaces a failing drain and still releases write ownership', async () => {
+      const { ctx } = await make()
+      const session = ctx.sessions.create(SessionId('close-drain-fails'))
+      const handle = await ctx.sessionPersistence.create(session.header)
+      const failure = new Error('storage refused the drain')
+      vi.spyOn(ctx.sessionPersistence as unknown as { persistBatch: () => Promise<void> }, 'persistBatch')
+        .mockRejectedValue(failure)
+      session.append('turn/start', { turn: 1 })
+      await expect(handle.close()).rejects.toBe(failure)
+      // Ownership was released despite the failed drain: the id is claimable.
+      const second = await ctx.sessionPersistence.create(session.header)
+      await second.close()
+      await ctx.fiber.dispose()
+    })
+
+    it('close normalizes a non-Error drain failure', async () => {
+      const { ctx } = await make()
+      const session = ctx.sessions.create(SessionId('close-drain-string'))
+      const handle = await ctx.sessionPersistence.create(session.header)
+      vi.spyOn(ctx.sessionPersistence as unknown as { persistBatch: () => Promise<void> }, 'persistBatch')
+        // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error arm is the case under test.
+        .mockImplementation(() => Promise.reject('backend string refusal'))
+      session.append('turn/start', { turn: 1 })
+      await expect(handle.close()).rejects.toThrow('backend string refusal')
+      await ctx.fiber.dispose()
+    })
+
+    it('a failed drain retains order, quiets the timer, and recovers exactly once', async () => {
+      const { ctx } = await make()
+      const session = ctx.sessions.create(SessionId('retained-order'))
+      const handle = await ctx.sessionPersistence.create(session.header)
+      const warned = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+      const host = ctx.sessionPersistence as unknown as { persistBatch: (...args: unknown[]) => Promise<void> }
+      const real = host.persistBatch.bind(host)
+      const persist = vi.spyOn(host, 'persistBatch').mockRejectedValue(new Error('first drain refused'))
+
+      vi.useFakeTimers()
+      session.append('turn/start', { turn: 1 })
+      session.append('step/start', { turn: 1, step: 1 })
+      await vi.advanceTimersByTimeAsync(batchDelayMs)
+      // Events arriving after the failure join the retained queue, and no new
+      // timer fires while the automatic path is paused.
+      session.append('step/end', { turn: 1, step: 1 })
+      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+      await vi.advanceTimersByTimeAsync(batchDelayMs * 4)
+      vi.useRealTimers()
+      expect(persist).toHaveBeenCalledTimes(1)
+
+      persist.mockImplementation(real)
+      await expect(ctx.sessions.flush(session)).resolves.toBe(true)
+      expect((await readAll(ctx.sessionPersistence, session.id)).map(event => event.seq)).toEqual([0, 1, 2, 3])
+      warned.mockRestore()
+      await handle.close()
+      await ctx.fiber.dispose()
+    })
+
+    it('a second write handle after close routes subsequent events', async () => {
+      const { ctx } = await make()
+      const session = ctx.sessions.create(SessionId('rebind'))
+      const first = await ctx.sessionPersistence.create(session.header)
+      session.append('turn/start', { turn: 1 })
+      await ctx.sessions.flush(session)
+      await first.close()
+
+      const second = await ctx.sessionPersistence.open(session.id, 'write')
+      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+      await ctx.sessions.flush(session)
+      expect((await readAll(ctx.sessionPersistence, session.id)).map(event => event.seq)).toEqual([0, 1])
+      await second.close()
+      await ctx.fiber.dispose()
+    })
+  })
+}
diff --git a/packages/session/session-persistence/tests/persistence.spec.ts b/packages/session/session-persistence/tests/persistence.spec.ts
deleted file mode 100644
index dd002882f7..0000000000
--- a/packages/session/session-persistence/tests/persistence.spec.ts
+++ /dev/null
@@ -1,2376 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import { Context } from '@deepseek-ai/cordis'
-import SessionStore, {
-  Session,
-  SessionId,
-  SessionLogOffset,
-  SessionSeq,
-} from '@deepseek-ai/dsh-session'
-import { isJsonValue } from '@deepseek-ai/dsh-util-values'
-import type {
-  SessionEvent,
-  SessionHeader,
-  SessionLogOffset as SessionLogOffsetType,
-} from '@deepseek-ai/dsh-session'
-import {
-  DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS,
-  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
-  type PersistenceBackend, type SessionEventSuffix, type SessionInspection, type SessionPersistenceSnapshot,
-  type SessionStorageMetadata, type StoredPrefix, type StoredSuffix,
-} from '../src/index.ts'
-import { runPersistenceContract, meta, oneTurnLog } from './contract.ts'
-import {
-  legacyMessageLog, preReactLoopLog, runCoordinatorContract, type CoordinatorFixture,
-} from './coordinator-contract.ts'
-
-/** The durable store shape: materialized sessions only (no lazy entries). */
-type MemoryStore = Map<string, {
-  meta: SessionHeader
-  inheritedEventCount?: SessionLogOffsetType
-  events: SessionEvent[]
-}>
-
-/** Test-store revision that changes for any metadata or event mutation. */
-function memoryRevision(entry: {
-  meta: SessionHeader
-  inheritedEventCount?: SessionLogOffsetType
-  events: SessionEvent[]
-}): SessionPersistenceRevision {
-  return SessionPersistenceRevision(JSON.stringify(entry))
-}
-
-/** An obsolete event fixture that emulates an untyped pre-change producer. */
-function legacyHeaderDelta(seq = 0): SessionEvent {
-  return {
-    type: 'request/header-delta',
-    seq,
-    time: 1,
-    data: { config: { model: 'legacy' } },
-  } as unknown as SessionEvent
-}
-
-/** An unsupported named-mode fixture emulating an untyped producer. */
-function legacyModeSet(seq = 0): SessionEvent {
-  return {
-    type: 'mode/set',
-    seq,
-    time: 1,
-    data: { mode: 'plan' },
-  } as unknown as SessionEvent
-}
-
-/** An obsolete full-header reason fixture from the removed delta codec. */
-function legacyFallbackHeader(seq = 0): SessionEvent {
-  return {
-    type: 'request/header',
-    seq,
-    time: 1,
-    data: { header: { config: { model: 'legacy' } }, reason: 'fallback' },
-  } as unknown as SessionEvent
-}
-
-/** Optional plugin config: an EXTERNAL store shared across backend instances. */
-interface MemoryConfig { store?: MemoryStore }
-
-/** Test-only view of the coordinator containers whose retirement is the contract under test. */
-interface CoordinatorInternals {
-  states: Map<unknown, unknown>
-  live: Map<unknown, {
-    writes: { pending: unknown[]; active: Promise<void> | undefined; hasWork: boolean }
-  }>
-  chains: Map<unknown, unknown>
-  retirements: Map<unknown, Promise<void>>
-}
-
-/**
- * Reference {@link PersistenceCoordinator} vehicle and abstract-service coverage, backed by a
- * dependency-free map with atomic writes and no torn-tail marker. Supplying the map lets multiple
- * instances share materialized sessions, the in-memory analogue of reload over one artifact;
- * durable behavior is covered by the JSONL provider.
- */
-class MemoryPersistence extends SessionPersistence implements PersistenceBackend<never> {
-  override readonly supportsRawArtifacts = false
-
-  static inject = ['sessions']
-
-  override readonly name = 'session-persistence-memory'
-
-  /** The whole durable store: materialized sessions only (no lazy entries). */
-  private store: MemoryStore
-  private coordinator: PersistenceCoordinator<never>
-
-  constructor(ctx: Context, config?: MemoryConfig) {
-    super(ctx)
-    // Assign the store BEFORE constructing the coordinator: the coordinator's
-    // constructor installs the write path and synchronously seeds existing live
-    // sessions through loadStored(), so store must exist first.
-    this.store = config?.store ?? new Map<string, { meta: SessionHeader; events: SessionEvent[] }>()
-    this.coordinator = new PersistenceCoordinator<never>(this.ctx, this)
-  }
-
-  // --- Service API (delegated to the coordinator) ---
-
-  locate(_meta: SessionHeader): undefined {
-    return undefined
-  }
-
-  create(m: SessionHeader, inheritedEventCount?: SessionLogOffsetType): Promise<void> {
-    return this.coordinator.create(m, inheritedEventCount)
-  }
-
-  override ensureMaterialized(session: Session): Promise<void> {
-    return this.coordinator.ensureMaterialized(session)
-  }
-
-  append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
-    return this.coordinator.append(id, events)
-  }
-
-  override prepare(id: SessionId, signal?: AbortSignal): ReturnType<PersistenceCoordinator['prepare']> {
-    return this.coordinator.prepare(id, signal)
-  }
-
-  load(id: SessionId): Promise<SessionInspection> {
-    return this.coordinator.load(id).then(loaded => ({
-      meta: loaded.meta,
-      inheritedEventCount: loaded.inheritedEventCount,
-      events: [...loaded.events],
-    }))
-  }
-
-  inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection> {
-    return this.coordinator.inspect(id, signal)
-      .then(loaded => ({
-        meta: loaded.meta,
-        inheritedEventCount: loaded.inheritedEventCount,
-        events: [...loaded.events],
-      }))
-  }
-
-  borrowSession(id: SessionId, signal?: AbortSignal): ReturnType<PersistenceCoordinator['borrowSession']> {
-    return this.coordinator.borrowSession(id, signal)
-  }
-
-  readFrom(id: SessionId, fromSeq: SessionLogOffsetType, signal?: AbortSignal): Promise<SessionEventSuffix> {
-    return this.coordinator.readFrom(id, fromSeq, signal)
-  }
-
-  // --- PersistenceBackend hooks (the Map storage primitives) ---
-
-  // A Map-backed store has no torn tails, so `tornMarker` is never set.
-  async loadStored(id: SessionId): Promise<StoredPrefix<never> | undefined> {
-    const entry = this.store.get(id)
-    if (!entry) return undefined
-    return {
-      meta: structuredClone(entry.meta),
-      inheritedEventCount: SessionLogOffset(entry.inheritedEventCount ?? 0),
-      events: structuredClone(entry.events),
-      revision: memoryRevision(entry),
-    }
-  }
-
-  async readStoredRevision(id: SessionId): Promise<SessionPersistenceRevision | undefined> {
-    const entry = this.store.get(id)
-    return entry === undefined ? undefined : memoryRevision(entry)
-  }
-
-  async appendBatch(
-    storage: SessionStorageMetadata,
-    events: readonly SessionEvent[],
-    _isMaterialized: boolean,
-  ): Promise<void> {
-    // Defense-in-depth: the coordinator already validates serializability, but a
-    // durable store must reject non-JSON data at its own boundary too.
-    for (const e of events) {
-      if (!isJsonValue(e.data)) throw new Error(`event "${e.type}" carries non-JSON-serializable data`)
-    }
-    const { meta: m, inheritedEventCount } = storage
-    const existing = this.store.get(m.id)
-    if (!existing) {
-      // The coordinator sends the first batch for materialization; later batches append.
-      this.store.set(m.id, {
-        meta: structuredClone(m),
-        inheritedEventCount,
-        events: structuredClone(events) as SessionEvent[],
-      })
-    } else {
-      existing.events.push(...structuredClone(events) as SessionEvent[])
-    }
-  }
-
-  materializeHeader(storage: SessionStorageMetadata): Promise<void> {
-    const { meta: m, inheritedEventCount } = storage
-    this.store.set(m.id, { meta: structuredClone(m), inheritedEventCount, events: [] })
-    return Promise.resolve()
-  }
-
-  async commitRepair(
-    storage: SessionStorageMetadata,
-    _tornMarker: undefined,
-    closers: readonly SessionEvent[],
-  ): Promise<void> {
-    // No torn tails in a Map store, so `_tornMarker` is always undefined; only the
-    // synthetic closers are appended (the same DELETE+INSERT a DB backend does,
-    // minus the truncate).
-    const entry = this.store.get(storage.meta.id)
-    /* v8 ignore next -- commitRepair only runs for a materialized (stored) session */
-    if (!entry) return
-    if (closers.length > 0) entry.events.push(...structuredClone(closers) as SessionEvent[])
-  }
-
-  async list(signal?: AbortSignal): Promise<SessionHeader[]> {
-    signal?.throwIfAborted()
-    return [...this.store.values()].map(e => structuredClone(e.meta))
-  }
-
-  async listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]> {
-    signal?.throwIfAborted()
-    return [...this.store.values()].map(entry => ({
-      header: structuredClone(entry.meta),
-      revision: memoryRevision(entry),
-    }))
-  }
-}
-
-/** Controllable storage primitive for serialization and retirement failure tests. */
-class ControlledBackend implements PersistenceBackend<never> {
-  readonly name = 'session-persistence-controlled'
-  readonly store: MemoryStore = new Map()
-  readonly lifecycle: string[] = []
-  lastAppendedBatch: readonly SessionEvent[] | undefined
-  appendAttempts = 0
-  loadAttempts = 0
-  repairAttempts = 0
-  beforeAppend?: (attempt: number) => Promise<void>
-  beforeLoadStored?: (attempt: number, signal?: AbortSignal) => Promise<void>
-  /** When set, the declared seek hook delegates here so readFrom exercises it; unset throws (tests set it first). */
-  seekHook?: (
-    id: SessionId,
-    fromSeq: SessionLogOffsetType,
-    signal?: AbortSignal,
-  ) => Promise<StoredSuffix | undefined>
-
-  loadStoredFrom(
-    id: SessionId,
-    fromSeq: SessionLogOffsetType,
-    signal?: AbortSignal,
-  ): Promise<StoredSuffix | undefined> {
-    if (this.seekHook === undefined) throw new Error('seekHook not configured for this test')
-    return this.seekHook(id, fromSeq, signal)
-  }
-
-  async loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<never> | undefined> {
-    const attempt = ++this.loadAttempts
-    await this.beforeLoadStored?.(attempt, signal)
-    const entry = this.store.get(id)
-    if (entry === undefined) return undefined
-    return {
-      meta: structuredClone(entry.meta),
-      inheritedEventCount: SessionLogOffset(entry.inheritedEventCount ?? 0),
-      events: structuredClone(entry.events),
-      revision: memoryRevision(entry),
-    }
-  }
-
-  async readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<SessionPersistenceRevision | undefined> {
-    signal?.throwIfAborted()
-    const entry = this.store.get(id)
-    return entry === undefined ? undefined : memoryRevision(entry)
-  }
-
-  async appendBatch(
-    storage: SessionStorageMetadata,
-    events: readonly SessionEvent[],
-    _isMaterialized: boolean,
-  ): Promise<void> {
-    const { meta: m, inheritedEventCount } = storage
-    this.lastAppendedBatch = events
-    const attempt = ++this.appendAttempts
-    await this.beforeAppend?.(attempt)
-    const entry = this.store.get(m.id)
-    if (entry === undefined) {
-      this.store.set(m.id, {
-        meta: structuredClone(m),
-        inheritedEventCount,
-        events: structuredClone(events) as SessionEvent[],
-      })
-    } else {
-      entry.events.push(...structuredClone(events) as SessionEvent[])
-    }
-  }
-
-  async commitRepair(
-    storage: SessionStorageMetadata,
-    _tornMarker: undefined,
-    closers: readonly SessionEvent[],
-  ): Promise<void> {
-    this.repairAttempts += 1
-    const entry = this.store.get(storage.meta.id)
-    if (entry !== undefined) entry.events.push(...structuredClone(closers) as SessionEvent[])
-  }
-
-  async list(): Promise<SessionHeader[]> {
-    return [...this.store.values()].map(entry => structuredClone(entry.meta))
-  }
-
-  async close(): Promise<void> {
-    this.lifecycle.push('close')
-  }
-}
-
-runPersistenceContract('memory', async () => {
-  const ctx = new Context()
-  await ctx.plugin(SessionStore)
-  const fiber = await ctx.plugin(MemoryPersistence)
-  return {
-    persistence: ctx.sessionPersistence,
-    dispose: async () => { await fiber.dispose() },
-  }
-})
-
-describe('the inherited readRaw default', () => {
-  it('rejects unsupported reads distinctly from absence and honors an aborted signal', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(MemoryPersistence)
-    expect(ctx.sessionPersistence.supportsRawArtifacts).toBe(false)
-    await expect(
-      ctx.sessionPersistence.readRaw(SessionId('any-session')),
-    ).rejects.toThrow('does not expose raw artifacts')
-    await expect(
-      ctx.sessionPersistence.readRaw(SessionId('any-session'), AbortSignal.abort()),
-    ).rejects.toThrow()
-    // A non-Error abort reason falls back to a wrapped Error rejection.
-    const controller = new AbortController()
-    controller.abort('boom')
-    await expect(
-      ctx.sessionPersistence.readRaw(SessionId('any-session'), controller.signal),
-    ).rejects.toThrow('aborted')
-  })
-})
-
-// Each fixture shares one map across mounts. No `corruptTail` is supplied because map writes are
-// atomic; the suite asserts that skip while JSONL covers the repair branch.
-runCoordinatorContract('memory', async (): Promise<CoordinatorFixture> => {
-  const store: MemoryStore = new Map()
-  return {
-    mount: async ctx => ctx.plugin(MemoryPersistence, { store }),
-    cleanup: async () => { store.clear() },
-  }
-})
-
-describe('PersistenceCoordinator seed ownership', () => {
-  it('retains the immutable session seed without cloning it', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const session = ctx.sessions.create(SessionId('shared-seed'), { seed: oneTurnLog() })
-      const seed = session.snapshotEvents()
-      await ctx.sessions.flush(session)
-
-      expect(backend.lastAppendedBatch).toBe(seed)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-})
-
-describe('PersistenceCoordinator bounded writes', () => {
-  it('cancels the batching deadline when live initialization rejects', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const failure = new Error('initialization failed')
-    backend.beforeLoadStored = () => Promise.reject(failure)
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      new PersistenceCoordinator(inner, backend, {
-        preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
-        writeBatchMaxDelayMs: MAX_WRITE_BATCH_DELAY_MS,
-      })
-    }, { inject: ['sessions'] }))
-
-    try {
-      const session = ctx.sessions.create(SessionId('bounded-init-failure'))
-      session.append('turn/start', { turn: 1 })
-
-      await expect(ctx.sessions.flush(session)).rejects.toBe(failure)
-      expect(vi.getTimerCount()).toBe(0)
-      try {
-        await fiber.dispose()
-      } catch {
-        // The initialization failure was already asserted at the flush boundary.
-      }
-      expect(vi.getTimerCount()).toBe(0)
-    } finally {
-      try {
-        await fiber.dispose()
-      } catch {
-        // The expected initialization failure was asserted above; cleanup only
-        // needs to release any remaining parent effects.
-      }
-      try {
-        await ctx.fiber.dispose()
-      } catch {
-        // The child failure was already asserted through the backend fiber.
-      }
-      vi.useRealTimers()
-    }
-  })
-
-  it('starts a follow-up batch for events admitted during an in-flight write', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const appendGate = Promise.withResolvers<boolean>()
-    backend.beforeAppend = async (attempt) => {
-      if (attempt === 1) await appendGate.promise
-    }
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      new PersistenceCoordinator(inner, backend, {
-        preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
-        writeBatchMaxDelayMs: 1,
-      })
-    }, { inject: ['sessions'] }))
-
-    try {
-      const session = ctx.sessions.create(SessionId('bounded-follow-up'))
-      await ctx.sessions.flush(session)
-      session.append('turn/start', { turn: 1 })
-      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
-
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      appendGate.resolve(true)
-
-      await vi.waitFor(() => {
-        expect(backend.appendAttempts).toBe(2)
-        expect(backend.store.get(session.id)?.events.map(event => event.seq)).toEqual([0, 1])
-      })
-    } finally {
-      appendGate.resolve(true)
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('retries a failed overlapping background write at the explicit flush barrier', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const appendGate = Promise.withResolvers<boolean>()
-    backend.beforeAppend = async (attempt) => {
-      if (attempt === 1) {
-        await appendGate.promise
-        throw new Error('transient background failure')
-      }
-    }
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      new PersistenceCoordinator(inner, backend, {
-        preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
-        writeBatchMaxDelayMs: 1,
-      })
-    }, { inject: ['sessions'] }))
-
-    try {
-      const session = ctx.sessions.create(SessionId('bounded-flush-retry'))
-      await ctx.sessions.flush(session)
-      session.append('turn/start', { turn: 1 })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
-
-      const barriers = [ctx.sessions.flush(session), ctx.sessions.flush(session)]
-      appendGate.resolve(true)
-
-      await expect(Promise.all(barriers)).resolves.toEqual([true, true])
-      expect(backend.appendAttempts).toBe(2)
-      expect(backend.store.get(session.id)?.events.map(event => event.seq)).toEqual([0, 1])
-    } finally {
-      appendGate.resolve(true)
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-})
-
-describe('PersistenceCoordinator stored identity', () => {
-  it('rejects a mismatched backend header before repair or state publication', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const requested = SessionId('requested')
-    backend.store.set(requested, {
-      meta: meta('different'),
-      events: [{
-        type: 'turn/start',
-        seq: SessionSeq(0),
-        time: 1,
-        data: { turn: 1 },
-      }],
-    })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    try {
-      await expect(coordinator.load(requested)).rejects.toThrow(/stored session identity mismatch/)
-      expect(backend.repairAttempts).toBe(0)
-      expect((coordinator as unknown as CoordinatorInternals).states.size).toBe(0)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('rejects an inherited cut beyond the stored prefix before repair', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('invalid-inherited-cut')
-    backend.store.set(id, {
-      meta: { ...meta(id), isSeeded: true },
-      inheritedEventCount: SessionLogOffset(2),
-      events: [{
-        type: 'turn/start',
-        seq: SessionSeq(0),
-        time: 1,
-        data: { turn: 1 },
-      }],
-    })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    try {
-      await expect(coordinator.load(id)).rejects.toThrow(/inherited event count exceeds its stored event count/)
-      expect(backend.repairAttempts).toBe(0)
-      expect((coordinator as unknown as CoordinatorInternals).states.size).toBe(0)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('reserves a cold id across asynchronous storage repair', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('cold-load-reservation')
-    const header = meta(id)
-    const start: SessionEvent = {
-      type: 'turn/start',
-      seq: SessionSeq(0),
-      time: 1,
-      data: { turn: 1 },
-    }
-    backend.store.set(id, { meta: header, events: [start] })
-    const loadGate = Promise.withResolvers<boolean>()
-    backend.beforeLoadStored = async () => { await loadGate.promise }
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const loading = coordinator.load(id)
-      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
-
-      await expect(ctx.plugin(Object.assign((inner: Context) => {
-        inner.sessions.create(id, { seed: [start], meta: header })
-      }, { inject: ['sessions'] }))).rejects.toThrow(/persisted state already owns this identity/)
-      expect(ctx.sessions.get(id)).toBeUndefined()
-
-      loadGate.resolve(true)
-      const loaded = await loading
-      expect(loaded.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
-
-      const resumed = ctx.sessions.create(id, { seed: loaded.events, meta: loaded.meta })
-      await expect(ctx.sessions.flush(resumed)).resolves.toBe(true)
-    } finally {
-      loadGate.resolve(true)
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-})
-
-describe('PersistenceCoordinator session preparations', () => {
-  it.each([0, 1.5])('rejects invalid preparation cache capacity %s', (capacity) => {
-    const ctx = new Context()
-    const backend = new ControlledBackend()
-
-    expect(() => new PersistenceCoordinator(ctx, backend, {
-      preparedSessionCacheSize: capacity,
-      writeBatchMaxDelayMs: DEFAULT_WRITE_BATCH_MAX_DELAY_MS,
-    })).toThrow(/positive safe integer/)
-  })
-
-  it.each([0, 1.5, MAX_WRITE_BATCH_DELAY_MS + 1])('rejects invalid write batch delay %s', (delay) => {
-    const ctx = new Context()
-    const backend = new ControlledBackend()
-
-    expect(() => new PersistenceCoordinator(ctx, backend, {
-      preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
-      writeBatchMaxDelayMs: delay,
-    })).toThrow(/writeBatchMaxDelayMs must be an integer between/)
-  })
-
-  it('retries invalidated prepare and load reservations', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const prepareId = SessionId('prepare-reservation-retry')
-    const loadId = SessionId('load-reservation-retry')
-    backend.store.set(prepareId, { meta: meta(prepareId), events: oneTurnLog() })
-    backend.store.set(loadId, { meta: meta(loadId), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const preparations = (coordinator as unknown as {
-      preparations: { reserve: (...args: unknown[]) => Promise<unknown> }
-    }).preparations
-    const reserve = vi.spyOn(preparations, 'reserve')
-
-    try {
-      reserve.mockResolvedValueOnce(undefined)
-      const preparation = await coordinator.prepare(prepareId)
-      preparation[Symbol.dispose]()
-
-      reserve.mockResolvedValueOnce(undefined)
-      await expect(coordinator.load(loadId)).resolves.toMatchObject({ meta: { id: loadId } })
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('prefers a session that becomes live across preparation reads', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const prepareId = SessionId('prepare-became-live')
-    const loadId = SessionId('load-became-live')
-    const inspectId = SessionId('inspect-became-live')
-    const validatedInspectId = SessionId('validated-inspect-became-live')
-    const failedInspectId = SessionId('failed-inspect-became-live')
-    for (const id of [prepareId, loadId, inspectId, validatedInspectId]) {
-      backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    }
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const prepareLive = Session.create(prepareId, oneTurnLog(), meta(prepareId))
-      const prepareGet = vi.spyOn(ctx.sessions, 'get')
-        .mockReturnValueOnce(undefined)
-        .mockReturnValueOnce(prepareLive)
-      await expect(coordinator.prepare(prepareId)).rejects.toThrow(/while it is live/)
-      prepareGet.mockRestore()
-
-      const loadLive = Session.create(loadId, oneTurnLog(), meta(loadId))
-      const loadGet = vi.spyOn(ctx.sessions, 'get')
-        .mockReturnValueOnce(undefined)
-        .mockReturnValueOnce(loadLive)
-      await expect(coordinator.load(loadId)).resolves.toMatchObject({ meta: { id: loadId } })
-      loadGet.mockRestore()
-
-      const inspectLive = Session.create(inspectId, oneTurnLog(), meta(inspectId))
-      const inspectGet = vi.spyOn(ctx.sessions, 'get')
-        .mockReturnValueOnce(undefined)
-        .mockReturnValueOnce(inspectLive)
-      await expect(coordinator.inspect(inspectId)).resolves.toMatchObject({ meta: { id: inspectId } })
-      inspectGet.mockRestore()
-
-      const validatedInspectLive = Session.create(validatedInspectId, oneTurnLog(), meta(validatedInspectId))
-      const validatedInspectGet = vi.spyOn(ctx.sessions, 'get')
-        .mockReturnValueOnce(undefined)
-        .mockReturnValueOnce(undefined)
-        .mockReturnValueOnce(validatedInspectLive)
-      await expect(coordinator.inspect(validatedInspectId))
-        .resolves.toMatchObject({ meta: { id: validatedInspectId } })
-      validatedInspectGet.mockRestore()
-
-      const failedInspectLive = Session.create(failedInspectId, oneTurnLog(), meta(failedInspectId))
-      backend.beforeLoadStored = () => Promise.reject(new Error('load failed'))
-      const failedInspectGet = vi.spyOn(ctx.sessions, 'get')
-        .mockReturnValueOnce(undefined)
-        .mockReturnValueOnce(failedInspectLive)
-      await expect(coordinator.inspect(failedInspectId))
-        .resolves.toMatchObject({ meta: { id: failedInspectId } })
-      failedInspectGet.mockRestore()
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('rejects a prepared commit when durable state already has a live owner', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('prepared-commit-live-owner')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const owner = Session.create(id, oneTurnLog(), meta(id))
-    const states = (coordinator as unknown as {
-      states: Map<SessionId, {
-        meta: SessionHeader
-        cursor: SessionLogOffsetType
-        materialized: boolean
-        owner?: Session
-      }>
-    }).states
-    states.set(id, {
-      meta: owner.header,
-      cursor: SessionLogOffset(oneTurnLog().length),
-      materialized: true,
-      owner,
-    })
-
-    try {
-      await expect(coordinator.prepare(id)).rejects.toThrow(/live persistence owner/)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('rejects publication after a preparation state no longer matches', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('prepared-publication-mismatch')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const preparation = await coordinator.prepare(id)
-    const preparations = (coordinator as unknown as {
-      preparations: {
-        reservationFor: (session: Session) => { state: { cursor: SessionLogOffsetType } } | undefined
-      }
-    }).preparations
-    const reservation = preparations.reservationFor(preparation.session)
-    if (reservation === undefined) throw new Error('test preparation must stay reserved')
-    reservation.state.cursor = SessionLogOffset(reservation.state.cursor + 1)
-    const detach = ctx.sessions.enter(preparation.session)
-
-    try {
-      expect(() => { ctx.sessions.announce(preparation.session) }).toThrow(/no longer matches/)
-    } finally {
-      detach()
-      preparation[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('observes a restored suffix initialization failure', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('prepared-suffix-init-failure')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const preparation = await coordinator.prepare(id)
-    const internals = coordinator as unknown as {
-      preparations: { reservationFor: (session: Session) => object | undefined }
-      attachPrepared: (session: Session, reservation: object) => { init: Promise<void> }
-    }
-    const reservation = internals.preparations.reservationFor(preparation.session)
-    if (reservation === undefined) throw new Error('test preparation must stay reserved')
-    const failure = new Error('restored suffix append failed')
-    backend.beforeAppend = () => Promise.reject(failure)
-    preparation.session.append('turn/start', { turn: 2 })
-
-    try {
-      const live = internals.attachPrepared(preparation.session, reservation)
-      await expect(live.init).rejects.toBe(failure)
-    } finally {
-      preparation[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('writes new events after publishing a preparation with no unpublished suffix', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('prepared-live-write')
-    const stored = [
-      ...oneTurnLog(),
-      { type: 'session/end-seed', seq: 6, time: 7, data: {} } as SessionEvent,
-    ]
-    backend.store.set(id, { meta: meta(id), events: stored })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const preparation = await coordinator.prepare(id)
-    const detach = ctx.sessions.enter(preparation.session)
-
-    try {
-      ctx.sessions.announce(preparation.session)
-      preparation.session.append('turn/start', { turn: 2 })
-      preparation.session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
-
-      await expect(ctx.sessions.flush(preparation.session)).resolves.toBe(true)
-      expect(backend.store.get(id)?.events.map(event => event.seq))
-        .toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8])
-    } finally {
-      detach()
-      preparation[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('reuses the exact Session from inspect through repeated unpublished prepare calls', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('inspect-prepare-reuse')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    let first: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-    let second: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-
-    try {
-      const inspected = await coordinator.inspect(id)
-      first = await coordinator.prepare(id)
-
-      expect(backend.loadAttempts).toBe(1)
-      expect(first.session.snapshotEvents()[0]).toBe(inspected.events[0])
-
-      first[Symbol.dispose]()
-      second = await coordinator.prepare(id)
-      expect(second.session).toBe(first.session)
-      expect(backend.loadAttempts).toBe(1)
-    } finally {
-      second?.[Symbol.dispose]()
-      first?.[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('reloads a cached inspection after the durable revision changes', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('inspect-revision-refresh')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const first = await coordinator.inspect(id)
-      backend.store.get(id)!.events.push(
-        { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-        { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-      )
-
-      const refreshed = await coordinator.inspect(id)
-      expect(refreshed.events).toHaveLength(8)
-      expect(refreshed.events[0]).not.toBe(first.events[0])
-      expect(backend.loadAttempts).toBe(2)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('does not restore from a cached inspection after the durable revision changes', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('prepare-revision-refresh')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    let preparation: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-
-    try {
-      const inspected = await coordinator.inspect(id)
-      backend.store.get(id)!.events.push(
-        { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-        { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-      )
-
-      preparation = await coordinator.prepare(id)
-      expect(preparation.session.snapshotEvents()).toHaveLength(9)
-      expect(preparation.session.snapshotEvents()[0]).not.toBe(inspected.events[0])
-      expect(backend.loadAttempts).toBe(2)
-    } finally {
-      preparation?.[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('retains a reserved preparation when inspection observes a newer external revision', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('reserved-inspect-revision-race')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    let preparation: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-    let detach: (() => void) | undefined
-
-    try {
-      const cached = await coordinator.inspect(id)
-      preparation = await coordinator.prepare(id)
-      backend.store.get(id)!.events.push(
-        { type: 'turn/start', seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-        { type: 'turn/end', seq: SessionSeq(7), time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-      )
-
-      await expect(coordinator.inspect(id)).resolves.toBe(cached)
-      const preparations = (coordinator as unknown as {
-        preparations: { reservationFor: (session: Session) => object | undefined }
-      }).preparations
-      expect(preparations.reservationFor(preparation.session)).toBeDefined()
-
-      detach = ctx.sessions.enter(preparation.session)
-      expect(() => { ctx.sessions.announce(preparation!.session) }).not.toThrow()
-      expect(preparations.reservationFor(preparation.session)).toBeUndefined()
-    } finally {
-      detach?.()
-      preparation?.[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('queues a same-tick cold append behind preparation readiness', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('inspect-cold-append-race')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const inspection = coordinator.inspect(id)
-      const append = coordinator.append(id, [{
-        type: 'turn/start',
-        seq: SessionSeq(oneTurnLog().length),
-        time: 7,
-        data: { turn: 2 },
-      }])
-
-      await expect(inspection).resolves.toMatchObject({
-        meta: { id },
-        events: [...oneTurnLog(), { seq: 6 }, { seq: 7 }],
-      })
-      await expect(append).resolves.toBeUndefined()
-      expect(backend.loadAttempts).toBe(2)
-      expect(backend.store.get(id)?.events).toHaveLength(oneTurnLog().length + 1)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('allows a same-tick cold append to start before inspection', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('cold-append-inspect-race')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const append = coordinator.append(id, [{
-        type: 'turn/start',
-        seq: SessionSeq(oneTurnLog().length),
-        time: 7,
-        data: { turn: 2 },
-      }])
-      const inspection = coordinator.inspect(id)
-
-      await expect(append).resolves.toBeUndefined()
-      await expect(inspection).resolves.toMatchObject({
-        meta: { id },
-        events: [...oneTurnLog(), { seq: 6 }, { seq: 7 }],
-      })
-      expect(backend.loadAttempts).toBe(2)
-      expect(backend.store.get(id)?.events).toHaveLength(oneTurnLog().length + 1)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('retries cold append adoption when the prepared revision becomes stale', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('append-adoption-revision-refresh')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    const readStoredRevision = backend.readStoredRevision.bind(backend)
-    vi.spyOn(backend, 'readStoredRevision')
-      .mockResolvedValueOnce(SessionPersistenceRevision('stale-revision'))
-      .mockImplementation(readStoredRevision)
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      await coordinator.append(id, [{
-        type: 'turn/start',
-        seq: SessionSeq(oneTurnLog().length),
-        time: 7,
-        data: { turn: 2 },
-      }])
-
-      expect(backend.loadAttempts).toBe(2)
-      expect(backend.appendAttempts).toBe(1)
-      expect(backend.store.get(id)?.events).toHaveLength(oneTurnLog().length + 1)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('inspects an open live turn without balancing it', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const session = ctx.sessions.create(SessionId('inspect-live-open-turn'))
-      session.append('turn/start', { turn: 1 })
-
-      const inspected = await coordinator.inspect(session.id)
-      expect(inspected.events).toBe(session.snapshotEvents())
-      expect(inspected.events.map(event => event.type)).toEqual(['turn/start'])
-      await expect(coordinator.load(session.id)).rejects.toThrow(/live turn is open/)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('keeps synthetic recovery in memory during inspect and commits it only once on prepare', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('inspect-repair-commit')
-    backend.store.set(id, {
-      meta: meta(id),
-      events: [{
-        type: 'turn/start',
-        seq: SessionSeq(0),
-        time: 1,
-        data: { turn: 1 },
-      }],
-    })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    let first: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-    let second: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-
-    try {
-      const inspected = await coordinator.inspect(id)
-      expect(inspected.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
-      expect(backend.store.get(id)?.events.map(event => event.type)).toEqual(['turn/start'])
-      expect(backend.repairAttempts).toBe(0)
-
-      first = await coordinator.prepare(id)
-      expect(backend.repairAttempts).toBe(1)
-      expect(backend.store.get(id)?.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
-      first[Symbol.dispose]()
-
-      second = await coordinator.prepare(id)
-      expect(second.session).toBe(first.session)
-      expect(backend.loadAttempts).toBe(2)
-      expect(backend.repairAttempts).toBe(1)
-    } finally {
-      second?.[Symbol.dispose]()
-      first?.[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('reloads the committed graph when another writer appends after repair', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('repair-external-append')
-    backend.store.set(id, {
-      meta: meta(id),
-      events: [{ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }],
-    })
-    const commitRepair = backend.commitRepair.bind(backend)
-    vi.spyOn(backend, 'commitRepair').mockImplementation(async (header, tornMarker, closers) => {
-      await commitRepair(header, tornMarker, closers)
-      const entry = backend.store.get(id)
-      if (entry === undefined) throw new Error('test repair must keep storage materialized')
-      const seq = entry.events.length
-      entry.events.push(
-        { type: 'turn/start', seq: SessionSeq(seq), time: 3, data: { turn: 2 } },
-        { type: 'turn/end', seq: SessionSeq(seq + 1), time: 4, data: { turn: 2, reason: { kind: 'completed' } } },
-      )
-    })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    let preparation: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-
-    try {
-      preparation = await coordinator.prepare(id)
-
-      expect(preparation.session.snapshotEvents().map(event => event.type)).toEqual([
-        'turn/start',
-        'turn/end',
-        'turn/start',
-        'turn/end',
-        'session/end-seed',
-      ])
-      expect(backend.loadAttempts).toBe(2)
-      expect(backend.repairAttempts).toBe(1)
-    } finally {
-      preparation?.[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('rejects preparation when storage disappears during the post-repair reload', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('repair-disappeared')
-    backend.store.set(id, {
-      meta: meta(id),
-      events: [{ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 } }],
-    })
-    const commitRepair = backend.commitRepair.bind(backend)
-    vi.spyOn(backend, 'commitRepair').mockImplementation(async (header, tornMarker, closers) => {
-      await commitRepair(header, tornMarker, closers)
-      backend.store.delete(id)
-    })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      await expect(coordinator.prepare(id)).rejects.toThrow(/not found/)
-      expect(backend.repairAttempts).toBe(1)
-      expect(backend.loadAttempts).toBe(2)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('waits for an existing reservation and reuses it after release', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('prepare-reservation-wait')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    let first: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-    let second: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-
-    try {
-      first = await coordinator.prepare(id)
-      let secondResolved = false
-      const waiting = coordinator.prepare(id).then((preparation) => {
-        secondResolved = true
-        return preparation
-      })
-      await Promise.resolve()
-      expect(secondResolved).toBe(false)
-
-      first[Symbol.dispose]()
-      second = await waiting
-      expect(second.session).toBe(first.session)
-      expect(backend.loadAttempts).toBe(1)
-    } finally {
-      second?.[Symbol.dispose]()
-      first?.[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('evicts only ready preparations by LRU capacity', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const firstId = SessionId('preparation-lru-first')
-    const secondId = SessionId('preparation-lru-second')
-    backend.store.set(firstId, { meta: meta(firstId), events: oneTurnLog() })
-    backend.store.set(secondId, { meta: meta(secondId), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend, {
-        preparedSessionCacheSize: 1,
-        writeBatchMaxDelayMs: DEFAULT_WRITE_BATCH_MAX_DELAY_MS,
-      })
-    }, { inject: ['sessions'] }))
-
-    try {
-      await coordinator.inspect(firstId)
-      await coordinator.inspect(secondId)
-      await coordinator.inspect(firstId)
-      expect(backend.loadAttempts).toBe(3)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('rejects append while an unpublished preparation owns the persisted cursor', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('reserved-append')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    let preparation: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-
-    try {
-      preparation = await coordinator.prepare(id)
-      await expect(coordinator.append(id, [{
-        type: 'turn/start',
-        seq: SessionSeq(oneTurnLog().length),
-        time: 7,
-        data: { turn: 2 },
-      }])).rejects.toThrow(/persisted preparation is reserved/)
-    } finally {
-      preparation?.[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-})
-
-describe('PersistenceCoordinator seek reads', () => {
-  it('loads the whole prefix only when a bounded legacy suffix needs earlier message identities', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('seek-read-from-legacy')
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    backend.seekHook = async (hookId, fromSeq) => {
-      const entry = backend.store.get(hookId)
-      if (entry === undefined) return undefined
-      return {
-        meta: structuredClone(entry.meta),
-        inheritedEventCount: SessionLogOffset(entry.inheritedEventCount ?? 0),
-        events: entry.events.filter(e => e.seq >= fromSeq),
-      }
-    }
-
-    try {
-      const assertLegacySuffixUsesWholePrefix = async (
-        events: SessionEvent[],
-        fromSeq: SessionLogOffsetType,
-        firstType: SessionEvent['type'],
-      ): Promise<void> => {
-        backend.store.set(id, { meta: meta(id), events })
-        const loadsBefore = backend.loadAttempts
-        const result = await coordinator.readFrom(id, fromSeq)
-        expect(result.events[0]?.type).toBe(firstType)
-        expect(backend.loadAttempts).toBe(loadsBefore + 1)
-      }
-      const legacyMessages = legacyMessageLog()
-      await assertLegacySuffixUsesWholePrefix(legacyMessages, SessionLogOffset(1), 'user/message')
-      await assertLegacySuffixUsesWholePrefix(legacyMessages, SessionLogOffset(3), 'assistant/message')
-      await assertLegacySuffixUsesWholePrefix(legacyMessages, SessionLogOffset(5), 'tool/result')
-      await assertLegacySuffixUsesWholePrefix(preReactLoopLog(), SessionLogOffset(3), 'user/message')
-
-      backend.store.set(id, { meta: meta(id), events: legacyMessages })
-      const directCurrent = await coordinator.readFrom(id, SessionLogOffset(0))
-      backend.store.set(id, { meta: meta(id), events: [...directCurrent.events] })
-      const loadsBeforeCurrent = backend.loadAttempts
-      await coordinator.readFrom(id, SessionLogOffset(1))
-      await coordinator.readFrom(id, SessionLogOffset(3))
-      await coordinator.readFrom(id, SessionLogOffset(5))
-      expect(backend.loadAttempts).toBe(loadsBeforeCurrent)
-
-      for (const [type, data] of [
-        ['user/message', {}],
-        ['assistant/message', {}],
-        ['tool/result', {}],
-      ] as const) {
-        backend.store.set(id, {
-          meta: meta(id),
-          events: [{ type, seq: 0, time: 1, data } as unknown as SessionEvent],
-        })
-        const loadsBefore = backend.loadAttempts
-        await expect(coordinator.readFrom(id, SessionLogOffset(0))).rejects.toThrow('lacks an identified message')
-        expect(backend.loadAttempts).toBe(loadsBefore)
-      }
-      backend.store.set(id, {
-        meta: meta(id),
-        events: [{
-          type: 'external/null', seq: 0, time: 1, data: null, ignorable: true,
-        } as unknown as SessionEvent],
-      })
-      const loadsBeforeNullData = backend.loadAttempts
-      expect((await coordinator.readFrom(id, SessionLogOffset(0))).events[0]?.data).toBeNull()
-      expect(backend.loadAttempts).toBe(loadsBeforeNullData)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-})
-
-describe('PersistenceCoordinator observation cancellation', () => {
-  it('borrows live Sessions before, during, and after cold source validation', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const afterBorrowId = SessionId('borrow-became-live-before-validation')
-    const afterValidationId = SessionId('borrow-became-live-after-validation')
-    for (const id of [afterBorrowId, afterValidationId]) {
-      backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    }
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const immediate = ctx.sessions.create(SessionId('borrow-already-live'))
-      const immediateSource = await coordinator.borrowSession(immediate.id)
-      expect(immediateSource).toMatchObject({ source: 'live', inspection: { meta: { id: immediate.id } } })
-      immediateSource[Symbol.dispose]()
-
-      const afterBorrow = Session.create(afterBorrowId, oneTurnLog(), meta(afterBorrowId))
-      const afterBorrowGet = vi.spyOn(ctx.sessions, 'get')
-        .mockReturnValueOnce(undefined)
-        .mockReturnValue(afterBorrow)
-      const attachedSource = await coordinator.borrowSession(afterBorrowId)
-      expect(attachedSource).toMatchObject({ source: 'live', inspection: { meta: { id: afterBorrowId } } })
-      attachedSource[Symbol.dispose]()
-      afterBorrowGet.mockRestore()
-
-      const afterValidation = Session.create(afterValidationId, oneTurnLog(), meta(afterValidationId))
-      const afterValidationGet = vi.spyOn(ctx.sessions, 'get')
-        .mockReturnValueOnce(undefined)
-        .mockReturnValueOnce(undefined)
-        .mockReturnValue(afterValidation)
-      const publishedSource = await coordinator.borrowSession(afterValidationId)
-      expect(publishedSource).toMatchObject({
-        source: 'live', inspection: { meta: { id: afterValidationId } },
-      })
-      publishedSource[Symbol.dispose]()
-      afterValidationGet.mockRestore()
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('returns and releases a current prepared observation', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('borrow-current-prepared')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const source = await coordinator.borrowSession(id)
-      expect(source).toMatchObject({ source: 'prepared', inspection: { meta: { id } } })
-      source[Symbol.dispose]()
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('reloads a stale prepared observation and retains one claimed concurrently', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const staleId = SessionId('borrow-stale-prepared')
-    const retainedId = SessionId('borrow-retained-prepared')
-    for (const id of [staleId, retainedId]) {
-      backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    }
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const readRevision = backend.readStoredRevision.bind(backend)
-      const revision = vi.spyOn(backend, 'readStoredRevision')
-        .mockResolvedValueOnce(SessionPersistenceRevision('stale'))
-        .mockImplementation(readRevision)
-      const stale = await coordinator.borrowSession(staleId)
-      expect(stale.source).toBe('prepared')
-      expect(backend.loadAttempts).toBe(2)
-      stale[Symbol.dispose]()
-      revision.mockRestore()
-
-      const preparations = (coordinator as unknown as {
-        preparations: { discardReady: (id: SessionId, source: unknown) => string }
-      }).preparations
-      vi.spyOn(backend, 'readStoredRevision').mockResolvedValue(SessionPersistenceRevision('changed'))
-      const discard = vi.spyOn(preparations, 'discardReady').mockReturnValue('retained')
-      const retained = await coordinator.borrowSession(retainedId)
-      expect(retained.source).toBe('prepared')
-      expect(discard).toHaveBeenCalledOnce()
-      retained[Symbol.dispose]()
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('falls back to a concurrently attached Session after revision validation fails', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('borrow-failed-validation-became-live')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const attached = Session.create(id, oneTurnLog(), meta(id))
-    const get = vi.spyOn(ctx.sessions, 'get')
-      .mockReturnValueOnce(undefined)
-      .mockReturnValueOnce(undefined)
-      .mockReturnValue(attached)
-    vi.spyOn(backend, 'readStoredRevision').mockRejectedValue(new Error('revision failed'))
-
-    try {
-      const source = await coordinator.borrowSession(id)
-      expect(source).toMatchObject({ source: 'live', inspection: { meta: { id } } })
-      source[Symbol.dispose]()
-    } finally {
-      get.mockRestore()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('rethrows revision validation failure when no live Session won the race', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('borrow-failed-validation')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    const failure = new Error('revision failed')
-    vi.spyOn(backend, 'readStoredRevision').mockRejectedValue(failure)
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      await expect(coordinator.borrowSession(id)).rejects.toBe(failure)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('promptly rejects a queued inspect without invoking it and keeps the same-id chain healthy', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('queued-inspect-cancellation')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    const loadGate = Promise.withResolvers<boolean>()
-    backend.beforeLoadStored = async (attempt) => {
-      if (attempt === 1) await loadGate.promise
-    }
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      const prior = coordinator.inspect(id)
-      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
-      const controller = new AbortController()
-      const reason = new Error('queued inspect cancelled')
-      const queued = coordinator.inspect(id, controller.signal)
-      let observedReason: unknown
-      const observedAbort = queued.catch((error: unknown) => {
-        observedReason = error
-      })
-
-      controller.abort(reason)
-
-      await vi.waitFor(() => { expect(observedReason).toBe(reason) })
-      expect(backend.loadAttempts).toBe(1)
-      const subsequent = coordinator.inspect(id)
-      expect(backend.loadAttempts).toBe(1)
-
-      loadGate.resolve(true)
-      await expect(prior).resolves.toMatchObject({ meta: { id } })
-      await observedAbort
-      await expect(subsequent).resolves.toMatchObject({ meta: { id } })
-      expect(backend.loadAttempts).toBe(1)
-      await vi.waitFor(() => {
-        expect((coordinator as unknown as CoordinatorInternals).chains.size).toBe(0)
-      })
-    } finally {
-      loadGate.resolve(true)
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('keeps a shared cold read alive when its creating inspect is cancelled', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('creating-inspect-cancellation')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    const loadGate = Promise.withResolvers<boolean>()
-    backend.beforeLoadStored = () => loadGate.promise.then(() => undefined)
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    let prepared: Awaited<ReturnType<typeof coordinator.prepare>> | undefined
-
-    try {
-      const controller = new AbortController()
-      const reason = new Error('creating inspect cancelled')
-      const inspection = coordinator.inspect(id, controller.signal)
-      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
-      const reservation = coordinator.prepare(id)
-
-      controller.abort(reason)
-      await expect(inspection).rejects.toBe(reason)
-      loadGate.resolve(true)
-      prepared = await reservation
-      expect(prepared.session.id).toBe(id)
-      expect(backend.loadAttempts).toBe(1)
-    } finally {
-      loadGate.resolve(true)
-      prepared?.[Symbol.dispose]()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('preserves inspect cancellation when the session concurrently becomes live', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('cancelled-inspect-became-live')
-    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
-    const controller = new AbortController()
-    const reason = new Error('inspect cancelled while publishing')
-    backend.beforeLoadStored = async () => {
-      controller.abort(reason)
-      throw new Error('load stopped after cancellation')
-    }
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const live = Session.create(id, oneTurnLog(), meta(id))
-    const get = vi.spyOn(ctx.sessions, 'get')
-      .mockReturnValueOnce(undefined)
-      .mockReturnValueOnce(live)
-
-    try {
-      await expect(coordinator.inspect(id, controller.signal)).rejects.toBe(reason)
-    } finally {
-      get.mockRestore()
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('readFrom via the seek hook: serves the suffix, maps undefined to not-found, and relays hook failures by abort state', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const id = SessionId('seek-read-from')
-    const log = oneTurnLog()
-    backend.store.set(id, { meta: meta(id), events: log })
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-
-    try {
-      // Happy path through the hook: only the suffix comes back, detached.
-      backend.seekHook = async (hookId, fromSeq) => {
-        const entry = backend.store.get(hookId)
-        if (entry === undefined) return undefined
-        return {
-          meta: structuredClone(entry.meta),
-          inheritedEventCount: SessionLogOffset(entry.inheritedEventCount ?? 0),
-          events: entry.events.filter(e => e.seq >= fromSeq),
-        }
-      }
-      const suffix = await coordinator.readFrom(id, SessionLogOffset(3))
-      expect(suffix.events).toEqual(log.slice(3))
-      // The hook's `undefined` is the backend contract's not-found result.
-      await expect(coordinator.readFrom(SessionId('missing-seek'), SessionLogOffset(0)))
-        .rejects.toThrow('not found')
-
-      // A hook failure with no cancellation in play propagates as-is.
-      const hookFailure = new Error('seek backend exploded')
-      backend.seekHook = () => Promise.reject(hookFailure)
-      await expect(coordinator.readFrom(id, SessionLogOffset(0))).rejects.toBe(hookFailure)
-
-      // A hook failure after cancellation surfaces the caller's abort reason,
-      // not the backend's internal teardown error. The abort fires only once
-      // the hook is provably entered, so the failure exercises the catch (not
-      // the pre-invocation throwIfAborted).
-      const controller = new AbortController()
-      const reason = new Error('read-from cancelled mid-hook')
-      let hookEntered = false
-      backend.seekHook = async (_hookId, _fromSeq, signal) => {
-        hookEntered = true
-        await new Promise<void>((resolve) => { signal?.addEventListener('abort', () => { resolve() }, { once: true }) })
-        throw new Error('backend teardown after abort')
-      }
-      const pending = coordinator.readFrom(id, SessionLogOffset(0), controller.signal)
-      const observed = pending.catch((error: unknown) => error)
-      await vi.waitFor(() => { expect(hookEntered).toBe(true) })
-      controller.abort(reason)
-      expect(await observed).toBe(reason)
-    } finally {
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('rejects a cancelled inspect while an in-flight retirement drain is still pending', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
-    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const internals = coordinator as unknown as CoordinatorInternals
-    const appendGate = Promise.withResolvers<boolean>()
-    backend.beforeAppend = async () => { await appendGate.promise }
-
-    try {
-      const id = SessionId('retiring-inspect')
-      let session!: Session
-      const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        session = inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      session.append('turn/start', { turn: 1 })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      // Dispose the session so retirement starts; its append is gated, so the
-      // retirement promise stays pending in the coordinator.
-      await sessionFiber.dispose()
-      await vi.waitFor(() => { expect(internals.retirements.has(id)).toBe(true) })
-      const baselineLoads = backend.loadAttempts
-
-      const controller = new AbortController()
-      const reason = new Error('inspect cancelled during retirement')
-      const pending = coordinator.inspect(id, controller.signal)
-      let observedReason: unknown
-      const observed = pending.catch((error: unknown) => { observedReason = error })
-
-      // Cancel before the gated retirement can settle: the inspect must reject
-      // promptly instead of waiting for the drain, and must never reach the
-      // backend read.
-      controller.abort(reason)
-      await vi.waitFor(() => { expect(observedReason).toBe(reason) })
-      expect(backend.loadAttempts).toBe(baselineLoads)
-
-      appendGate.resolve(true)
-      await observed
-    } finally {
-      appendGate.resolve(true)
-      await backendFiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-})
-
-describe('PersistenceCoordinator retirement', () => {
-  it('a retiring unmaterialized owner without buffered events releases its id', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const loadGate = Promise.withResolvers<boolean>()
-    backend.beforeLoadStored = async (attempt) => {
-      if (attempt === 1) await loadGate.promise
-    }
-
-    try {
-      const id = SessionId('retiring-lazy-owner')
-      const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
-      await firstFiber.dispose()
-
-      let reuse!: Session
-      await ctx.plugin(Object.assign((inner: Context) => {
-        reuse = inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      const reuseFlush = ctx.sessions.flush(reuse)
-
-      loadGate.resolve(true)
-      await expect(reuseFlush).resolves.toBe(true)
-    } finally {
-      loadGate.resolve(true)
-      await backendFiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('a superseded retirement leaves the successor lifecycle\'s pending drain in place', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
-    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const internals = coordinator as unknown as CoordinatorInternals
-    const readGate = Promise.withResolvers<boolean>()
-
-    try {
-      const id = SessionId('superseded-retirement')
-      // First lifecycle: unmaterialized (zero events), so a same-id successor
-      // may legally reclaim the abandoned id later.
-      let first!: Session
-      const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        first = inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      await ctx.sessions.flush(first)
-
-      // Occupy the per-id serialize chain with a gated physical read:
-      // inspect() correctly borrows the still-live Session without entering
-      // the backend chain, while both retirements must queue behind readFrom().
-      const readEntered = Promise.withResolvers<undefined>()
-      backend.seekHook = async () => {
-        readEntered.resolve(undefined)
-        await readGate.promise
-        return undefined
-      }
-      const parked = coordinator.readFrom(id, SessionLogOffset(0)).catch((error: unknown) => error)
-      await readEntered.promise
-
-      // First retirement queues behind the gate and stays pending.
-      await firstFiber.dispose()
-      await vi.waitFor(() => { expect(internals.retirements.has(id)).toBe(true) })
-      const firstRetirement = internals.retirements.get(id)
-
-      // Successor lifecycle retires while the first drain is still in flight:
-      // retire() replaces the map entry synchronously.
-      const secondFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      await secondFiber.dispose()
-      await vi.waitFor(() => {
-        expect(internals.retirements.get(id)).not.toBe(firstRetirement)
-      })
-
-      // Release the chain: the first drain settles and its forget() must not
-      // delete the successor's entry (exact-entry guard); the successor's own
-      // forget() then clears the map.
-      readGate.resolve(true)
-      expect(await parked).toBeInstanceOf(Error) // the parked inspect (not found) is observed
-      await firstRetirement
-      await vi.waitFor(() => { expect(internals.retirements.has(id)).toBe(false) })
-    } finally {
-      readGate.resolve(true)
-      await backendFiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('a replacement queued before retirement cleanup still collides with the live owner', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const appendGate = Promise.withResolvers<boolean>()
-
-    try {
-      const id = SessionId('retiring-live-owner')
-      let first!: Session
-      const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        first = inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      await ctx.sessions.flush(first)
-      backend.beforeAppend = async () => { await appendGate.promise }
-      first.append('turn/start', { turn: 1 })
-      first.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
-      await firstFiber.dispose()
-
-      let reuse!: Session
-      await ctx.plugin(Object.assign((inner: Context) => {
-        reuse = inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      const reuseFlush = ctx.sessions.flush(reuse)
-
-      appendGate.resolve(true)
-      await expect(reuseFlush).rejects.toThrow(/bound to a different live session/)
-      expect(backend.store.get(id)?.events.map(event => event.seq)).toEqual([0, 1])
-    } finally {
-      appendGate.resolve(true)
-      await backendFiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('a racing cold load survives retirement cleanup and rejects same-id reuse', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
-    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const appendGate = Promise.withResolvers<boolean>()
-    const loadGate = Promise.withResolvers<boolean>()
-
-    try {
-      const id = SessionId('retiring-buffered-owner')
-      let first!: Session
-      const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        first = inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      await ctx.sessions.flush(first)
-      backend.beforeAppend = async () => { await appendGate.promise }
-      first.append('turn/start', { turn: 1 })
-      first.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
-      await firstFiber.dispose()
-      const baselineLoads = backend.loadAttempts
-      backend.beforeLoadStored = async () => { await loadGate.promise }
-      const coldLoad = coordinator.load(id)
-
-      appendGate.resolve(true)
-      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(baselineLoads + 1) })
-
-      await expect(ctx.plugin(Object.assign((inner: Context) => {
-        inner.sessions.create(id)
-      }, { inject: ['sessions'] }))).rejects.toThrow(/persisted state already owns this identity/)
-
-      loadGate.resolve(true)
-      await expect(coldLoad).resolves.toMatchObject({
-        events: [{ seq: 0 }, { seq: 1 }],
-      })
-
-      let reuse!: Session
-      await ctx.plugin(Object.assign((inner: Context) => {
-        reuse = inner.sessions.create(id)
-      }, { inject: ['sessions'] }))
-      await expect(ctx.sessions.flush(reuse)).rejects.toThrow(/id collision/)
-      await vi.waitFor(() => {
-        expect(backend.store.get(id)?.events.map(event => event.seq)).toEqual([0, 1])
-      })
-    } finally {
-      appendGate.resolve(true)
-      loadGate.resolve(true)
-      await backendFiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('a settled chain tail cannot delete a newer operation for the same id', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const internals = coordinator as unknown as CoordinatorInternals
-    const first = Promise.withResolvers<boolean>()
-    const second = Promise.withResolvers<boolean>()
-    backend.beforeAppend = async (attempt) => {
-      if (attempt === 1) await first.promise
-      if (attempt === 2) await second.promise
-    }
-
-    try {
-      const id = SessionId('chain-tail')
-      await coordinator.create(meta(id))
-      const firstAppend = coordinator.append(id, [{
-        type: 'turn/start',
-        seq: SessionSeq(0),
-        time: 1,
-        data: { turn: 1 },
-      }])
-      const secondAppend = coordinator.append(id, [{
-        type: 'turn/end',
-        seq: SessionSeq(1),
-        time: 2,
-        data: { turn: 1, reason: { kind: 'completed' } },
-      }])
-
-      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
-      first.resolve(true)
-      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(2) })
-      expect(internals.chains.size).toBe(1)
-      second.resolve(true)
-      await Promise.all([firstAppend, secondAppend])
-      await vi.waitFor(() => { expect(internals.chains.size).toBe(0) })
-      expect(backend.store.get(id)?.events.map(event => event.seq)).toEqual([0, 1])
-    } finally {
-      first.resolve(true)
-      second.resolve(true)
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('backend teardown retries a failed session retirement before close', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
-    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const internals = coordinator as unknown as CoordinatorInternals
-    let retryEnabled = false
-    backend.beforeAppend = async () => {
-      if (!retryEnabled) {
-        backend.lifecycle.push('append-failed')
-        throw new Error('transient append failure')
-      }
-      backend.lifecycle.push('append-committed')
-    }
-
-    try {
-      let session!: Session
-      const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        session = inner.sessions.create(SessionId('retry-retirement'))
-      }, { inject: ['sessions'] }))
-      session.append('turn/start', { turn: 1 })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      await sessionFiber.dispose()
-
-      await vi.waitFor(() => {
-        expect(backend.appendAttempts).toBeGreaterThanOrEqual(1)
-        expect([...internals.live.values()][0]?.writes.pending).toEqual(expect.arrayContaining([
-          expect.objectContaining({ seq: 0 }),
-          expect.objectContaining({ seq: 1 }),
-        ]))
-      })
-
-      retryEnabled = true
-      await backendFiber.dispose()
-      expect(backend.store.get(SessionId('retry-retirement'))?.events.map(event => event.seq)).toEqual([0, 1])
-      expect(backend.lifecycle.at(-2)).toBe('append-committed')
-      expect(backend.lifecycle.at(-1)).toBe('close')
-    } finally {
-      await backendFiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('backend teardown waits for an in-flight session retirement before close', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
-    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const internals = coordinator as unknown as CoordinatorInternals
-    const appendGate = Promise.withResolvers<boolean>()
-    backend.beforeAppend = async () => {
-      backend.lifecycle.push('append-started')
-      await appendGate.promise
-      backend.lifecycle.push('append-committed')
-    }
-
-    try {
-      let session!: Session
-      const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        session = inner.sessions.create(SessionId('inflight-retirement'))
-      }, { inject: ['sessions'] }))
-      session.append('turn/start', { turn: 1 })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      await sessionFiber.dispose()
-      await vi.waitFor(() => {
-        expect(backend.appendAttempts).toBe(1)
-        expect(internals.live.size).toBe(1)
-        expect([...internals.live.values()][0]?.writes.active).toBeInstanceOf(Promise)
-      })
-
-      let disposed = false
-      const teardown = backendFiber.dispose().then(() => { disposed = true })
-      await Promise.resolve()
-      expect(disposed).toBe(false)
-      expect(backend.lifecycle).toEqual(['append-started'])
-
-      appendGate.resolve(true)
-      await teardown
-      expect(backend.store.get(SessionId('inflight-retirement'))?.events.map(event => event.seq)).toEqual([0, 1])
-      expect(backend.lifecycle).toEqual(['append-started', 'append-committed', 'close'])
-    } finally {
-      appendGate.resolve(true)
-      await backendFiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('backend teardown waits for a detached public append before close', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
-    }, { inject: ['sessions'] }))
-    const appendGate = Promise.withResolvers<boolean>()
-    backend.beforeAppend = async () => {
-      backend.lifecycle.push('append-started')
-      await appendGate.promise
-      backend.lifecycle.push('append-committed')
-    }
-
-    try {
-      const id = SessionId('inflight-public-append')
-      await coordinator.create(meta(id))
-      const append = coordinator.append(id, [{
-        type: 'turn/start',
-        seq: SessionSeq(0),
-        time: 1,
-        data: { turn: 1 },
-      }])
-      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
-
-      let disposed = false
-      const teardown = fiber.dispose().then(() => { disposed = true })
-      await Promise.resolve()
-      expect(disposed).toBe(false)
-
-      appendGate.resolve(true)
-      await Promise.all([append, teardown])
-      expect(backend.lifecycle).toEqual(['append-started', 'append-committed', 'close'])
-    } finally {
-      appendGate.resolve(true)
-      await fiber.dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-})
-
-describe('SessionPersistence service registration', () => {
-  it('materializes an explicitly durable live session without adding events', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(MemoryPersistence)
-    const session = ctx.sessions.create(SessionId('durable-empty'), { meta: { cwd: '/workspace' } })
-
-    await ctx.sessionPersistence.ensureMaterialized(session)
-    await ctx.sessionPersistence.ensureMaterialized(session)
-
-    await expect(ctx.sessionPersistence.list()).resolves.toEqual([session.header])
-    await expect(ctx.sessionPersistence.load(session.id)).resolves.toEqual({
-      meta: session.header,
-      inheritedEventCount: SessionLogOffset(0),
-      events: [],
-    })
-    await ctx.fiber.dispose()
-  })
-
-  it('fails loud when a direct backend does not support empty materialization', async () => {
-    const session = Session.create(SessionId('unsupported-empty'))
-    await expect(SessionPersistence.prototype.ensureMaterialized.call({} as SessionPersistence, session))
-      .rejects.toThrow(/cannot materialize an empty session/)
-  })
-
-  it('fails loud when a coordinator backend omits empty materialization', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    let coordinator!: PersistenceCoordinator
-    await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, new ControlledBackend())
-    }, { inject: ['sessions'] }))
-    const session = ctx.sessions.create(SessionId('unsupported-coordinator'))
-
-    await expect(coordinator.ensureMaterialized(session)).rejects.toThrow(/cannot materialize an empty session/)
-    await ctx.fiber.dispose()
-  })
-
-  it('accepts current aborted and error turn endings without legacy conversion', async () => {
-    const store: MemoryStore = new Map()
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const endings: SessionEvent[] = [
-      {
-        type: 'turn/end', seq: SessionSeq(5), time: 6,
-        data: { turn: 1, reason: { kind: 'aborted', reason: { kind: 'user' } } },
-      },
-      {
-        type: 'turn/end', seq: SessionSeq(5), time: 6,
-        data: { turn: 1, reason: { kind: 'error', error: { message: 'failed', code: 'UNKNOWN' } } },
-      },
-    ]
-    for (const [index, ending] of endings.entries()) {
-      const m = meta(`current-ending-${index}`)
-      store.set(m.id, { meta: m, events: [...oneTurnLog().slice(0, -1), ending] })
-    }
-    await ctx.plugin(MemoryPersistence, { store })
-    await Promise.all([...store.keys()].map(id => ctx.sessionPersistence.load(SessionId(id))))
-    await ctx.fiber.dispose()
-  })
-
-  it('rejects preparing an id that already has a live Session', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(MemoryPersistence)
-    const session = ctx.sessions.create(SessionId('live-prepare-conflict'))
-
-    await expect(ctx.sessionPersistence.prepare(session.id)).rejects.toThrow(/while it is live/)
-    await ctx.fiber.dispose()
-  })
-
-  it('provides a cancellation-aware default preparation for simple backends', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence)
-    const m = meta('default-preparation')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    const defaultPrepare = SessionPersistence.prototype.prepare.bind(ctx.sessionPersistence)
-
-    const preparation = await defaultPrepare(m.id)
-    expect(preparation.session.header).toEqual(m)
-    preparation[Symbol.dispose]()
-
-    const preAborted = new AbortController()
-    const preAbortReason = new Error('pre-aborted preparation')
-    preAborted.abort(preAbortReason)
-    await expect(defaultPrepare(m.id, preAborted.signal))
-      .rejects.toBe(preAbortReason)
-
-    const postAborted = new AbortController()
-    const postAbortReason = new Error('post-load preparation abort')
-    const originalLoad = ctx.sessionPersistence.load.bind(ctx.sessionPersistence)
-    ctx.sessionPersistence.load = async (id) => {
-      const loaded = await originalLoad(id)
-      postAborted.abort(postAbortReason)
-      return loaded
-    }
-    await expect(defaultPrepare(m.id, postAborted.signal))
-      .rejects.toBe(postAbortReason)
-
-    await fiber.dispose()
-  })
-
-  it('requires SessionStore for the default preparation', async () => {
-    const id = SessionId('default-preparation-without-store')
-    const persistence = {
-      ctx: new Context(),
-      load: () => Promise.resolve({ meta: meta(id), events: oneTurnLog() }),
-    } as unknown as SessionPersistence
-
-    await expect(SessionPersistence.prototype.prepare.call(persistence, id))
-      .rejects.toThrow(/SessionStore is not configured/)
-  })
-
-  it('registers as ctx.sessionPersistence and is removed on fiber dispose (HMR safety)', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence)
-    expect(ctx.sessionPersistence).toBeInstanceOf(SessionPersistence)
-
-    await fiber.dispose()
-    expect(ctx.sessionPersistence).toBeUndefined()
-  })
-
-  it('round-trips through the registered service instance', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence)
-    const m = meta('reg')
-    await ctx.sessionPersistence.create(m)
-    await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    const loaded = await ctx.sessionPersistence.load(m.id)
-    expect(loaded.events).toHaveLength(6)
-    await fiber.dispose()
-  })
-
-  it('rejects non-JSON session metadata before registering lazy state', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence)
-    const invalid = { ...meta('invalid-meta'), createdAt: 1n as unknown as number }
-
-    await expect(ctx.sessionPersistence.create(invalid))
-      .rejects.toThrow('session metadata must be losslessly JSON-serializable')
-    await fiber.dispose()
-  })
-
-  it('rejects a legacy header delta from a pre-change live producer', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence)
-    const session = ctx.sessions.create(SessionId('legacy-live'), { meta: { cwd: '/legacy' } })
-    // Model the runtime shape available to JavaScript or a hot-loaded plugin
-    // compiled against the obsolete event vocabulary.
-    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
-    expect(() => appendLegacy('request/header-delta', { config: { model: 'legacy' } }))
-      .toThrow(/unsupported legacy request\/header-delta format/)
-    expect(session.snapshotEvents()).toHaveLength(0)
-    await fiber.dispose()
-  })
-
-  it('rejects a legacy fallback header buffered by a pre-change live producer', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence)
-    const session = ctx.sessions.create(SessionId('legacy-fallback-live'), { meta: { cwd: '/legacy' } })
-    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
-
-    expect(() => appendLegacy('request/header', legacyFallbackHeader().data))
-      .toThrow('unsupported legacy request/header reason "fallback"')
-    expect(session.snapshotEvents()).toHaveLength(0)
-    await fiber.dispose()
-  })
-
-  it('rejects a legacy stored prefix during live HMR adoption', async () => {
-    const id = SessionId('legacy-hmr')
-    const m = meta(id, '/legacy')
-    const legacy = legacyHeaderDelta()
-    const store: MemoryStore = new Map([[id, { meta: m, events: [legacy] }]])
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    // A current live session cannot carry the obsolete event in its seed, but
-    // HMR still has to identify the persisted prefix as unsupported rather than
-    // treating it as an ordinary live-prefix collision.
-    const session = ctx.sessions.create(id, { meta: { cwd: '/legacy' } })
-    const fiber = await ctx.plugin(MemoryPersistence, { store })
-
-    await expect(ctx.sessions.flush(session))
-      .rejects.toThrow(/unsupported legacy request\/header-delta event at seq 0/)
-    await Promise.allSettled([fiber.dispose()])
-  })
-
-  it('rejects a stored legacy fallback header during load', async () => {
-    const id = SessionId('legacy-fallback-load')
-    const m = meta(id, '/legacy')
-    const store: MemoryStore = new Map([[id, { meta: m, events: [legacyFallbackHeader()] }]])
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence, { store })
-
-    await expect(ctx.sessionPersistence.load(id))
-      .rejects.toThrow('unsupported legacy request/header reason "fallback" at seq 0')
-    await fiber.dispose()
-  })
-
-  it('rejects a stored legacy named-mode event during load', async () => {
-    const id = SessionId('legacy-mode-load')
-    const m = meta(id, '/legacy')
-    const store: MemoryStore = new Map([[id, { meta: m, events: [legacyModeSet()] }]])
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence, { store })
-
-    await expect(ctx.sessionPersistence.load(id))
-      .rejects.toThrow('unsupported legacy mode/set event at seq 0')
-    await fiber.dispose()
-  })
-
-  it('retires all coordinator bookkeeping for disposed sessions', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(MemoryPersistence)
-    const { coordinator } = ctx.sessionPersistence as unknown as { coordinator: CoordinatorInternals }
-
-    try {
-      for (let index = 0; index < 3; index += 1) {
-        let session!: Session
-        const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
-          session = inner.sessions.create(SessionId(`disposed-${index}`))
-        }, { inject: ['sessions'] }))
-        session.append('turn/start', { turn: 1 })
-        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-        await ctx.sessions.flush(session)
-        await sessionFiber.dispose()
-      }
-
-      await vi.waitFor(() => {
-        expect(ctx.sessions.list()).toHaveLength(0)
-        expect({
-          states: coordinator.states.size,
-          live: coordinator.live.size,
-          chains: coordinator.chains.size,
-        }).toEqual({ states: 0, live: 0, chains: 0 })
-      })
-    } finally {
-      await fiber.dispose()
-    }
-  })
-})
diff --git a/packages/session/session-persistence/tests/preparations.spec.ts b/packages/session/session-persistence/tests/preparations.spec.ts
deleted file mode 100644
index 7635ffd223..0000000000
--- a/packages/session/session-persistence/tests/preparations.spec.ts
+++ /dev/null
@@ -1,432 +0,0 @@
-/** Unit coverage for unpublished Session preparation ownership and sharing. */
-
-import { describe, expect, it, vi } from 'vitest'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import { observeQueuedAbort, SessionPreparations } from '../src/preparations.ts'
-
-interface PreparedSource {
-  readonly session: Session
-  readonly label: string
-}
-
-function prepared(label: string): PreparedSource {
-  return { session: Session.create(SessionId(label)), label }
-}
-
-function committed(source: PreparedSource): Promise<{ source: PreparedSource; state: string }> {
-  return Promise.resolve({ source, state: source.label })
-}
-
-describe('SessionPreparations inspection', () => {
-  it('shares in-flight and ready sources, then invalidates them', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(2)
-    const id = SessionId('shared-inspection')
-    const gate = Promise.withResolvers<PreparedSource>()
-    const load = vi.fn(() => gate.promise)
-    const first = preparations.inspect(id, load)
-    const second = preparations.inspect(id, load, new AbortController().signal)
-    const source = prepared(id)
-
-    expect(preparations.has(id)).toBe(true)
-    gate.resolve(source)
-    await expect(first).resolves.toBe(source)
-    await expect(second).resolves.toBe(source)
-    await expect(preparations.inspect(id, load)).resolves.toBe(source)
-    expect(load).toHaveBeenCalledOnce()
-
-    preparations.invalidate(id)
-    preparations.invalidate(id)
-    expect(preparations.has(id)).toBe(false)
-  })
-
-  it('keeps a shared load alive when its first observer cancels', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('cancelled-first-observer')
-    const gate = Promise.withResolvers<PreparedSource>()
-    const load = vi.fn(() => gate.promise)
-    const controller = new AbortController()
-    const reason = new Error('first observer cancelled')
-    const first = preparations.inspect(id, load, controller.signal)
-    const joined = preparations.inspect(id, load)
-
-    controller.abort(reason)
-    await expect(first).rejects.toBe(reason)
-    const source = prepared(id)
-    gate.resolve(source)
-    await expect(joined).resolves.toBe(source)
-    await expect(preparations.inspect(id, load)).resolves.toBe(source)
-    expect(load).toHaveBeenCalledOnce()
-  })
-
-  it('evicts completed loads whose observers cancelled before readiness', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const firstId = SessionId('cancelled-ready-first')
-    const secondId = SessionId('cancelled-ready-second')
-    const firstGate = Promise.withResolvers<PreparedSource>()
-    const secondGate = Promise.withResolvers<PreparedSource>()
-    const firstController = new AbortController()
-    const secondController = new AbortController()
-    const first = preparations.inspect(firstId, () => firstGate.promise, firstController.signal)
-    const second = preparations.inspect(secondId, () => secondGate.promise, secondController.signal)
-
-    firstController.abort(new Error('first observer cancelled'))
-    secondController.abort(new Error('second observer cancelled'))
-    await expect(first).rejects.toThrow('first observer cancelled')
-    await expect(second).rejects.toThrow('second observer cancelled')
-
-    firstGate.resolve(prepared(firstId))
-    await firstGate.promise
-    secondGate.resolve(prepared(secondId))
-    await secondGate.promise
-    await Promise.resolve()
-
-    expect(preparations.has(firstId)).toBe(false)
-    expect(preparations.has(secondId)).toBe(true)
-  })
-
-  it('removes failed and invalidated in-flight loads without changing their observers', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const failedId = SessionId('failed-inspection')
-    const failure = new Error('load failed')
-    await expect(preparations.inspect(failedId, () => Promise.reject(failure))).rejects.toBe(failure)
-    expect(preparations.has(failedId)).toBe(false)
-
-    const invalidatedId = SessionId('invalidated-inspection')
-    const gate = Promise.withResolvers<PreparedSource>()
-    const inspection = preparations.inspect(invalidatedId, () => gate.promise)
-    preparations.invalidate(invalidatedId)
-    const source = prepared(invalidatedId)
-    gate.resolve(source)
-    await expect(inspection).resolves.toBe(source)
-    expect(preparations.has(invalidatedId)).toBe(false)
-
-    const rejectedId = SessionId('invalidated-rejection')
-    const rejectedGate = Promise.withResolvers<PreparedSource>()
-    const rejected = preparations.inspect(rejectedId, () => rejectedGate.promise)
-    preparations.invalidate(rejectedId)
-    rejectedGate.reject(failure)
-    await expect(rejected).rejects.toBe(failure)
-  })
-
-  it('removes a load that throws before returning its promise', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('synchronous-load-failure')
-    const failure = new Error('synchronous load failure')
-
-    await expect(preparations.inspect(id, () => { throw failure })).rejects.toBe(failure)
-    expect(preparations.has(id)).toBe(false)
-  })
-
-  it('evicts ready entries while leaving reserved entries alone', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const reservedA = await preparations.reserve(
-      SessionId('reserved-a'),
-      () => Promise.resolve(prepared('reserved-a')),
-      committed,
-    )
-    const reservedB = await preparations.reserve(
-      SessionId('reserved-b'),
-      () => Promise.resolve(prepared('reserved-b')),
-      committed,
-    )
-    expect(reservedA).toBeDefined()
-    expect(reservedB).toBeDefined()
-
-    await preparations.inspect(SessionId('ready-c'), () => Promise.resolve(prepared('ready-c')))
-    preparations.release(reservedA!, true)
-    expect(preparations.has(SessionId('reserved-b'))).toBe(true)
-    expect(preparations.has(SessionId('ready-c'))).toBe(false)
-    expect(preparations.has(SessionId('reserved-a'))).toBe(true)
-
-    preparations.discard(reservedB!)
-    preparations.invalidate(SessionId('reserved-a'))
-  })
-
-  it('discards only the exact ready source and retains exclusive reservations', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const ready = prepared('discard-ready')
-    expect(preparations.discardReady(ready.session.id, ready)).toBe('missing')
-    await preparations.inspect(ready.session.id, () => Promise.resolve(ready))
-    expect(preparations.discardReady(ready.session.id, prepared('different'))).toBe('missing')
-    expect(preparations.discardReady(ready.session.id, ready)).toBe('discarded')
-
-    const reserved = await preparations.reserve(
-      ready.session.id,
-      () => Promise.resolve(ready),
-      committed,
-    )
-    expect(preparations.discardReady(ready.session.id, ready)).toBe('retained')
-    preparations.release(reserved!, false)
-  })
-})
-
-describe('SessionPreparations borrowing', () => {
-  it('returns a detached lease when loading invalidates its own entry', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('borrow-invalidated-load')
-    const source = prepared(id)
-
-    const lease = await preparations.borrow(id, () => {
-      preparations.invalidate(id)
-      return Promise.resolve(source)
-    })
-
-    expect(lease.source).toBe(source)
-    expect(preparations.has(id)).toBe(false)
-    expect(() => { lease[Symbol.dispose]() }).not.toThrow()
-  })
-
-  it('releases pins after cancellation while loading and after readiness', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const loadingId = SessionId('borrow-cancelled-loading')
-    const loading = Promise.withResolvers<PreparedSource>()
-    const loadingAbort = new AbortController()
-    const pending = preparations.borrow(loadingId, () => loading.promise, loadingAbort.signal)
-    loadingAbort.abort(new Error('cancelled while loading'))
-    await expect(pending).rejects.toThrow('cancelled while loading')
-    loading.resolve(prepared(loadingId))
-    await loading.promise
-    await Promise.resolve()
-
-    const readyId = SessionId('borrow-cancelled-ready')
-    const ready = prepared(readyId)
-    await preparations.inspect(readyId, () => Promise.resolve(ready))
-    const readyAbort = new AbortController()
-    readyAbort.abort(new Error('cancelled while ready'))
-    await expect(preparations.borrow(readyId, () => Promise.resolve(ready), readyAbort.signal))
-      .rejects.toThrow('cancelled while ready')
-
-    await preparations.inspect(SessionId('borrow-eviction'), () => Promise.resolve(prepared('borrow-eviction')))
-    expect(preparations.has(loadingId)).toBe(false)
-  })
-
-  it('makes borrowed lease disposal idempotent across ready, invalidated, and reserved entries', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(3)
-
-    const ready = prepared('borrow-ready-release')
-    const readyLease = await preparations.borrow(ready.session.id, () => Promise.resolve(ready))
-    readyLease[Symbol.dispose]()
-    readyLease[Symbol.dispose]()
-
-    const invalidated = prepared('borrow-invalidated-release')
-    const invalidatedLease = await preparations.borrow(
-      invalidated.session.id,
-      () => Promise.resolve(invalidated),
-    )
-    preparations.invalidate(invalidated.session.id)
-    invalidatedLease[Symbol.dispose]()
-
-    const reserved = prepared('borrow-reserved-release')
-    const reservation = await preparations.reserve(
-      reserved.session.id,
-      () => Promise.resolve(reserved),
-      committed,
-    )
-    expect(reservation).toBeDefined()
-    const reservedLease = await preparations.borrow(
-      reserved.session.id,
-      () => Promise.resolve(prepared('unused')),
-    )
-    reservedLease[Symbol.dispose]()
-    preparations.release(reservation!, false)
-  })
-})
-
-describe('SessionPreparations reservation', () => {
-  it('waits for an existing reservation, republishes the exact Session, and attaches once', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(2)
-    const id = SessionId('reservation-wait')
-    const source = prepared(id)
-    const first = await preparations.reserve(id, () => Promise.resolve(source), committed)
-    expect(first).toBeDefined()
-    expect(preparations.reservationFor(source.session)).toBe(first)
-    expect(() => preparations.reservationFor(Session.create(id))).toThrow(/cannot publish/)
-    expect(() => { preparations.assertWritable(id) }).toThrow(/is reserved/)
-
-    let secondSettled = false
-    const secondPromise = preparations.reserve(id, () => Promise.resolve(prepared('unused')), committed)
-      .then((reservation) => {
-        secondSettled = true
-        return reservation
-      })
-    await Promise.resolve()
-    await Promise.resolve()
-    await Promise.resolve()
-    expect(secondSettled).toBe(false)
-
-    preparations.release(first!, true)
-    const second = await secondPromise
-    expect(second?.source).toBe(source)
-    preparations.attach(second!)
-    expect(preparations.reservationFor(source.session)).toBeUndefined()
-    expect(() => { preparations.attach(second!) }).toThrow(/no longer reserved/)
-    preparations.discard(second!)
-    preparations.release(second!, true)
-    expect(() => { preparations.assertWritable(id) }).not.toThrow()
-  })
-
-  it('supports abortable reservation waits without cancelling the held reservation', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('abortable-reservation-wait')
-    const first = await preparations.reserve(id, () => Promise.resolve(prepared(id)), committed)
-    const controller = new AbortController()
-    const reason = { kind: 'cancelled' }
-    const waiting = preparations.reserve(id, () => Promise.resolve(prepared('unused')), committed, controller.signal)
-
-    await Promise.resolve()
-    await Promise.resolve()
-    await Promise.resolve()
-    controller.abort(reason)
-    await expect(waiting).rejects.toBe(reason)
-    expect(preparations.reservationFor(first!.source.session)).toBe(first)
-    preparations.release(first!, false)
-    expect(preparations.has(id)).toBe(false)
-  })
-
-  it('removes a failed commit and wakes another waiter as invalidated', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('failed-commit')
-    const commitStarted = Promise.withResolvers<undefined>()
-    const commitGate = Promise.withResolvers<{ source: PreparedSource; state: string }>()
-    const source = prepared(id)
-    const failure = new Error('commit failed')
-    const first = preparations.reserve(id, () => Promise.resolve(source), () => {
-      commitStarted.resolve(undefined)
-      return commitGate.promise
-    })
-    await commitStarted.promise
-    expect(() => { preparations.assertWritable(id) }).toThrow(/is reserved/)
-    const second = preparations.reserve(id, () => Promise.resolve(prepared('unused')), committed)
-
-    commitGate.reject(failure)
-    await expect(first).rejects.toBe(failure)
-    await expect(second).resolves.toBeUndefined()
-    expect(preparations.has(id)).toBe(false)
-  })
-
-  it('returns a post-commit cancellation to the ready pool', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('post-commit-cancel')
-    const source = prepared(id)
-    const controller = new AbortController()
-    const reason = new Error('cancel after commit')
-
-    await expect(preparations.reserve(id, () => Promise.resolve(source), async (value) => {
-      controller.abort(reason)
-      return { source: value, state: value.label }
-    }, controller.signal)).rejects.toBe(reason)
-
-    expect(preparations.takeReady(id)).toBe(source)
-    expect(preparations.takeReady(id)).toBeUndefined()
-  })
-
-  it('does not revive an invalidated commit after post-commit cancellation', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('invalidated-commit-cancel')
-    const source = prepared(id)
-    const commitStarted = Promise.withResolvers<undefined>()
-    const commitGate = Promise.withResolvers<undefined>()
-    const controller = new AbortController()
-    const reason = new Error('cancel invalidated commit')
-    const reservation = preparations.reserve(id, () => Promise.resolve(source), async (value) => {
-      commitStarted.resolve(undefined)
-      await commitGate.promise
-      return { source: value, state: value.label }
-    }, controller.signal)
-
-    await commitStarted.promise
-    preparations.invalidate(id)
-    controller.abort(reason)
-    commitGate.resolve(undefined)
-    await expect(reservation).rejects.toBe(reason)
-    expect(preparations.has(id)).toBe(false)
-  })
-
-  it('does not reserve an entry invalidated while its commit succeeds', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('invalidated-successful-commit')
-    const source = prepared(id)
-    const commitStarted = Promise.withResolvers<undefined>()
-    const commitGate = Promise.withResolvers<undefined>()
-    const reservation = preparations.reserve(id, () => Promise.resolve(source), async (value) => {
-      commitStarted.resolve(undefined)
-      await commitGate.promise
-      return { source: value, state: value.label }
-    })
-
-    await commitStarted.promise
-    preparations.invalidate(id)
-    commitGate.resolve(undefined)
-
-    await expect(reservation).resolves.toBeUndefined()
-    expect(preparations.has(id)).toBe(false)
-  })
-
-  it('returns undefined when a load is invalidated before reservation', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('invalidated-reservation')
-    const gate = Promise.withResolvers<PreparedSource>()
-    const reservation = preparations.reserve(id, () => gate.promise, committed)
-    preparations.invalidate(id)
-    gate.resolve(prepared(id))
-    await expect(reservation).resolves.toBeUndefined()
-  })
-
-  it('skips pending adoption and accepts a ready source exactly once', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const id = SessionId('take-ready')
-    const gate = Promise.withResolvers<PreparedSource>()
-    const inspection = preparations.inspect(id, () => gate.promise)
-    expect(preparations.takeReady(id)).toBeUndefined()
-    const source = prepared(id)
-    gate.resolve(source)
-    await inspection
-    expect(preparations.takeReady(id)).toBe(source)
-    expect(preparations.takeReady(id)).toBeUndefined()
-  })
-
-  it('rejects publication while only an inspection exists', async () => {
-    const preparations = new SessionPreparations<PreparedSource, string>(1)
-    const source = prepared('inspection-publication')
-    await preparations.inspect(source.session.id, () => Promise.resolve(source))
-    expect(() => preparations.reservationFor(source.session)).toThrow(/cannot publish/)
-  })
-})
-
-describe('observeQueuedAbort', () => {
-  it('relays fulfillment and rejection exactly', async () => {
-    const signal = new AbortController().signal
-    await expect(observeQueuedAbort(Promise.resolve('value'), signal)).resolves.toBe('value')
-    const failure = { kind: 'failed' }
-    const rejected = Promise.withResolvers<never>()
-    rejected.reject(failure)
-    await expect(observeQueuedAbort(rejected.promise, signal)).rejects.toBe(failure)
-  })
-
-  it('rejects promptly with an exact abort reason and ignores later settlement', async () => {
-    const operation = Promise.withResolvers<string>()
-    const controller = new AbortController()
-    const reason = { kind: 'aborted' }
-    const observed = observeQueuedAbort(operation.promise, controller.signal)
-    controller.abort(reason)
-    await expect(observed).rejects.toBe(reason)
-    operation.resolve('late')
-    await Promise.resolve()
-  })
-
-  it('observes a pre-aborted signal through the default start predicate', async () => {
-    const controller = new AbortController()
-    controller.abort('pre-aborted')
-    await expect(observeQueuedAbort(new Promise<never>(() => {}), controller.signal))
-      .rejects.toBe('pre-aborted')
-  })
-
-  it('lets an operation that already started own cancellation settlement', async () => {
-    const operation = Promise.withResolvers<string>()
-    const controller = new AbortController()
-    const observed = observeQueuedAbort(operation.promise, controller.signal, () => true)
-    controller.abort(new Error('too late'))
-    operation.resolve('owned')
-    await expect(observed).resolves.toBe('owned')
-  })
-})
diff --git a/packages/session/session-persistence/tests/storage-contract.spec.ts b/packages/session/session-persistence/tests/storage-contract.spec.ts
new file mode 100644
index 0000000000..8a7d224b6c
--- /dev/null
+++ b/packages/session/session-persistence/tests/storage-contract.spec.ts
@@ -0,0 +1,321 @@
+/**
+ * Unit tests for the backend-shared storage validation helpers and the
+ * stable error vocabulary.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import {
+  SessionAlreadyExistsError,
+  SessionAlreadyOwnedError,
+  SessionFormatUnsupportedError,
+  SessionHandleClosedError,
+  SessionOwnershipLostError,
+  SessionPersistenceCorruptionError,
+  SessionPersistenceNotFoundError,
+  SessionPersistenceRevision,
+  SessionReadOnlyError,
+  assertContiguous,
+  assertStoredId,
+  assertVersion,
+  materializeAppendBatch,
+  sessionFormatVersionRefusal,
+  validateStoredEvents,
+} from '../src/index.ts'
+import type { SessionLocation } from '../src/index.ts'
+import { meta } from './contract.ts'
+
+const LOCATION: SessionLocation = { kind: 'jsonl', path: '/store/session.jsonl' }
+
+/** A stored user/message event with a well-formed identified message. */
+function userMessage(seq: number): SessionEvent {
+  return {
+    type: 'user/message',
+    seq,
+    time: seq + 1,
+    data: {
+      id: 'stored-user',
+      role: 'user',
+      content: [{ type: 'text', text: 'hi' }],
+      source: { kind: 'user' },
+    },
+    surfaceOp: 'append',
+  } as unknown as SessionEvent
+}
+
+describe('assertStoredId', () => {
+  it('accepts a bound header and names both ids on a mismatch', () => {
+    const m = meta('bound')
+    expect(() => { assertStoredId(m.id, m) }).not.toThrow()
+    expect(() => { assertStoredId(SessionId('requested'), m) })
+      .toThrow('stored session identity mismatch: requested "requested", header contains "bound"')
+  })
+})
+
+describe('assertVersion', () => {
+  it('accepts the current format version', () => {
+    expect(() => { assertVersion(meta('current')) }).not.toThrow()
+  })
+
+  it('refuses a newer version with the upgrade direction and the artifact location', () => {
+    const newer = { ...meta('newer'), version: SESSION_FORMAT_VERSION + 42 }
+    let refusal: unknown
+    try {
+      assertVersion(newer, LOCATION)
+    } catch (error) {
+      refusal = error
+    }
+    expect(refusal).toBeInstanceOf(SessionFormatUnsupportedError)
+    expect((refusal as Error).message).toContain('written by a newer harness — upgrade the harness to open it')
+    expect((refusal as Error).message).toContain(`(raw log: ${LOCATION.path})`)
+    expect((refusal as SessionFormatUnsupportedError).location).toBe(LOCATION)
+  })
+
+  it('refuses an older version without a location suffix when the backend has no artifact', () => {
+    const older = { ...meta('older'), version: SESSION_FORMAT_VERSION - 1 }
+    let refusal: unknown
+    try {
+      assertVersion(older)
+    } catch (error) {
+      refusal = error
+    }
+    expect(refusal).toBeInstanceOf(SessionFormatUnsupportedError)
+    expect((refusal as Error).message).toBe(sessionFormatVersionRefusal('older', SESSION_FORMAT_VERSION - 1))
+    expect((refusal as Error).message).toContain('this build ships no upgrade path for it')
+    expect((refusal as Error).message).not.toContain('raw log')
+    expect((refusal as SessionFormatUnsupportedError).location).toBeUndefined()
+  })
+})
+
+describe('sessionFormatVersionRefusal', () => {
+  it('states the direction for newer and older stored versions', () => {
+    expect(sessionFormatVersionRefusal('s', SESSION_FORMAT_VERSION + 1))
+      .toBe(`session "s" uses log format v${SESSION_FORMAT_VERSION + 1}, but this harness reads only v${SESSION_FORMAT_VERSION}: the log was written by a newer harness — upgrade the harness to open it`)
+    expect(sessionFormatVersionRefusal('s', SESSION_FORMAT_VERSION - 1))
+      .toBe(`session "s" uses log format v${SESSION_FORMAT_VERSION - 1}, older than the supported v${SESSION_FORMAT_VERSION}, and this build ships no upgrade path for it`)
+  })
+})
+
+describe('validateStoredEvents', () => {
+  it('adopts and freezes the events in place, returning the same array', () => {
+    const m = meta('adopted')
+    const events = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
+      userMessage(1),
+    ] as SessionEvent[]
+    const validated = validateStoredEvents(m, events)
+    expect(validated).toBe(events)
+    expect(Object.isFrozen(validated[1]!.data)).toBe(true)
+  })
+
+  it('adopts a merge-extended turn/end reason outside the closed built-in set', () => {
+    const m = meta('extended-reason')
+    const events = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
+      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'plugin/custom-outcome' } } },
+    ] as SessionEvent[]
+    expect(validateStoredEvents(m, events)).toBe(events)
+  })
+
+  it('refuses an unknown event type before adopting anything', () => {
+    const m = meta('unknown-type')
+    const events = [
+      { type: 'mystery/event', seq: 0, time: 1, data: {} },
+    ] as unknown as SessionEvent[]
+    expect(() => validateStoredEvents(m, events)).toThrow(SessionFormatUnsupportedError)
+    expect(() => validateStoredEvents(m, events)).toThrow(
+      'session "unknown-type" contains event type "mystery/event" (seq 0) unknown to this harness',
+    )
+    // With an artifact, the refusal points at the raw log.
+    let refusal: unknown
+    try {
+      validateStoredEvents(m, events, LOCATION)
+    } catch (error) {
+      refusal = error
+    }
+    expect((refusal as Error).message).toContain(`(raw log: ${LOCATION.path})`)
+    expect((refusal as SessionFormatUnsupportedError).location).toBe(LOCATION)
+  })
+
+  it('retains an unknown event type its writer marked ignorable', () => {
+    const m = meta('ignorable-unknown')
+    const events = [
+      { type: 'foreign/telemetry', seq: 0, time: 1, data: {}, ignorable: true },
+    ] as unknown as SessionEvent[]
+    expect(validateStoredEvents(m, events)).toBe(events)
+    expect(events[0]).toMatchObject({ type: 'foreign/telemetry', ignorable: true })
+  })
+
+  it('refuses the retired request/header "fallback" reason while accepting current headers', () => {
+    const m = meta('retired-reason')
+    const retired = [
+      {
+        type: 'request/header',
+        seq: 0,
+        time: 1,
+        data: { header: { config: { provider: 'mock', model: 'legacy' } }, reason: 'fallback' },
+      },
+    ] as unknown as SessionEvent[]
+    expect(() => validateStoredEvents(m, retired)).toThrow(SessionFormatUnsupportedError)
+    expect(() => validateStoredEvents(m, retired)).toThrow(
+      'session "retired-reason" contains a request/header event (seq 0) with the unsupported legacy reason "fallback"',
+    )
+
+    const current = [
+      {
+        type: 'request/header',
+        seq: 0,
+        time: 1,
+        data: { header: { config: { provider: 'mock', model: 'current' } }, reason: 'initial' },
+      },
+    ] as unknown as SessionEvent[]
+    expect(validateStoredEvents(m, current)).toBe(current)
+  })
+
+  it('wraps a record validation failure as corruption with its cause', () => {
+    const m = meta('damaged')
+    const events = [
+      {
+        type: 'user/message',
+        seq: 0,
+        time: 1,
+        // No identified message: adoption refuses the record.
+        data: { role: 'user', content: [], source: { kind: 'user' } },
+      },
+    ] as unknown as SessionEvent[]
+    let failure: unknown
+    try {
+      validateStoredEvents(m, events)
+    } catch (error) {
+      failure = error
+    }
+    expect(failure).toBeInstanceOf(SessionPersistenceCorruptionError)
+    expect((failure as Error).message).toContain('stored session "damaged" failed validation')
+    expect((failure as Error).message).toContain('lacks an identified message')
+    expect((failure as Error).cause).toBeInstanceOf(Error)
+  })
+
+  it('passes an adoption-side format refusal through unwrapped', () => {
+    // The adoption step may itself refuse a record as unsupported rather than
+    // damaged; such a refusal must reach the caller as-is, never rebranded as
+    // corruption.
+    const m = meta('adoption-refusal')
+    const passthrough = new SessionFormatUnsupportedError('refused during adoption')
+    const trap = {
+      type: 'user/message',
+      seq: 0,
+      time: 1,
+      get data(): never {
+        throw passthrough
+      },
+    } as unknown as SessionEvent
+    expect(() => validateStoredEvents(m, [trap])).toThrow(passthrough)
+  })
+})
+
+describe('materializeAppendBatch', () => {
+  it('returns a detached lossless-JSON snapshot of the batch', () => {
+    const original = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
+    ] as SessionEvent[]
+    const batch = materializeAppendBatch(original)
+    expect(batch).not.toBe(original)
+    expect(batch).toEqual(original)
+    // The snapshot is detached: mutating the caller's batch afterwards cannot
+    // change what a backend persists.
+    ;(original[0]!.data as { turn: number }).turn = 99
+    expect((batch[0]!.data as { turn: number }).turn).toBe(1)
+  })
+
+  it('rejects every non-JSON value, not only BigInt', () => {
+    // Every value `snapshotJsonValue` refuses must be refused here — a backend
+    // passing this helper cannot accept values that corrupt the durable
+    // round-trip.
+    const cyclic: Record<string, unknown> = { type: 'text', text: 'x' }
+    cyclic['self'] = cyclic
+    const badValues: unknown[] = [
+      1n,                  // BigInt
+      undefined,           // dropped by JSON.stringify
+      Infinity,            // → null
+      () => 0,             // function
+      Symbol('s'),         // symbol
+      new Map(),           // exotic object
+      cyclic,              // circular ref
+    ]
+    for (const bad of badValues) {
+      const events = [
+        { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, extra: bad } },
+      ] as unknown as SessionEvent[]
+      expect(() => materializeAppendBatch(events)).toThrow(TypeError)
+      expect(() => materializeAppendBatch(events)).toThrow(/losslessly JSON-serializable/)
+    }
+  })
+})
+
+describe('assertContiguous', () => {
+  it('accepts a batch continuing exactly at the cursor', () => {
+    const events = [
+      { type: 'turn/start', seq: 6, time: 1, data: { turn: 2 } },
+      { type: 'turn/end', seq: 7, time: 2, data: { turn: 2, reason: { kind: 'completed' } } },
+    ] as SessionEvent[]
+    expect(() => { assertContiguous(SessionId('ok'), events, 6) }).not.toThrow()
+    expect(() => { assertContiguous(SessionId('ok'), [], 6) }).not.toThrow()
+  })
+
+  it('names the expected seq for a stale batch and for a mid-batch gap', () => {
+    const stale = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
+    ] as SessionEvent[]
+    expect(() => { assertContiguous(SessionId('stale'), stale, 6) })
+      .toThrow('append seq mismatch for "stale": expected 6 at index 0, got 0')
+
+    const gapped = [
+      { type: 'turn/start', seq: 6, time: 1, data: { turn: 2 } },
+      { type: 'turn/end', seq: 8, time: 2, data: { turn: 2, reason: { kind: 'completed' } } },
+    ] as SessionEvent[]
+    expect(() => { assertContiguous(SessionId('gapped'), gapped, 6) })
+      .toThrow('append seq mismatch for "gapped": expected 7 at index 1, got 8')
+  })
+})
+
+describe('error vocabulary', () => {
+  it('carries stable names, messages, and the session id', () => {
+    const id = SessionId('errored')
+    const notFound = new SessionPersistenceNotFoundError(id)
+    expect(notFound.name).toBe('SessionPersistenceNotFoundError')
+    expect(notFound.sessionId).toBe(id)
+    expect(notFound.message).toBe('session "errored" not found')
+
+    const exists = new SessionAlreadyExistsError(id)
+    expect(exists.name).toBe('SessionAlreadyExistsError')
+    expect(exists.message).toBe('session "errored" already exists')
+
+    const owned = new SessionAlreadyOwnedError(id)
+    expect(owned.name).toBe('SessionAlreadyOwnedError')
+    expect(owned.message).toBe('session "errored" is already owned by an active write handle')
+
+    const readOnly = new SessionReadOnlyError(id, 'append')
+    expect(readOnly.name).toBe('SessionReadOnlyError')
+    expect(readOnly.message).toBe('session "errored": append is not available on a read handle')
+
+    const lost = new SessionOwnershipLostError(id)
+    expect(lost.name).toBe('SessionOwnershipLostError')
+    expect(lost.message).toBe('session "errored": write ownership was lost; close this handle and reopen')
+
+    const closed = new SessionHandleClosedError(id, 'flush')
+    expect(closed.name).toBe('SessionHandleClosedError')
+    expect(closed.message).toBe('session "errored": flush on a closed handle')
+
+    const cause = new Error('detail')
+    const corruption = new SessionPersistenceCorruptionError('bad log', { cause })
+    expect(corruption.name).toBe('SessionPersistenceCorruptionError')
+    expect(corruption.cause).toBe(cause)
+  })
+})
+
+describe('SessionPersistenceRevision', () => {
+  it('brands the backend token without changing its runtime value', () => {
+    expect(SessionPersistenceRevision('rev:1')).toBe('rev:1')
+  })
+})
diff --git a/packages/session/session-persistence/tests/write-behind.spec.ts b/packages/session/session-persistence/tests/write-behind.spec.ts
deleted file mode 100644
index 8b33dc34d0..0000000000
--- a/packages/session/session-persistence/tests/write-behind.spec.ts
+++ /dev/null
@@ -1,275 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session'
-import { SessionWriteBehind } from '../src/write-behind.ts'
-
-/** Minimal ordered event fixture; batching does not interpret event vocabulary. */
-function event(seq: SessionSeq): SessionEvent<'turn/start'> {
-  return {
-    type: 'turn/start',
-    seq,
-    time: seq,
-    data: { turn: seq + 1 },
-  }
-}
-
-afterEach(() => {
-  vi.useRealTimers()
-})
-
-describe('SessionWriteBehind', () => {
-  it('uses one fixed window from the first queued event and owns its copy', async () => {
-    vi.useFakeTimers()
-    const batches: SessionEvent[][] = []
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => { batches.push(structuredClone(events) as SessionEvent[]) },
-      reportBackgroundFailure: vi.fn(),
-    })
-    const first = event(SessionSeq(0))
-
-    controller.enqueue(first)
-    first.data.turn = 99
-    await vi.advanceTimersByTimeAsync(150)
-    controller.enqueue(event(SessionSeq(1)))
-    await vi.advanceTimersByTimeAsync(49)
-    expect(batches).toEqual([])
-
-    await vi.advanceTimersByTimeAsync(1)
-    expect(batches).toEqual([[
-      expect.objectContaining({ seq: 0, data: { turn: 1 } }),
-      expect.objectContaining({ seq: 1 }),
-    ]])
-    expect(controller.hasWork).toBe(false)
-  })
-
-  it('coalesces twenty events admitted ten milliseconds apart into one 200 ms batch', async () => {
-    vi.useFakeTimers()
-    const batches: number[][] = []
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => { batches.push(events.map(item => item.seq)) },
-      reportBackgroundFailure: vi.fn(),
-    })
-
-    controller.enqueue(event(SessionSeq(0)))
-    for (let seq = 1; seq < 20; seq += 1) {
-      await vi.advanceTimersByTimeAsync(10)
-      controller.enqueue(event(SessionSeq(seq)))
-    }
-    expect(batches).toEqual([])
-
-    await vi.advanceTimersByTimeAsync(10)
-    expect(batches).toEqual([Array.from({ length: 20 }, (_, seq) => seq)])
-    await controller.flush()
-  })
-
-  it('makes concurrent flushes one immediate barrier that drains admitted tails', async () => {
-    vi.useFakeTimers()
-    const gate = Promise.withResolvers<boolean>()
-    const batches: number[][] = []
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => {
-        batches.push(events.map(item => item.seq))
-        if (batches.length === 1) await gate.promise
-      },
-      reportBackgroundFailure: vi.fn(),
-    })
-
-    controller.enqueue(event(SessionSeq(0)))
-    const first = controller.flush()
-    const second = controller.flush()
-    expect(second).toBe(first)
-    await Promise.resolve()
-    expect(batches).toEqual([[0]])
-
-    controller.enqueue(event(SessionSeq(1)))
-    gate.resolve(true)
-    await first
-    expect(batches).toEqual([[0], [1]])
-    expect(controller.hasWork).toBe(false)
-    expect(vi.getTimerCount()).toBe(0)
-  })
-
-  it('starts a new window for work admitted after an already-quiescent barrier', async () => {
-    vi.useFakeTimers()
-    const batches: number[][] = []
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => { batches.push(events.map(item => item.seq)) },
-      reportBackgroundFailure: vi.fn(),
-    })
-
-    const barrier = controller.flush()
-    controller.enqueue(event(SessionSeq(0)))
-    await barrier
-    expect(batches).toEqual([])
-    expect(vi.getTimerCount()).toBe(1)
-
-    await vi.advanceTimersByTimeAsync(200)
-    expect(batches).toEqual([[0]])
-    expect(controller.hasWork).toBe(false)
-  })
-
-  it('starts an over-budget tail immediately after the active write', async () => {
-    vi.useFakeTimers()
-    const gate = Promise.withResolvers<boolean>()
-    const batches: number[][] = []
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => {
-        batches.push(events.map(item => item.seq))
-        if (batches.length === 1) await gate.promise
-      },
-      reportBackgroundFailure: vi.fn(),
-    })
-
-    controller.enqueue(event(SessionSeq(0)))
-    await vi.advanceTimersByTimeAsync(200)
-    expect(batches).toEqual([[0]])
-    controller.enqueue(event(SessionSeq(1)))
-    await vi.advanceTimersByTimeAsync(200)
-    expect(batches).toEqual([[0]])
-
-    gate.resolve(true)
-    await vi.advanceTimersByTimeAsync(0)
-    expect(batches).toEqual([[0], [1]])
-    await controller.flush()
-  })
-
-  it('keeps a tail deadline that has not expired when the active write finishes', async () => {
-    vi.useFakeTimers()
-    const gate = Promise.withResolvers<boolean>()
-    const batches: number[][] = []
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => {
-        batches.push(events.map(item => item.seq))
-        if (batches.length === 1) await gate.promise
-      },
-      reportBackgroundFailure: vi.fn(),
-    })
-
-    controller.enqueue(event(SessionSeq(0)))
-    await vi.advanceTimersByTimeAsync(200)
-    controller.enqueue(event(SessionSeq(1)))
-    await vi.advanceTimersByTimeAsync(50)
-    gate.resolve(true)
-    await vi.advanceTimersByTimeAsync(0)
-    expect(batches).toEqual([[0]])
-
-    await vi.advanceTimersByTimeAsync(149)
-    expect(batches).toEqual([[0]])
-    await vi.advanceTimersByTimeAsync(1)
-    expect(batches).toEqual([[0], [1]])
-    await controller.flush()
-  })
-
-  it('pauses automatic retries after failure and preserves order for new work', async () => {
-    vi.useFakeTimers()
-    const failure = new Error('storage unavailable')
-    const report = vi.fn()
-    const batches: number[][] = []
-    let attempt = 0
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => {
-        batches.push(events.map(item => item.seq))
-        if (++attempt === 1) throw failure
-      },
-      reportBackgroundFailure: report,
-    })
-
-    controller.enqueue(event(SessionSeq(0)))
-    await vi.advanceTimersByTimeAsync(200)
-    expect(report).toHaveBeenCalledWith(failure)
-    expect(controller.hasWork).toBe(true)
-    await vi.advanceTimersByTimeAsync(1_000)
-    expect(batches).toEqual([[0]])
-
-    controller.enqueue(event(SessionSeq(1)))
-    await vi.advanceTimersByTimeAsync(199)
-    expect(batches).toEqual([[0]])
-    await vi.advanceTimersByTimeAsync(1)
-    expect(batches).toEqual([[0], [0, 1]])
-    await controller.flush()
-  })
-
-  it('observes an overlapping background failure and retries it inside flush', async () => {
-    vi.useFakeTimers()
-    const gate = Promise.withResolvers<boolean>()
-    const report = vi.fn()
-    const batches: number[][] = []
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => {
-        batches.push(events.map(item => item.seq))
-        if (batches.length === 1) {
-          await gate.promise
-          throw new Error('transient')
-        }
-      },
-      reportBackgroundFailure: report,
-    })
-
-    controller.enqueue(event(SessionSeq(0)))
-    await vi.advanceTimersByTimeAsync(200)
-    const first = controller.flush()
-    const second = controller.flush()
-    gate.resolve(true)
-
-    await expect(Promise.all([first, second])).resolves.toEqual([undefined, undefined])
-    expect(batches).toEqual([[0], [0]])
-    expect(report).toHaveBeenCalledOnce()
-    expect(controller.hasWork).toBe(false)
-  })
-
-  it('surfaces a barrier failure without detached logging and retains its batch', async () => {
-    vi.useFakeTimers()
-    const failure = new Error('durability failed')
-    const report = vi.fn()
-    const batches: number[][] = []
-    let attempt = 0
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => {
-        batches.push(events.map(item => item.seq))
-        if (++attempt === 1) throw failure
-      },
-      reportBackgroundFailure: report,
-    })
-
-    controller.enqueue(event(SessionSeq(0)))
-    await expect(controller.flush()).rejects.toBe(failure)
-    expect(report).not.toHaveBeenCalled()
-    expect(controller.hasWork).toBe(true)
-
-    controller.enqueue(event(SessionSeq(1)))
-    await vi.advanceTimersByTimeAsync(200)
-    expect(batches).toEqual([[0], [0, 1]])
-    await controller.flush()
-  })
-
-  it('retains a failed batch larger than the engine call-argument limit', async () => {
-    const failure = new Error('durability failed')
-    const batchSize = 150_000
-    const sizes: number[] = []
-    let attempt = 0
-    const controller = new SessionWriteBehind({
-      maxDelayMs: 200,
-      write: async (events) => {
-        sizes.push(events.length)
-        if (++attempt === 1) throw failure
-      },
-      reportBackgroundFailure: vi.fn(),
-    })
-
-    for (let seq = 0; seq < batchSize; seq += 1) controller.enqueue(event(SessionSeq(seq)))
-    await expect(controller.flush()).rejects.toBe(failure)
-    expect(controller.hasWork).toBe(true)
-
-    await controller.flush()
-    expect(sizes).toEqual([batchSize, batchSize])
-    expect(controller.hasWork).toBe(false)
-  })
-})
diff --git a/packages/session/session-projection/src/index.ts b/packages/session/session-projection/src/index.ts
index edfa4820b3..d29c5bb021 100644
--- a/packages/session/session-projection/src/index.ts
+++ b/packages/session/session-projection/src/index.ts
@@ -418,9 +418,9 @@ export class SessionProjectionRegistry extends Service {
    * yields an end below every watermark and the restore rejects for a full
    * re-read.
    * @param checkpoint - persisted rows for one session (possibly stale or empty).
-   * @returns the seq to hand the persistence `readFrom`, or `undefined`
-   *   when no unit is registered (no read needed — {@link restore} would
-   *   serve empty values regardless).
+   * @returns the offset for the stored-log suffix read (`SessionHandle.read`),
+   *   or `undefined` when no unit is registered (no read needed —
+   *   {@link restore} would serve empty values regardless).
    */
   restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined {
     let floor: number | undefined
@@ -472,8 +472,8 @@ export class SessionProjectionRegistry extends Service {
    * Cold read: fold every persisted unit over a stored log suffix, seeding
    * each from its checkpoint row when usable — the one read recipe (cached
    * state + forward tail replay + `view`) applied without a live `Session`.
-   * Call with the events returned by a persistence
-   * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+   * Call with the stored events at or past `restoreFloor(checkpoint)` (a
+   * `SessionHandle.read` slice) and that same floor as
    * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
    * so a shrunk log is detected here. A row is usable iff its
    * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
diff --git a/packages/session/session-telemetry/src/coordinator.ts b/packages/session/session-telemetry/src/coordinator.ts
index 24150051fb..6914499907 100644
--- a/packages/session/session-telemetry/src/coordinator.ts
+++ b/packages/session/session-telemetry/src/coordinator.ts
@@ -46,10 +46,10 @@ const handoffCursor = new WeakMap<Session, SessionSeqCursor>()
 /**
  * Install the telemetry capture side onto a context for one backend.
  *
- * Live capture registers the persistence-coordinator listener set plus the
- * `agent/error` relay, all through `ctx.effect()`/`ctx.on()` on the composing
- * fiber, and sweeps already-live sessions (a hot reload does not replay
- * `session/created`). A `session/disposed` captures the session's `shutdown`
+ * Live capture registers its own `session/created` / `session/event` /
+ * `session/disposed` listener set plus the `agent/error` relay, all through
+ * `ctx.effect()`/`ctx.on()` on the composing fiber, and sweeps already-live
+ * sessions (a hot reload does not replay `session/created`). A `session/disposed` captures the session's `shutdown`
  * operational record at its own termination edge and retires it from the
  * adopted set. On-demand capture registers none of those continuous listeners;
  * {@link captureSession} reads the canonical log explicitly and never creates
diff --git a/packages/session/session-title/tests/persistence.spec.ts b/packages/session/session-title/tests/persistence.spec.ts
index fa7c5bd833..755dd916af 100644
--- a/packages/session/session-title/tests/persistence.spec.ts
+++ b/packages/session/session-title/tests/persistence.spec.ts
@@ -23,31 +23,41 @@ afterEach(async () => {
 
 async function appendPersistedTitle(ctx: Context, id: ReturnType<typeof SessionId>): Promise<void> {
   const session = ctx.sessions.create(id)
-  session.append('turn/start', {
-    turn: 1,
-  })
-  session.append('user/message', createUserMessage({
-    content: [{ type: 'text', text: 'Persist this session title' }],
-    source: { kind: 'user' },
-  }), { surfaceOp: 'append' })
-  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-  await ctx.sessionTitle.refresh(session)
+  const handle = await ctx.sessionPersistence.create(session.header)
+  try {
+    session.append('turn/start', {
+      turn: 1,
+    })
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'Persist this session title' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    await ctx.sessionTitle.refresh(session)
+  } finally {
+    await handle.close()
+  }
 }
 
 async function expectPersistedTitle(ctx: Context, id: ReturnType<typeof SessionId>): Promise<void> {
-  const loaded = await ctx.sessionPersistence.load(id)
-  expect(foldSessionTitle(loaded.events)).toMatchObject({
-    title: 'Persist this session title',
-    messageSeqs: [1],
-    source: { kind: 'fallback' },
-    eventSeq: 3,
-  })
-  expect(loaded.events.map(event => event.type)).toEqual([
-    'turn/start',
-    'user/message',
-    'turn/end',
-    'session/title',
-  ])
+  const handle = await ctx.sessionPersistence.open(id, 'read')
+  try {
+    const events = await handle.read()
+    expect(foldSessionTitle(events)).toMatchObject({
+      title: 'Persist this session title',
+      messageSeqs: [1],
+      source: { kind: 'fallback' },
+      eventSeq: 3,
+    })
+    expect(events.map(event => event.type)).toEqual([
+      'turn/start',
+      'user/message',
+      'turn/end',
+      'session/title',
+    ])
+  } finally {
+    await handle.close()
+  }
 }
 
 describe('session title persistence round trips', () => {
diff --git a/packages/shell/shell-env/README.i18n.yaml b/packages/shell/shell-env/README.i18n.yaml
index cbfe47cb5c..57a271577a 100644
--- a/packages/shell/shell-env/README.i18n.yaml
+++ b/packages/shell/shell-env/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/shell/shell-env/README.md
-README.md: 0004e0c73321b73a61c4ffa64ad45fc13a290231
-README.zh.md: ba923d644c85c7e150e24d1440c78c152c5fac88
+README.md: f85fb0005e94dc59939cfd2e9f0d69e5cdc7d133
+README.zh.md: f0d02de700c2e5e7d8fe0081813cda96bd099a78
diff --git a/packages/shell/shell-env/README.md b/packages/shell/shell-env/README.md
index 0004e0c733..f85fb0005e 100644
--- a/packages/shell/shell-env/README.md
+++ b/packages/shell/shell-env/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-shell-env` provides the trusted `DSH_*` environment that every model shell call — bash or pwsh — runs with: built-in facts such as `DSH_HOME`, `DSH_SHELL=1`, and the agent's `DSH_SESSION_ID`, plus `DSH_SESSION_JSONL` when the active persistence backend locates a JSONL artifact. Plugin authors can register their own facts with declared keys, collected per execution and disposed with their plugin; duplicate ownership or undeclared runtime keys fail loudly instead of silently overwriting. The registry changes nothing else the model sees — the shell tools own their own schemas and prompts. Choose it in any composition that mounts a model shell tool; configuration only picks the Harness home directory.
+`dsh-shell-env` provides the trusted `DSH_*` environment that every model shell call — bash or pwsh — runs with: built-in facts such as `DSH_HOME`, `DSH_SHELL=1`, and the agent's `DSH_SESSION_ID`. Plugin authors can register their own facts with declared keys, collected per execution and disposed with their plugin; duplicate ownership or undeclared runtime keys fail loudly instead of silently overwriting. The registry changes nothing else the model sees — the shell tools own their own schemas and prompts. Choose it in any composition that mounts a model shell tool; configuration only picks the Harness home directory.
 
 ## Table of Contents
 
@@ -29,7 +29,7 @@ Load this plugin in any composition that mounts a model shell tool (`dsh-tool-ba
 
 ### What every shell call receives
 
-Every call receives `DSH_HOME` (the absolute Harness home), `DSH_SHELL=1`, and, for agent calls, `DSH_SESSION_ID` (the calling session's id). When the active persistence backend locates a JSONL artifact for the session, calls also receive `DSH_SESSION_JSONL` with its absolute target path — a location hint, not a guarantee: the file may not exist before the first flush and may not contain the current buffered turn, and the value is not an authorization credential.
+Every call receives `DSH_HOME` (the absolute Harness home), `DSH_SHELL=1`, and, for agent calls, `DSH_SESSION_ID` (the calling session's id).
 
 ### Adding your own environment facts
 
@@ -80,13 +80,13 @@ This section explains the design decisions behind the registry and points at the
 
 - **Trusted namespace, rebuilt per call.** The environment is a Harness-owned `DSH_*` namespace: the shell executor discards inherited `DSH_*` values and merges the registry's current snapshot for each execution, so nested harnesses and concurrent parent/child agents cannot leak stale identities, and `process.env` is never modified.
 - **Declared ownership, loud conflicts.** Contributors declare their keys up front so duplicate ownership is detected before the first command; resolvers may only return declared keys.
-- **Built-ins stay here.** `DSH_HOME`, `DSH_SHELL`, and `DSH_SESSION_ID` are reserved for the registry; `DSH_SESSION_JSONL` is contributed by this plugin's own persistence translator, which reads the backend-neutral `sessionPersistence.locate()` seam.
+- **Built-ins stay here.** `DSH_HOME`, `DSH_SHELL`, and `DSH_SESSION_ID` are reserved for the registry; contributors cannot claim them.
 
 ### Source map
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry, `ShellEnvRegistry` service, built-in facts and the persistence contributor |
+| [`src/index.ts`](src/index.ts) | Plugin entry, `ShellEnvRegistry` service, and the built-in facts |
 | — | No runtime invariant companion is published; the environment registry validates ownership and collected values at each registration/collection; it publishes no independent snapshot that a companion could cross-check. |
 
 ### Collection
@@ -128,7 +128,6 @@ The managed environment never enters the request prefix, so it does not invalida
 These limits define when the registry is a poor fit or needs care. They are current package constraints, not a task backlog.
 
 - **`list()` enumerates plugin-contributed variables only** — registry-owned built-ins (`DSH_HOME`, `DSH_SHELL`, `DSH_SESSION_ID`) are not included, so diagnostics, prompt, or UI code must not treat `list()` as an exhaustive environment catalog.
-- **`DSH_SESSION_JSONL` is a location hint, not a guarantee** — the file may not exist before the first flush and may not contain the current buffered turn, and the value is not an authorization credential.
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/shell/shell-env/README.zh.md b/packages/shell/shell-env/README.zh.md
index ba923d644c..f0d02de700 100644
--- a/packages/shell/shell-env/README.zh.md
+++ b/packages/shell/shell-env/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-shell-env` 提供每次模型 shell 调用——bash 或 pwsh——所运行的受信 `DSH_*` 环境：内置事实如 `DSH_HOME`、`DSH_SHELL=1` 与 agent（智能体）的 `DSH_SESSION_ID`，以及活跃持久化后端定位到 JSONL 产物时的 `DSH_SESSION_JSONL`。插件作者可以注册自己的事实，带声明键、按每次执行收集，并随插件释放；重复所有权或未声明的运行时键会响亮失败，而不是静默覆盖。注册表不会改变模型看到的其他任何内容——shell 工具拥有各自的 schema 与提示词。任何挂载了模型 shell 工具的组合都适合选择它；配置只决定 Harness 主目录。
+`dsh-shell-env` 提供每次模型 shell 调用——bash 或 pwsh——所运行的受信 `DSH_*` 环境：内置事实如 `DSH_HOME`、`DSH_SHELL=1` 与 agent（智能体）的 `DSH_SESSION_ID`。插件作者可以注册自己的事实，带声明键、按每次执行收集，并随插件释放；重复所有权或未声明的运行时键会响亮失败，而不是静默覆盖。注册表不会改变模型看到的其他任何内容——shell 工具拥有各自的 schema 与提示词。任何挂载了模型 shell 工具的组合都适合选择它；配置只决定 Harness 主目录。
 
 ## 目录
 
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 每次 shell 调用都会收到什么
 
-每次调用都会收到 `DSH_HOME`（Harness 主目录的绝对路径）、`DSH_SHELL=1`，agent 调用还会收到 `DSH_SESSION_ID`（调用方会话的 id）。当活跃持久化后端为该会话定位到 JSONL 产物时，调用还会收到带绝对目标路径的 `DSH_SESSION_JSONL`——这只是位置提示，不是保证：首次 flush 之前文件可能不存在，也可能不包含当前缓冲中的轮次，而且该值不是授权凭据。
+每次调用都会收到 `DSH_HOME`（Harness 主目录的绝对路径）、`DSH_SHELL=1`，agent 调用还会收到 `DSH_SESSION_ID`（调用方会话的 id）。
 
 ### 添加你自己的环境事实
 
@@ -80,13 +80,13 @@ contributor 必须声明它返回的每个键；返回未声明或非字符串
 
 - **受信命名空间，每次调用重建。** 环境是归 Harness 所有的 `DSH_*` 命名空间：shell 执行器丢弃继承的 `DSH_*` 值，并为每次执行合并注册表的当前快照，因此嵌套 harness 与并发的父子 agent 无法泄漏陈旧身份，`process.env` 也永不被修改。
 - **声明的所有权，响亮的冲突。** contributor 预先声明键，使重复所有权在第一条命令之前就被发现；resolver 只能返回已声明的键。
-- **内置键留在这里。** `DSH_HOME`、`DSH_SHELL` 与 `DSH_SESSION_ID` 为注册表保留；`DSH_SESSION_JSONL` 由本插件自己的持久化翻译器贡献，它读取与后端无关的 `sessionPersistence.locate()` seam。
+- **内置键留在这里。** `DSH_HOME`、`DSH_SHELL` 与 `DSH_SESSION_ID` 为注册表保留；contributor 不能声称拥有它们。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口、`ShellEnvRegistry` 服务、内置事实与持久化 contributor |
+| [`src/index.ts`](src/index.ts) | 插件入口、`ShellEnvRegistry` 服务与内置事实 |
 | — | 不发布运行时不变式伴生入口；收集可通过工具执行观察。 |
 
 ### 收集
@@ -128,7 +128,6 @@ contributor 必须声明它返回的每个键；返回未声明或非字符串
 这些限制说明注册表何时不合适或需要小心使用。它们是当前包约束，不是任务积压。
 
 - **`list()` 只枚举插件贡献的变量**——注册表自有的内置键（`DSH_HOME`、`DSH_SHELL`、`DSH_SESSION_ID`）不包含在内，因此诊断、prompt 或 UI 代码不得把 `list()` 当作完整的环境目录。
-- **`DSH_SESSION_JSONL` 只是位置提示，不是保证**——首次 flush 之前文件可能不存在，也可能不包含当前缓冲中的轮次，而且该值不是授权凭据。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/shell/shell-env/package.json b/packages/shell/shell-env/package.json
index 98bc4bdbc9..53c1406b10 100644
--- a/packages/shell/shell-env/package.json
+++ b/packages/shell/shell-env/package.json
@@ -29,7 +29,6 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-shell": "workspace:^",
     "@deepseek-ai/dsh-home-paths": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^"
   },
@@ -41,7 +40,6 @@
     "@deepseek-ai/dsh-shell": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-home-paths": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^"
   }
diff --git a/packages/shell/shell-env/src/index.ts b/packages/shell/shell-env/src/index.ts
index 88f329d281..4b52f28c01 100644
--- a/packages/shell/shell-env/src/index.ts
+++ b/packages/shell/shell-env/src/index.ts
@@ -14,7 +14,6 @@ import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-shell'
 import type { DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-shell'
 import { DSH_HOME_ENV, resolveDshHome } from '@deepseek-ai/dsh-home-paths'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
-import type {} from '@deepseek-ai/dsh-session-persistence'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -70,7 +69,6 @@ export interface BashEnvVariableInfo extends BashEnvVariable {
 
 const DSH_SHELL_KEY = `${DSH_ENV_PREFIX}SHELL` as const
 const DSH_SESSION_ID_KEY = `${DSH_ENV_PREFIX}SESSION_ID` as const
-const DSH_SESSION_JSONL_KEY = `${DSH_ENV_PREFIX}SESSION_JSONL` as const
 const RESERVED_BASH_ENV_KEYS = new Set<DshEnvironmentKey>([
   DSH_HOME_ENV,
   DSH_SHELL_KEY,
@@ -193,25 +191,10 @@ export class ShellEnvRegistry extends Service {
 }
 
 /**
- * Load the shell-env plugin: register the `ctx.shellEnv` service and the
- * shell-agnostic persistence contributor (`DSH_SESSION_JSONL`).
+ * Load the shell-env plugin: register the `ctx.shellEnv` registry service.
  * @param ctx - Cordis context that owns the service and registrations.
  * @param config - home-directory configuration for the built-in variables.
  */
 export function apply(ctx: Context, config: Config = {}): void {
-  const registry = new ShellEnvRegistry(ctx, config)
-  registry.register({
-    name: 'session-persistence',
-    variables: {
-      [DSH_SESSION_JSONL_KEY]: {
-        description: 'Absolute target path of the current session JSONL when the active persistence backend provides one.',
-      },
-    },
-    resolve(execution) {
-      const agent = execution.agent
-      if (agent === undefined) return {}
-      const location = ctx.get('sessionPersistence')?.locate(agent.session.header)
-      return location?.kind === 'jsonl' ? { [DSH_SESSION_JSONL_KEY]: location.path } : {}
-    },
-  })
+  new ShellEnvRegistry(ctx, config)
 }
diff --git a/packages/shell/shell-env/tests/shell-env.spec.ts b/packages/shell/shell-env/tests/shell-env.spec.ts
index 4df99a41a4..1aedc3cfe1 100644
--- a/packages/shell/shell-env/tests/shell-env.spec.ts
+++ b/packages/shell/shell-env/tests/shell-env.spec.ts
@@ -199,40 +199,10 @@ describe('ShellEnvRegistry', () => {
     expect(registry.collect(execution())).not.toHaveProperty('DSH_EXPLICIT_DISPOSAL')
   })
 
-  it('the plugin registers the service and the persistence contributor on load', async () => {
+  it('the plugin registers the service with no contributors on load', async () => {
     const ctx = new Context()
     await ctx.plugin(BashEnvPlugin)
     expect(ctx.shellEnv).toBeInstanceOf(ShellEnvRegistry)
-    expect(ctx.shellEnv.list()).toEqual([
-      {
-        contributor: 'session-persistence',
-        description: 'Absolute target path of the current session JSONL when the active persistence backend provides one.',
-        key: 'DSH_SESSION_JSONL',
-      },
-    ])
-  })
-
-  it('the persistence contributor resolves DSH_SESSION_JSONL only for a jsonl backend', async () => {
-    const ctx = new Context()
-    await ctx.plugin(BashEnvPlugin)
-    ctx.provide('sessionPersistence', {
-      locate: () => ({ kind: 'jsonl' as const, path: 'C:\\sessions\\s.jsonl' }),
-    })
-    expect(ctx.shellEnv.collect(execution('sess-p')).DSH_SESSION_JSONL).toBe('C:\\sessions\\s.jsonl')
-  })
-
-  it('the persistence contributor omits the variable for a non-jsonl backend', async () => {
-    const ctx = new Context()
-    await ctx.plugin(BashEnvPlugin)
-    ctx.provide('sessionPersistence', {
-      locate: () => ({ kind: 'sqlite' as const, path: 'C:\\sessions\\s.db' }),
-    })
-    expect(ctx.shellEnv.collect(execution('sess-p'))).not.toHaveProperty('DSH_SESSION_JSONL')
-  })
-
-  it('the persistence contributor omits the variable without a persistence backend', async () => {
-    const ctx = new Context()
-    await ctx.plugin(BashEnvPlugin)
-    expect(ctx.shellEnv.collect(execution('sess-p'))).not.toHaveProperty('DSH_SESSION_JSONL')
+    expect(ctx.shellEnv.list()).toEqual([])
   })
 })
diff --git a/packages/shell/shell-env/tsconfig.json b/packages/shell/shell-env/tsconfig.json
index fa1cbc5430..6db2523824 100644
--- a/packages/shell/shell-env/tsconfig.json
+++ b/packages/shell/shell-env/tsconfig.json
@@ -25,9 +25,6 @@
     },
     {
       "path": "../../core/tools"
-    },
-    {
-      "path": "../../session/session-persistence"
     }
   ]
 }
diff --git a/packages/shell/tool-bash/tests/integration.spec.ts b/packages/shell/tool-bash/tests/integration.spec.ts
index 7923382bc8..f06f4d22f3 100644
--- a/packages/shell/tool-bash/tests/integration.spec.ts
+++ b/packages/shell/tool-bash/tests/integration.spec.ts
@@ -1,7 +1,7 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
@@ -96,14 +96,14 @@ async function pollUntil(predicate: () => boolean, timeoutMs = 5_000): Promise<v
 }
 
 describe('bash tool through the agent loop', () => {
-  it('first-turn bash receives session identity before the lazy JSONL file materializes', async () => {
+  it('first-turn bash receives session identity in a scrubbed DSH_* namespace', async () => {
     const root = mkdtempSync(join(tmpdir(), 'dsh-bash-session-env-'))
     dirs.push(root)
     const dshHome = join(root, 'dsh-home')
     vi.stubEnv('DSH_STALE_PARENT', 'stale')
     const adapter = new MockAdapter([
       toolCallResponse('call-1', 'bash', {
-        command: 'printf \'%s\\n%s\\n%s\\n%s\\n%s\\n\' "$DSH_HOME" "$DSH_SHELL" "$DSH_SESSION_ID" "$DSH_SESSION_JSONL" "${DSH_STALE_PARENT-unset}"; if [ -e "$DSH_SESSION_JSONL" ]; then printf \'present\\n\'; else printf \'absent\\n\'; fi',
+        command: 'printf \'%s\\n%s\\n%s\\n%s\\n\' "$DSH_HOME" "$DSH_SHELL" "$DSH_SESSION_ID" "${DSH_STALE_PARENT-unset}"',
         description: 'inspect session environment',
       }),
       textResponse('Session environment inspected.'),
@@ -114,18 +114,12 @@ describe('bash tool through the agent loop', () => {
       agentOptions: { provider: 'mock', model: 'mock' },
     })
     const agent = handle.agent
-    const location = ctx.sessionPersistence.locate(agent.session.header)
-    expect(location?.kind).toBe('jsonl')
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'inspect the current session' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
     const result = findEvent(events(agent), 'tool/result')
-    expect(resultText(result)).toBe(`${dshHome}\n1\nsession-env-id\n${location?.path}\nunset\nabsent\n`)
-    await ctx.sessions.flush(agent.session)
-    expect(existsSync(location!.path)).toBe(true)
-    const header = JSON.parse(readFileSync(location!.path, 'utf8').split('\n')[0]!) as { type: string; id: string }
-    expect(header).toMatchObject({ type: 'session', id: 'session-env-id' })
+    expect(resultText(result)).toBe(`${dshHome}\n1\nsession-env-id\nunset\n`)
     await handle.dispose()
   })
 
@@ -135,7 +129,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('The command printed integration-ok.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('it-fg'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('it-fg'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'run echo integration-ok' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
@@ -167,7 +161,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('It failed with code 9.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('it-exit'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('it-exit'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'run exit 9' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
@@ -200,7 +194,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('Background job finished.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('it-bg'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('it-bg'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'run echo bg-ok in the background' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
diff --git a/packages/shell/tool-bash/tests/tools.spec.ts b/packages/shell/tool-bash/tests/tools.spec.ts
index ca8ce99c89..747d98b48d 100644
--- a/packages/shell/tool-bash/tests/tools.spec.ts
+++ b/packages/shell/tool-bash/tests/tools.spec.ts
@@ -11,8 +11,7 @@ import ToolRuntime, { TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepse
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { turnBoundaryProjectionDefinition } from '@deepseek-ai/dsh-agent-loop'
-import SessionStore, { SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
-import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs'
 import ApprovalService from '@deepseek-ai/dsh-user-approval'
@@ -205,37 +204,20 @@ function sandboxAgent(
   ctx?: Context,
   onAppend?: (type: string) => void,
 ): Agent {
-  const events: Array<{
-    type: string
-    seq: ReturnType<typeof SessionSeq>
-    time: number
-    data: Record<string, unknown>
-  }> = [{ type: 'turn/start', seq: SessionSeq(0), time: 0, data: { turn: 1 } }]
-  if (mode !== undefined) {
-    events.push({ type: 'sandbox/mode', seq: SessionSeq(1), time: 1, data: { mode } })
-  }
+  const events: Array<{ type: string; data?: Record<string, unknown>; seq: number }> = [{ type: 'turn/start', seq: 0, data: { turn: 1 } }]
+  if (mode !== undefined) events.push({ type: 'sandbox/mode', seq: events.length, data: { mode } })
   const id = SessionId('sandbox-session')
   return {
     id,
     ...ctx === undefined ? {} : { ctx: ctx.plugin(() => {}).ctx },
     session: {
       id,
-      header: { version: 0, id, createdAt: 0, isSeeded: false },
-      inheritedEventCount: SessionLogOffset(0),
-      firstLiveSeq: SessionLogOffset(0),
-      get seq() { return SessionLogOffset(events.length) },
-      eventAt: (seq: ReturnType<typeof SessionSeq>) => events[seq],
-      snapshotEvents: (
-        fromSeq = SessionLogOffset(0),
-        toSeqExclusive = SessionLogOffset(events.length),
-      ) => events.slice(fromSeq, toSeqExclusive),
+      header: { version: 0, id, createdAt: 0 },
+      get seq() { return events.length },
+      eventAt: (seq: number) => events[seq],
+      snapshotEvents: () => events,
       append: (type: string, data: Record<string, unknown>) => {
-        const event = {
-          type,
-          seq: SessionSeq(events.length),
-          time: events.length,
-          data,
-        }
+        const event = { type, data, seq: events.length }
         events.push(event)
         onAppend?.(type)
         return event
@@ -644,10 +626,11 @@ describe('sandbox escalation through the generic task producer', () => {
     expect(prompted).not.toHaveBeenCalled()
 
     const malformed = sandboxAgent()
-    ;(malformed.session.append as unknown as (
-      type: string,
-      data: Record<string, unknown>,
-    ) => unknown)('sandbox/mode', { mode: 'unknown-mode' })
+    ;(malformed.session.snapshotEvents() as unknown as Array<{ type: string; data: { mode: string }; seq: number }>).push({
+      type: 'sandbox/mode',
+      data: { mode: 'unknown-mode' },
+      seq: malformed.session.seq,
+    })
     expect(text(await call(ctx, 'bash', escalate, malformed))).toContain('not strictly wider')
   })
 
@@ -1131,15 +1114,11 @@ describe('the model-facing bash tool builds its request from named args only (no
     }
   }
 
-  async function setupRecording(withJsonl = false) {
+  async function setupRecording() {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRuntime)
     await ctx.plugin(AgentRegistry)
-    if (withJsonl) {
-      await ctx.plugin(SessionStore)
-      await ctx.plugin(JsonlSessionPersistence, { root: join(spillDir, 'jsonl') })
-    }
     await ctx.plugin(LocalJobRegistry)
     await ctx.plugin(ToolTasks)
     await ctx.plugin(BashEnvPlugin, { dshHome: recordingDshHome })
@@ -1152,13 +1131,12 @@ describe('the model-facing bash tool builds its request from named args only (no
     const { ctx } = await setupRecording()
     const description = ctx.tools.get('bash')?.description ?? ''
     expect(description).toContain('$DSH_*')
-    expect(description).not.toContain('DSH_SESSION_JSONL')
   })
 
-  it('injects the session id and JSONL target path into a foreground request', async () => {
-    const { ctx, bash } = await setupRecording(true)
+  it('injects built-ins and the stable session id into a foreground request', async () => {
+    const { ctx, bash } = await setupRecording()
     const agent = registerFakeAgent(ctx, 'request-fg', () => undefined)
-    const path = ctx.sessionPersistence.locate(agent.session.header)?.path
+    const ambient = process.env.DSH_SESSION_ID
 
     await ctx.tools.execute({
       signal: testToolSignal,
@@ -1171,15 +1149,14 @@ describe('the model-facing bash tool builds its request from named args only (no
     expect(bash.requests[0]?.dshEnv).toEqual({
       DSH_HOME: recordingDshHome,
       DSH_SESSION_ID: 'request-fg',
-      DSH_SESSION_JSONL: path,
       DSH_SHELL: '1',
     })
+    expect(process.env.DSH_SESSION_ID).toBe(ambient)
   })
 
   it('injects the same trusted variables into a background request without forwarding model env', async () => {
-    const { ctx, bash } = await setupRecording(true)
+    const { ctx, bash } = await setupRecording()
     const agent = registerFakeAgent(ctx, 'request-bg', () => undefined)
-    const path = ctx.sessionPersistence.locate(agent.session.header)?.path
 
     await ctx.tools.execute({
       signal: testToolSignal,
@@ -1189,7 +1166,7 @@ describe('the model-facing bash tool builds its request from named args only (no
         command: 'sleep 1',
         description: 'run command',
         run_in_background: true,
-        env: { DSH_SESSION_ID: 'spoofed', DSH_SESSION_JSONL: '/tmp/spoofed' },
+        env: { DSH_SESSION_ID: 'spoofed' },
       },
       agent,
     })
@@ -1198,34 +1175,12 @@ describe('the model-facing bash tool builds its request from named args only (no
     expect(bash.requests[0]?.dshEnv).toEqual({
       DSH_HOME: recordingDshHome,
       DSH_SESSION_ID: 'request-bg',
-      DSH_SESSION_JSONL: path,
       DSH_SHELL: '1',
     })
   })
 
-  it('injects built-ins and the stable session id when no JSONL locator is available', async () => {
-    const { ctx, bash } = await setupRecording()
-    const agent = registerFakeAgent(ctx, 'request-id-only', () => undefined)
-    const ambient = process.env.DSH_SESSION_ID
-
-    await ctx.tools.execute({
-      signal: testToolSignal,
-      callId: ToolCallId('session-env-id-only'),
-      name: 'bash',
-      arguments: { command: 'true', description: 'run command' },
-      agent,
-    })
-
-    expect(bash.requests[0]?.dshEnv).toEqual({
-      DSH_HOME: recordingDshHome,
-      DSH_SESSION_ID: 'request-id-only',
-      DSH_SHELL: '1',
-    })
-    expect(process.env.DSH_SESSION_ID).toBe(ambient)
-  })
-
   it('keeps parent and child agent session environments isolated', async () => {
-    const { ctx, bash } = await setupRecording(true)
+    const { ctx, bash } = await setupRecording()
     const parent = registerFakeAgent(ctx, 'request-parent', () => undefined)
     const child = registerFakeAgent(ctx, 'request-child', () => undefined)
 
@@ -1243,17 +1198,14 @@ describe('the model-facing bash tool builds its request from named args only (no
       {
         DSH_HOME: recordingDshHome,
         DSH_SESSION_ID: 'request-parent',
-        DSH_SESSION_JSONL: ctx.sessionPersistence.locate(parent.session.header)?.path,
         DSH_SHELL: '1',
       },
       {
         DSH_HOME: recordingDshHome,
         DSH_SESSION_ID: 'request-child',
-        DSH_SESSION_JSONL: ctx.sessionPersistence.locate(child.session.header)?.path,
         DSH_SHELL: '1',
       },
     ])
-    expect(bash.requests[0]?.dshEnv?.DSH_SESSION_JSONL).not.toBe(bash.requests[1]?.dshEnv?.DSH_SESSION_JSONL)
   })
 
   it('does not forward trusted-only fields even when the model includes them as extra arguments', async () => {
diff --git a/packages/subagent/subagent-fork-in-process/tests/multi-subagent.spec.ts b/packages/subagent/subagent-fork-in-process/tests/multi-subagent.spec.ts
index 67b0dd9d70..e761f070af 100644
--- a/packages/subagent/subagent-fork-in-process/tests/multi-subagent.spec.ts
+++ b/packages/subagent/subagent-fork-in-process/tests/multi-subagent.spec.ts
@@ -43,7 +43,7 @@ async function setup(script: Script) {
   await ctx.plugin(Spawn, { providerName: 'spawn' })
   await ctx.plugin(fork, { providerName: 'fork' })
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent }
 }
 
diff --git a/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts b/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
index 0219824497..ac9a994c29 100644
--- a/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
+++ b/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
@@ -49,7 +49,7 @@ async function setup(script: Script) {
   await ctx.plugin(SubagentRuntime)
   await ctx.plugin(fork, { providerName: 'fork' })
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent }
 }
 
diff --git a/packages/subagent/subagent-in-process-driver/tests/inheritance.spec.ts b/packages/subagent/subagent-in-process-driver/tests/inheritance.spec.ts
index d5f26b8558..4d86cb3705 100644
--- a/packages/subagent/subagent-in-process-driver/tests/inheritance.spec.ts
+++ b/packages/subagent/subagent-in-process-driver/tests/inheritance.spec.ts
@@ -48,7 +48,7 @@ async function setupWalled(script: Script): Promise<{ ctx: Context; parent: Agen
   await ctx.plugin(ApprovalService)
   await ctx.plugin(AgentLoop, { agents: [] })
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(
+  const parent = await ctx.agentLoop.create(
     SessionId('parent'),
     { provider: 'mock', model: 'mock' },
     { cwd: workspace },
diff --git a/packages/subagent/subagent-in-process-driver/tests/structured.spec.ts b/packages/subagent/subagent-in-process-driver/tests/structured.spec.ts
index c145204ea2..2b5350d951 100644
--- a/packages/subagent/subagent-in-process-driver/tests/structured.spec.ts
+++ b/packages/subagent/subagent-in-process-driver/tests/structured.spec.ts
@@ -78,7 +78,7 @@ async function setup(script: Script, options: SetupOptions = {}) {
     start: (request: ResolvedSubagentStartRequest) => startInProcessRun(request, {}),
   })
   ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent, adapter, disposeProvider }
 }
 
diff --git a/packages/subagent/subagent-in-process-driver/tests/subagent-in-process-driver.spec.ts b/packages/subagent/subagent-in-process-driver/tests/subagent-in-process-driver.spec.ts
index df0250cf3f..c669e614b6 100644
--- a/packages/subagent/subagent-in-process-driver/tests/subagent-in-process-driver.spec.ts
+++ b/packages/subagent/subagent-in-process-driver/tests/subagent-in-process-driver.spec.ts
@@ -33,7 +33,7 @@ async function setup(script: Script, parentOptions: Partial<AgentOptions> = {})
   await ctx.plugin(SubagentRuntime)
   const adapter = new MockAdapter(script)
   ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock', ...parentOptions })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock', ...parentOptions })
   return { ctx, parent, adapter }
 }
 
@@ -71,7 +71,7 @@ describe('startInProcessRun', () => {
 
   it('uses explicit child model selectors when the parent has none and preserves its cwd', async () => {
     const { ctx } = await setup([textResponse('driver answer')])
-    const parent = ctx.agentLoop.create(SessionId('bare-parent'), {}, { cwd: '/workspace' })
+    const parent = await ctx.agentLoop.create(SessionId('bare-parent'), {}, { cwd: '/workspace' })
     const run = await startInProcessRun({
       ...request(parent),
       agentOptions: { provider: 'mock', model: 'mock' },
@@ -307,7 +307,7 @@ describe('startInProcessRun', () => {
     // no provider/model is fabricated, so the child's turn errors for want of a
     // route rather than silently adopting one.
     const { ctx } = await setup([])
-    const parent = ctx.agentLoop.create(SessionId('routeless-parent'), {})
+    const parent = await ctx.agentLoop.create(SessionId('routeless-parent'), {})
     const run = await startInProcessRun(request(parent), {})
     const child = ctx.agents.get(run.id)!
     expect(child.options).toEqual({ subagentDepth: 1 })
diff --git a/packages/subagent/subagent-spawn-in-process/tests/spawn-in-process.e2e.ts b/packages/subagent/subagent-spawn-in-process/tests/spawn-in-process.e2e.ts
index 8a17743341..3e764070f7 100644
--- a/packages/subagent/subagent-spawn-in-process/tests/spawn-in-process.e2e.ts
+++ b/packages/subagent/subagent-spawn-in-process/tests/spawn-in-process.e2e.ts
@@ -23,7 +23,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('spawn backend with-key smoke', (
   it('a parent delegates to a child that writes a file on disk', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-subagent-spawn-e2e-'))
     ctx = await spawnHarness(workdir)
-    const parent = ctx.agentLoop.create(SessionId('e2e-parent'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    const parent = await ctx.agentLoop.create(SessionId('e2e-parent'), { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
 
     parent.followup(createUserMessage({
       content: [{ type: 'text', text:
diff --git a/packages/subagent/subagent-spawn-in-process/tests/subagent-spawn-in-process.spec.ts b/packages/subagent/subagent-spawn-in-process/tests/subagent-spawn-in-process.spec.ts
index c46f99514f..dc9d3ed4d1 100644
--- a/packages/subagent/subagent-spawn-in-process/tests/subagent-spawn-in-process.spec.ts
+++ b/packages/subagent/subagent-spawn-in-process/tests/subagent-spawn-in-process.spec.ts
@@ -43,7 +43,7 @@ async function setup(script: Script) {
   await ctx.plugin(SubagentRuntime)
   await ctx.plugin(spawn, { providerName: 'spawn' })
   ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent, adapter }
 }
 
@@ -334,7 +334,7 @@ describe('dsh-subagent-spawn-in-process', () => {
     await ctx.plugin(SubagentRuntime)
     const fiber = await ctx.plugin(spawn, { providerName: 'spawn' })
     ctx.llm.registerAdapter(['mock'], adapter)
-    const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+    const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
     const controller = new AbortController()
     const run = await start(ctx, 'spawn', {
       prompt: [{ type: 'text', text: 'q' }],
@@ -362,7 +362,7 @@ describe('dsh-subagent-spawn-in-process', () => {
     await ctx.plugin(SessionProjectionRegistry)
     await ctx.plugin(SubagentRuntime)
     const fiber = await ctx.plugin(spawn, { providerName: 'spawn' })
-    const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+    const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
     const parentEffects = parent.ctx.fiber.getEffects().length
     const published: string[] = []
     ctx.on('session/created', () => void published.push('session/created'))
diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts
index 2103ce2270..edaa0d0eea 100644
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -33,7 +33,7 @@ import type {
 import { ReasoningEffortId, boundContextSummary, contentHasImage, createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm'
 import { SessionLogOffset } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionId, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId , SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import type { SessionObservation, SessionQueryEngine } from '@deepseek-ai/dsh-session-query'
 import type { ToolRestriction } from '@deepseek-ai/dsh-tools'
@@ -455,53 +455,94 @@ export class SubagentContinuationManager {
     // parent's future, not to this child.
     const delegatedPolicies = captureDelegatedPolicyOverrides(parent)
 
-    const prepared = await this.host.prepareContinuable(spec.provider, {
-      sessionId: childId,
-      parent,
-      signal: spec.signal,
-    })
-    spec.signal.throwIfAborted()
-    this.assertAdmitting(parent)
-
-    const inheritedEventCount = SessionLogOffset(prepared.seed?.length ?? 0)
-    const seed = seedDescriptorTurn(childId, prepared.seed, descriptor)
-    const messageId = await this.locks.run(childId, async () => {
+    // Hold the parent's own Activation open across the establishment awaits:
+    // an idle continuation-managed parent must not settle while a caller is
+    // still creating its child, or the admitted delivery would find a stale
+    // parent identity. A turn-scoped delegation never needs this (the parent
+    // is `running`), but this service is also callable outside a turn.
+    const releaseHold = this.holdOwnership(parent, childId)
+    try {
+      const prepared = await this.host.prepareContinuable(spec.provider, {
+        sessionId: childId,
+        parent,
+        signal: spec.signal,
+      })
       spec.signal.throwIfAborted()
       this.assertAdmitting(parent)
-      this.assertChildIdAvailable(childId)
-      if (spec.childId !== undefined) {
-        const persisted = await persistence.listSnapshots(spec.signal)
+
+      const inheritedEventCount = SessionLogOffset(prepared.seed?.length ?? 0)
+      const seed = seedDescriptorTurn(childId, prepared.seed, descriptor)
+      const messageId = await this.locks.run(childId, async () => {
         spec.signal.throwIfAborted()
         this.assertAdmitting(parent)
         this.assertChildIdAvailable(childId)
-        if (persisted.some(snapshot => snapshot.header.id === childId)) {
-          throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD')
+        if (spec.childId !== undefined) {
+          const persisted = await persistence.stat(childId, { signal: spec.signal })
+          spec.signal.throwIfAborted()
+          this.assertAdmitting(parent)
+          this.assertChildIdAvailable(childId)
+          if (persisted !== undefined) {
+            throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD')
+          }
         }
-      }
-      const activation = await this.materialize({
-        childId,
-        provider: spec.provider,
-        parent,
-        create: {
-          seed,
-          meta: childSessionMeta(parent, childDepth, prepared.seed !== undefined),
-          inheritedEventCount,
-          delegatedPolicies,
-        },
-        agentOptions,
-        composition: { persona: request.persona, toolFilter: request.toolFilter },
-        signal: spec.signal,
+        const activation = await this.materialize({
+          childId,
+          provider: spec.provider,
+          parent,
+          create: { seed, meta: childSessionMeta(parent, childDepth, prepared.seed !== undefined), inheritedEventCount, delegatedPolicies },
+          agentOptions,
+          composition: { persona: request.persona, toolFilter: request.toolFilter },
+          signal: spec.signal,
+        })
+        return this.submitMaterialized(
+          activation,
+          isAdjacentAgentSendMessageTool(this.ctx.get('tools')?.get('send_message', activation.handle.agent))
+            ? continuableInitialPrompt(parent.id, request.prompt)
+            : request.prompt,
+          { source: { kind: 'user' }, signal: spec.signal, delivery: 'queue' },
+          parent,
+        )
       })
-      return this.submitMaterialized(
-        activation,
-        isAdjacentAgentSendMessageTool(this.ctx.get('tools')?.get('send_message', activation.handle.agent))
-          ? continuableInitialPrompt(parent.id, request.prompt)
-          : request.prompt,
-        { source: { kind: 'user' }, signal: spec.signal, delivery: 'queue' },
-        parent,
+      return { childId, messageId }
+    } catch (error: unknown) {
+      releaseHold()
+      throw error
+    }
+  }
+
+  /**
+   * Pre-register `childId` in a continuation-managed parent's owned set so the
+   * parent cannot settle while a caller is still establishing or resuming that
+   * child. Returns a releaser for the failure path; it removes only a hold
+   * this call added, and leaves ownership in place once a live Activation for
+   * the child exists (an admitted delivery owns it from then on). A parent
+   * without an Activation needs no hold: only this manager settles parents.
+   * @param parent - the live direct parent the operation is admitted under.
+   * @param childId - the durable child the operation addresses.
+   * @returns the failure-path releaser; a no-op when nothing was added.
+   * @throws {SubagentError} `ACTIVATION_CLOSING` when the parent's own
+   *   disposal transaction is already open.
+   */
+  private holdOwnership(parent: Agent, childId: SessionId): () => void {
+    const parentActivation = this.activations.get(parent.id)
+    if (parentActivation === undefined || parentActivation.handle.agent !== parent) return () => {}
+    if (parentActivation.disposal !== undefined) {
+      throw new SubagentError(
+        `subagent parent "${parent.id}" is being disposed; the child was not established`,
+        'ACTIVATION_CLOSING',
       )
-    })
-    return { childId, messageId }
+    }
+    if (parentActivation.ownedChildren.has(childId)) return () => {}
+    parentActivation.ownedChildren.add(childId)
+    return () => {
+      const live = this.activations.get(childId)
+      /* v8 ignore next 4 -- reaching this arm needs another delivery to establish the child
+       * between this operation's failure and its releaser running, which no test can schedule
+       * deterministically: the ownership edge then belongs to that live Activation, so the
+       * conservative keep leaves it for finishDisposal's releaseOwnership. */
+      if (live !== undefined && live.disposal === undefined) return
+      if (parentActivation.ownedChildren.delete(childId)) this.wake(parentActivation)
+    }
   }
 
   /** Reject one child identity already owned by a live Agent or Session. */
@@ -583,6 +624,24 @@ export class SubagentContinuationManager {
     options: ChildDeliveryOptions,
   ): Promise<MessageId> {
     this.assertAdmitting(parent)
+    // Same hold as `startContinuable`: an idle continuation-managed parent
+    // must not settle underneath a cold resume it is authorizing.
+    const releaseHold = this.holdOwnership(parent, childId)
+    try {
+      return await this.deliverFollowup(parent, childId, content, options)
+    } catch (error: unknown) {
+      releaseHold()
+      throw error
+    }
+  }
+
+  /** The delivery loop behind {@link deliverToChild}, run under the parent hold. */
+  private async deliverFollowup(
+    parent: Agent,
+    childId: SessionId,
+    content: ContentBlock[],
+    options: ChildDeliveryOptions,
+  ): Promise<MessageId> {
     while (true) {
       const live = await this.locks.run(childId, async () => {
         const activation = this.activations.get(childId)
@@ -995,7 +1054,9 @@ export class SubagentContinuationManager {
     // Fold only the child's own suffix: a fork seed replays the parent's log,
     // which may carry an ANCESTOR's descriptor when the parent is itself a
     // continuable child.
-    const descriptor = foldSubagentDescriptor(source.events.slice(source.inheritedEventCount))
+    const descriptor = foldSubagentDescriptor(
+      source.events.slice(source.inheritedEventCount),
+    )
     if (descriptor === undefined || descriptor.mode !== 'continuable') {
       throw new SubagentError(
         `subagent "${childId}" has no supported continuation state and cannot be resumed; choose a different target`,
diff --git a/packages/subagent/subagent/tests/continuation-inheritance.spec.ts b/packages/subagent/subagent/tests/continuation-inheritance.spec.ts
index 97b05c98af..d1dde79a41 100644
--- a/packages/subagent/subagent/tests/continuation-inheritance.spec.ts
+++ b/packages/subagent/subagent/tests/continuation-inheritance.spec.ts
@@ -27,6 +27,7 @@ import ApprovalService from '@deepseek-ai/dsh-user-approval'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import SubagentRuntime from '../src/index.ts'
 import { TestSessionQuery } from './test-session-query.ts'
+import { loadStoredSession } from './persistence-helpers.ts'
 
 type Script = ConstructorParameters<typeof MockAdapter>[0]
 
@@ -54,7 +55,7 @@ async function setup(script: Script) {
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(SubagentFork, { providerName: 'fork' })
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent }
 }
 
@@ -105,7 +106,7 @@ describe('continuable policy inheritance', () => {
     expect(ctx.approval.overrideOf(child.session)).toBe('never')
 
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(policyEvents(loaded.events)).toMatchObject([
       { type: 'sandbox/mode', data: { mode: 'danger-full-access', source: 'delegation' } },
       { type: 'approval/policy', data: { policy: 'never', source: 'delegation' } },
@@ -136,7 +137,7 @@ describe('continuable policy inheritance', () => {
     const started = await starting
 
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(ctx.sandboxPolicy.overrideOf(parent.session)).toBe('danger-full-access')
     expect(foldedSandboxMode(ctx, started.childId, loaded.events)).toBe('read-only')
   })
@@ -147,7 +148,7 @@ describe('continuable policy inheritance', () => {
     const started = await ctx.subagents.startContinuable(startSpec(parent))
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(policyEvents(loaded.events)).toMatchObject([
       { type: 'approval/policy', data: { policy: 'never', source: 'delegation' } },
     ])
@@ -165,8 +166,7 @@ describe('continuable policy inheritance', () => {
     const started = await ctx.subagents.startContinuable(startSpec(parent, 'fork'))
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
-    expect(loaded.meta.isSeeded).toBe(true)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.inheritedEventCount).toBeGreaterThan(0)
     expect(policyEvents(loaded.events)).toMatchObject([
       { type: 'approval/policy', data: { policy: 'never', source: 'delegation' } },
@@ -190,7 +190,7 @@ describe('continuable policy inheritance', () => {
     expect(ctx.sandboxPolicy.overrideOf(child.session)).toBe('read-only')
 
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(foldedSandboxMode(ctx, started.childId, loaded.events)).toBe('read-only')
   })
 
@@ -213,7 +213,7 @@ describe('continuable policy inheritance', () => {
     )
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.events.filter(event => event.type === 'sandbox/mode')).toMatchObject([
       { data: { mode: 'read-only', source: 'delegation' } },
     ])
@@ -238,8 +238,7 @@ describe('continuable policy inheritance', () => {
     const started = await ctx.subagents.startContinuable(startSpec(parent, 'fork'))
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
-    expect(loaded.meta.isSeeded).toBe(true)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.inheritedEventCount).toBeGreaterThan(0)
     expect(loaded.events.filter(event => event.type === 'sandbox/mode')).toMatchObject([
       { data: { mode: 'workspace-write' } },
diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts
index 851720f228..82298d6eaf 100644
--- a/packages/subagent/subagent/tests/continuation.spec.ts
+++ b/packages/subagent/subagent/tests/continuation.spec.ts
@@ -24,6 +24,7 @@ import SubagentRuntime, {
 import type { SubagentRunEndInfo, SubagentRunInfo } from '../src/index.ts'
 import * as SubagentInvariant from '../src/invariant.ts'
 import { TestSessionQuery } from './test-session-query.ts'
+import { loadStoredSession } from './persistence-helpers.ts'
 
 type Script = ConstructorParameters<typeof MockAdapter>[0]
 
@@ -94,7 +95,7 @@ async function setupWith(
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(SubagentFork, { providerName: 'fork' })
   ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent, disposePersistence, root }
 }
 
@@ -219,7 +220,7 @@ describe('SubagentRuntime.startContinuable', () => {
     expect(adapter.requests).toEqual([])
 
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'child task')).toBe(true)
   })
 
@@ -245,7 +246,7 @@ describe('SubagentRuntime.startContinuable', () => {
 
     release.resolve(undefined)
     await waitNoActivation(ctx, reservedId)
-    const loaded = await ctx.sessionPersistence.load(reservedId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, reservedId)
     expect(loaded.meta.id).toBe(reservedId)
 
     await expect(ctx.subagents.startContinuable({
@@ -283,7 +284,7 @@ describe('SubagentRuntime.startContinuable', () => {
     const started = await ctx.subagents.startContinuable(startSpec(parent))
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const descriptorIndex = loaded.events.findIndex(event => event.type === 'subagent/descriptor')
     const turnStartIndex = loaded.events.findIndex(event => event.type === 'turn/start')
     expect(descriptorIndex).toBeGreaterThanOrEqual(0)
@@ -329,7 +330,7 @@ describe('SubagentRuntime.startContinuable', () => {
       },
     })
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.events.find(event => event.type === 'subagent/descriptor')?.data)
       .toMatchObject({ agentReasoningEffort: 'max' })
 
@@ -410,7 +411,7 @@ describe('SubagentRuntime.startContinuable', () => {
     const { ctx } = await setup([])
     // A routeless parent declares no provider/model, and this start declares no
     // persona or tool filter, so the descriptor records only what exists.
-    const routeless = ctx.agentLoop.create(SessionId('routeless'), {})
+    const routeless = await ctx.agentLoop.create(SessionId('routeless'), {})
     const started = await ctx.subagents.startContinuable(startSpec(routeless))
     const child = await vi.waitFor(() => {
       const found = ctx.agents.get(started.childId)
@@ -441,7 +442,7 @@ describe('SubagentRuntime.startContinuable', () => {
       },
       execute: () => Promise.resolve({}),
     }))
-    const routeless = ctx.agentLoop.create(SessionId('routeless-filtered'), {})
+    const routeless = await ctx.agentLoop.create(SessionId('routeless-filtered'), {})
     const started = await ctx.subagents.startContinuable({
       ...startSpec(routeless),
       request: { prompt: message('filtered work'), parent: routeless, toolFilter: { deny: ['noop'] } },
@@ -465,7 +466,7 @@ describe('SubagentRuntime.startContinuable', () => {
 
   it('cold-resumes without inventing a model route the descriptor never declared', async () => {
     const { ctx, root } = await setup([textResponse('first')])
-    const routeless = ctx.agentLoop.create(SessionId('routeless-resume'), {})
+    const routeless = await ctx.agentLoop.create(SessionId('routeless-resume'), {})
     const started = await ctx.subagents.startContinuable(startSpec(routeless))
     await waitNoActivation(ctx, started.childId)
 
@@ -480,7 +481,7 @@ describe('SubagentRuntime.startContinuable', () => {
     await fresh.plugin(TestSessionQuery)
     await fresh.plugin(SubagentRuntime)
     await fresh.plugin(SubagentSpawn, { providerName: 'spawn' })
-    const freshParent = fresh.agentLoop.create(SessionId('routeless-resume'), {})
+    const freshParent = await fresh.agentLoop.create(SessionId('routeless-resume'), {})
     await queuePrompt(fresh, freshParent, started.childId, message('resume routeless'))
 
     const resumed = await vi.waitFor(() => {
@@ -505,7 +506,7 @@ describe('SubagentRuntime.startContinuable', () => {
     const started = await ctx.subagents.startContinuable(startSpec(parent, 'fork'))
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const descriptorIndex = loaded.events.findIndex(event => event.type === 'subagent/descriptor')
     const childTurn = loaded.events.slice(descriptorIndex + 1)
       .find(event => event.type === 'turn/start')
@@ -529,14 +530,14 @@ describe('SubagentRuntime.startContinuable', () => {
     })
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const descriptor = loaded.events.find(event => event.type === 'subagent/descriptor')
     expect(descriptor?.data).toMatchObject({ persona: 'You are scoped.' })
 
     // Cold resume reconstructs the declared composition from that descriptor.
     await queuePrompt(ctx, parent, started.childId, message('resume it'))
     await waitNoActivation(ctx, started.childId)
-    const resumed = await ctx.sessionPersistence.load(started.childId)
+    const resumed = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(resumed.events, 'resume it')).toBe(true)
   })
 })
@@ -563,7 +564,7 @@ describe('continuable image Queue prompts', () => {
       .rejects.toMatchObject({ code: 'MODEL_DOES_NOT_SUPPORT_IMAGES' })
 
     expect(resolve).toHaveBeenCalledWith('mock', 'mock', testSignal)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'see this')).toBe(false)
     await drainManager(ctx)
   })
@@ -589,7 +590,7 @@ describe('continuable image Queue prompts', () => {
     releaseFirst.resolve(undefined)
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const delivered = loaded.events.find(event => event.type === 'user/message'
       && event.data.content.some(block => block.type === 'image'))
     expect(delivered?.type === 'user/message' && delivered.data.content).toEqual([
@@ -634,14 +635,14 @@ describe('continuable image Queue prompts', () => {
 
     await expect(delivery).rejects.toMatchObject({ code: 'ACTIVATION_CLOSING' })
     await draining
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.events.some(event => event.type === 'user/message'
       && event.data.content.some(block => block.type === 'image'))).toBe(false)
   })
 
   it('defers to the text-only projection when the descriptor declares no model route', async () => {
     const { ctx } = await setup([])
-    const routeless = ctx.agentLoop.create(SessionId('routeless-image'), {})
+    const routeless = await ctx.agentLoop.create(SessionId('routeless-image'), {})
     const started = await ctx.subagents.startContinuable(startSpec(routeless))
     await waitNoActivation(ctx, started.childId)
     const resolve = vi.spyOn(ctx.llm, 'resolveModelInfo')
@@ -688,7 +689,7 @@ describe('direct-child Queue residency routing', () => {
 
     releaseFirst.resolve(undefined)
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(userTexts(loaded.events)).toEqual(['child task', 'first follow-up', 'second follow-up'])
   })
 
@@ -701,7 +702,7 @@ describe('direct-child Queue residency routing', () => {
     expect(messageId).toBeTypeOf('string')
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(userTexts(loaded.events)).toEqual(['child task', 'continue please'])
     // One descriptor only: cold resume never re-seeds it.
     expect(loaded.events.filter(event => event.type === 'subagent/descriptor')).toHaveLength(1)
@@ -735,7 +736,7 @@ describe('direct-child Queue residency routing', () => {
 
     expect(starts.map(info => info.provider)).toEqual(['retired', 'retired'])
     expect(ends.map(info => info.runId)).toEqual(starts.map(info => info.runId))
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(userTexts(loaded.events)).toEqual(['child task', 'continue without provider'])
   })
 
@@ -771,18 +772,49 @@ describe('direct-child Queue residency routing', () => {
     releaseGrandchild.resolve(undefined)
     await waitNoActivation(ctx, grandchild.childId)
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     // This child is itself a parent, so its grandchild's settlement notice is
     // an ordinary later user message in its log.
     expect(userTexts(loaded.events).slice(0, 2)).toEqual(['child task', 'while waiting'])
     expect(userTexts(loaded.events).slice(2).join('\n')).toContain('finished and will do no further work')
   })
 
+  it('holds one ownership edge per child: a followup under an existing hold is a no-op re-hold', async () => {
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child done') },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+      { chunks: textResponse('extra delivery') },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    const child = await vi.waitFor(() => {
+      const found = ctx.agents.get(started.childId)
+      expect(found).toBeDefined()
+      return found!
+    })
+    // startContinuable held the child→grandchild ownership edge; a followup
+    // from the same managed parent to the same child re-holds it as a no-op,
+    // and its failure-path release must not drop the established edge.
+    const grandchild = await ctx.subagents.startContinuable(startSpec(child))
+    const aborted = AbortSignal.abort(new Error('followup abandoned'))
+    await expect(queuePrompt(ctx, child, grandchild.childId, message('while owned'), aborted))
+      .rejects.toThrow('followup abandoned')
+    // The edge survives the released duplicate hold: the grandchild delivery
+    // still completes and settles normally.
+    await expect(queuePrompt(ctx, child, grandchild.childId, message('after release')))
+      .resolves.toBeTypeOf('string')
+
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+  })
+
   it('rejects a parent that is not the durable direct parent', async () => {
     const { ctx, parent } = await setup([textResponse('first')])
     const started = await ctx.subagents.startContinuable(startSpec(parent))
     await waitNoActivation(ctx, started.childId)
-    const stranger = ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
+    const stranger = await ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
 
     await expect(queuePrompt(ctx, stranger, started.childId, message('mine now')))
       .rejects.toThrow(/belongs to another parent session/)
@@ -822,8 +854,9 @@ describe('direct-child Queue residency routing', () => {
     const started = await ctx.subagents.startContinuable(startSpec(parent))
     await waitNoActivation(ctx, started.childId)
     const inspectStarted = Promise.withResolvers<undefined>()
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession').mockImplementation((_id, signal) => {
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'open').mockImplementation((_id, _access, options) => {
       return new Promise<never>((_resolve, reject) => {
+        const signal = options?.signal
         if (signal === undefined) {
           reject(new Error('cold inspection must receive the followup signal'))
           return
@@ -874,7 +907,7 @@ describe('direct-child Queue residency routing', () => {
 
     await expect(delivery).resolves.toBeTypeOf('string')
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'raced')).toBe(true)
   })
 })
@@ -918,7 +951,7 @@ describe('continuable child ownership', () => {
 })
 
 describe('continuable durability and teardown', () => {
-  it('settles when the best-effort final flush has no listeners', async () => {
+  it('settles despite the persistence backend being disposed mid-run', async () => {
     const releaseResponse = Promise.withResolvers<undefined>()
     const adapter = new GatedAdapter([
       { chunks: textResponse('unconfirmed answer'), gate: releaseResponse.promise },
@@ -929,12 +962,15 @@ describe('continuable durability and teardown', () => {
 
     const started = await ctx.subagents.startContinuable(startSpec(parent))
     await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
-    // Remove every persistence listener; the final flush is advisory.
+    // Tear down the whole backend under the child's open write path: its
+    // teardown closes the handle (draining what was buffered) and detaches
+    // the durability listeners, so the final flush finds no participant and
+    // never pins the Activation.
     await disposePersistence!()
     releaseResponse.resolve(undefined)
 
     await waitNoActivation(ctx, started.childId)
-    expect(warnings.some(warning => warning.includes('final session flush'))).toBe(false)
+    expect(warnings.join('\n')).not.toContain('final session flush')
   })
 
   it('logs a failed final flush after every listener settles without failing the Activation', async () => {
@@ -1013,7 +1049,7 @@ describe('continuable durability and teardown', () => {
     expect(disposals.indexOf(grandchild.childId))
       .toBeLessThan(disposals.indexOf(started.childId))
     // Durable sessions survive process-local teardown.
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.meta.id).toBe(started.childId)
   })
 
@@ -1028,7 +1064,7 @@ describe('continuable durability and teardown', () => {
       { chunks: textResponse('sibling follow-up') },
     ])
     const { ctx, parent } = await setupWith(adapter)
-    const siblingParent = ctx.agentLoop.create(
+    const siblingParent = await ctx.agentLoop.create(
       SessionId('sibling-parent'),
       { provider: 'mock', model: 'mock' },
     )
@@ -1126,7 +1162,11 @@ describe('continuable durability and teardown', () => {
     await vi.waitFor(() => { expect(adapter.requests).toHaveLength(3) })
     const cancel = vi.spyOn(targetAgent, 'cancel')
 
-    const drained = ctx.subagents.drainContinuableChildren(parent, [target.childId, target.childId])
+    // A repeated id folds to one teardown and an absent target is an accepted no-op.
+    const drained = ctx.subagents.drainContinuableChildren(
+      parent,
+      [target.childId, target.childId, SessionId('never-materialized')],
+    )
 
     expect(cancel).toHaveBeenCalledWith({ kind: 'parent' })
     expect(ctx.agents.get(sibling.childId)).toBe(siblingAgent)
@@ -1174,7 +1214,7 @@ describe('continuable durability and teardown', () => {
     const release = Promise.withResolvers<undefined>()
     const adapter = new GatedAdapter([{ chunks: textResponse('target'), gate: release.promise }])
     const { ctx, parent } = await setupWith(adapter)
-    const other = ctx.agentLoop.create(SessionId('other-parent'), { provider: 'mock', model: 'mock' })
+    const other = await ctx.agentLoop.create(SessionId('other-parent'), { provider: 'mock', model: 'mock' })
     const target = await ctx.subagents.startContinuable(startSpec(parent))
     await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
 
@@ -1394,7 +1434,7 @@ describe('continuable durability and teardown', () => {
     await drained
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     // Only what actually reached the log is reconstructable.
     expect(hasUserText(loaded.events, 'never logged')).toBe(false)
   })
@@ -1433,8 +1473,12 @@ describe('continuable review regressions', () => {
     )
     await resumed.promise
     await originalParent.dispose()
-    const replacement = await ctx.agents.create({
-      sessionId: parentId,
+    // The durable store still holds the parent, so a same-id replacement is a
+    // resume of the persisted session — a distinct exact Agent identity.
+    // Called through the unmocked bound original: the spy above must keep
+    // gating only the child's in-flight cold resume.
+    const replacement = await originalResume({
+      resumeSessionId: parentId,
       agentOptions: { provider: 'mock', model: 'mock' },
     })
     releaseResume.resolve(undefined)
@@ -1442,7 +1486,7 @@ describe('continuable review regressions', () => {
     await expect(delivery).rejects.toMatchObject({ code: 'UNAUTHORIZED' })
     resumeSpy.mockRestore()
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'must not cross parent replacement')).toBe(false)
     await replacement.dispose()
   })
@@ -1511,7 +1555,7 @@ describe('continuable review regressions', () => {
     // Nothing was enqueued, so no later turn can carry it.
     releaseFirst.resolve(undefined)
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'cancelled')).toBe(false)
     expect(before).toBeGreaterThan(0)
   })
@@ -1718,7 +1762,7 @@ describe('continuable review regressions', () => {
     await drained
 
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'discarded')).toBe(false)
   })
 
@@ -1744,7 +1788,7 @@ describe('continuable review regressions', () => {
     // Retaining the discarded id would pin residency at `running` forever, so
     // reaching no-Activation without an explicit drain is the assertion.
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'doomed')).toBe(false)
   })
 
@@ -1827,7 +1871,7 @@ describe('continuable review regressions', () => {
     // Two child turns; the third request is the parent's own turn on the
     // settlement notice.
     expect(adapter.requests.filter(request => request.sessionId === started.childId)).toHaveLength(2)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'queued')).toBe(true)
   })
 })
@@ -2058,7 +2102,7 @@ describe('continuable settlement delivery', () => {
     await vi.waitFor(() => { expect(settlementNotices(parent)).toHaveLength(1) })
     // The parent must not be told the child finished: the delivery it is still
     // waiting on was claimed out of the inbox and then swallowed by the failure.
-    const child = await ctx.sessionPersistence.load(started.childId)
+    const child = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(child.events, 'second task')).toBe(false)
     expect(settlementNotices(parent)[0]!.text).toBe(
       `Background subagent ${started.childId} failed before it finished.`
@@ -2416,7 +2460,7 @@ describe('continuable settlement delivery', () => {
     expect(settlementNotices(resumed.agent)).toEqual([])
     await resumed.dispose()
     // The account is still in the durable log: delivered, then cancelled unread.
-    const persisted = await ctx.sessionPersistence.load(parentId)
+    const persisted = await loadStoredSession(ctx.sessionPersistence, parentId)
     expect(persisted.events.flatMap(event => event.type === 'agent/inbox/spliced'
       ? [{ inserted: event.data.inserted.length, removed: event.data.removedCount ?? 0 }]
       : [])).toEqual([{ inserted: 1, removed: 0 }, { inserted: 0, removed: 1 }])
@@ -2545,7 +2589,7 @@ describe('continuable public API', () => {
     await expect(queuePrompt(ctx, parent, started.childId, message('aborted'), controller.signal))
       .rejects.toThrow()
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'aborted')).toBe(false)
   })
 
@@ -2566,7 +2610,7 @@ describe('continuable public API', () => {
 
     releaseFirst.resolve(undefined)
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(hasUserText(loaded.events, 'survives')).toBe(true)
   })
 })
@@ -2662,11 +2706,11 @@ describe('continuable errors', () => {
     await expect(drained).rejects.toMatchObject({ code: 'ACTIVATION_TEARDOWN_FAILED' })
     // The other branch still released, and durable sessions survive.
     expect(ctx.agents.get(started.childId)).toBeUndefined()
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.meta.id).toBe(started.childId)
   })
 
-  it('rolls the transfer back when ownership registration fails after handle transfer', async () => {
+  it('rejects a new child at admission when the parent disposal transaction is already open', async () => {
     const hold = Promise.withResolvers<undefined>()
     const adapter = new GatedAdapter([
       { chunks: textResponse('parent child'), gate: hold.promise },
@@ -2679,9 +2723,8 @@ describe('continuable errors', () => {
       expect(found).toBeDefined()
       return found!
     })
-    // Begin the would-be parent's disposal, then race a grandchild into it. The
-    // handle transfers before ownership registration rejects, so the rollback
-    // must leave no Activation and no live Agent behind.
+    // The would-be parent's disposal is already open at the entry hold, so the
+    // establishment rejects before any grandchild resource exists.
     const manager = (ctx.subagents as unknown as {
       continuations: { activations: Map<SessionId, { disposal: Promise<void> | undefined }> }
     }).continuations
@@ -2696,6 +2739,95 @@ describe('continuable errors', () => {
     hold.resolve(undefined)
   })
 
+  it('rolls the transfer back when the parent begins disposal during materialization', async () => {
+    const hold = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('parent child'), gate: hold.promise },
+      { chunks: textResponse('unused') },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const outer = await ctx.subagents.startContinuable(startSpec(parent))
+    const child = await vi.waitFor(() => {
+      const found = ctx.agents.get(outer.childId)
+      expect(found).toBeDefined()
+      return found!
+    })
+    const manager = (ctx.subagents as unknown as {
+      continuations: {
+        activations: Map<SessionId, { disposal: Promise<void> | undefined }>
+        ownerCtx: Context
+      }
+    }).continuations
+    const ownerAgents = manager.ownerCtx.agents
+    const before = new Set(ctx.agents.list().map(agent => agent.id))
+    // Open the would-be parent's disposal only once the grandchild's Agent is
+    // being created: the entry hold has already passed, so the post-transfer
+    // ownership registration must reject and roll the transfer back with no
+    // Activation and no live Agent left behind.
+    const originalCreate = ownerAgents.create.bind(ownerAgents)
+    const createSpy = vi.spyOn(ownerAgents, 'create').mockImplementation((options) => {
+      manager.activations.get(outer.childId)!.disposal = Promise.resolve()
+      createSpy.mockRestore()
+      return originalCreate(options)
+    })
+
+    await expect(ctx.subagents.startContinuable(startSpec(child)))
+      .rejects.toMatchObject({ code: 'ACTIVATION_CLOSING' })
+    await vi.waitFor(() => {
+      expect(ctx.agents.list().map(agent => agent.id).filter(id => !before.has(id))).toEqual([])
+    })
+    hold.resolve(undefined)
+  })
+
+  it('releases the parent hold when a cold delivery fails, so the parent can settle', async () => {
+    const release = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child done'), gate: release.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    const child = await vi.waitFor(() => {
+      const found = ctx.agents.get(started.childId)
+      expect(found).toBeDefined()
+      return found!
+    })
+
+    // The failed delivery to a missing child must give back the hold it put on
+    // the delivering parent; a leaked hold would pin the parent in `waiting`.
+    await expect(queuePrompt(ctx, child, SessionId('no-such-child'), message('hello')))
+      .rejects.toMatchObject({ code: 'NOT_RESUMABLE' })
+
+    release.resolve(undefined)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('follows up on an already-owned running grandchild without a duplicate hold', async () => {
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child done') },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+      { chunks: textResponse('follow-up answer') },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    const child = await vi.waitFor(() => {
+      const found = ctx.agents.get(started.childId)
+      expect(found).toBeDefined()
+      return found!
+    })
+    const grandchild = await ctx.subagents.startContinuable(startSpec(child))
+    await vi.waitFor(() => { expect(adapter.requests.length).toBeGreaterThanOrEqual(2) })
+
+    // The delivering parent already owns this running child, so the entry hold
+    // is a no-op and the delivery is accepted as ordinary inbox work.
+    const accepted = await queuePrompt(ctx, child, grandchild.childId, message('one more'))
+    expect(accepted).toBeTypeOf('string')
+
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+  })
+
   it('reapplies the descriptor model route and reasoning effort on cold resume', async () => {
     const effort = ReasoningEffortId('high')
     const adapter = new MockAdapter([textResponse('first'), textResponse('resumed')], {
@@ -2712,7 +2844,7 @@ describe('continuable errors', () => {
       },
     })
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.events.find(event => event.type === 'subagent/descriptor')?.data)
       .toMatchObject({
         agentProvider: 'mock',
@@ -2729,7 +2861,7 @@ describe('continuable errors', () => {
       })
     })
     await waitNoActivation(ctx, started.childId)
-    const resumed = await ctx.sessionPersistence.load(started.childId)
+    const resumed = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(resumed.events.flatMap(event => event.type === 'request/header'
       ? [event.data.header.config.reasoningEffort]
       : [])).toEqual([effort, effort])
@@ -2751,7 +2883,7 @@ describe('continuable errors', () => {
     const serviceFiber = await ctx.plugin(SubagentRuntime)
     await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
     ctx.llm.registerAdapter(['mock'], adapter)
-    const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+    const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
     const started = await ctx.subagents.startContinuable(startSpec(parent))
     await vi.waitFor(() => { expect(ctx.agents.get(started.childId)).toBeDefined() })
 
@@ -2798,7 +2930,7 @@ describe('SubagentRuntime.interrupt', () => {
     // run before it in the existing FIFO order.
     await queuePrompt(ctx, parent, started.childId, message('waking D'))
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(userTexts(loaded.events)).toEqual(['child task', 'parked B', 'parked C', 'waking D'])
     const turnEnds = loaded.events
       .filter(event => event.type === 'turn/end')
@@ -2837,7 +2969,7 @@ describe('SubagentRuntime.interrupt', () => {
     releaseGrandchild.resolve(undefined)
     await waitNoActivation(ctx, grandchild.childId)
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(grandchild.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, grandchild.childId)
     const turnEnds = loaded.events
       .filter(event => event.type === 'turn/end')
       .map(event => (event).data.reason.kind)
@@ -2909,7 +3041,7 @@ describe('SubagentRuntime.interrupt', () => {
     const siblingStart = await ctx.subagents.startContinuable(startSpec(parent))
     await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
     const sibling = ctx.agents.get(siblingStart.childId)!
-    const stranger = ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
+    const stranger = await ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
     const stale = { ...parent, id: parent.id } as unknown as Agent
     const cancelSpy = vi.spyOn(target, 'cancel')
 
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index 54d34f8c95..9c5c7c1e4e 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -6,8 +6,9 @@ import { z } from 'zod'
 import { Context } from '@deepseek-ai/cordis'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionLogOffset, SessionSeq, SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import type { SessionObservation } from '@deepseek-ai/dsh-session-query'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
@@ -29,6 +30,7 @@ import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
 import * as SubagentFork from '@deepseek-ai/dsh-subagent-fork-in-process'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import { TestSessionQuery } from './test-session-query.ts'
+import { seedStoredSession } from './persistence-helpers.ts'
 
 type Script = ConstructorParameters<typeof MockAdapter>[0]
 
@@ -71,9 +73,9 @@ async function setup(
   const parent = loop === undefined
     ? (() => {
       const session = ctx.sessions.create(SessionId('parent'))
-      return { id: session.id, session } as ReturnType<Context['agentLoop']['create']>
+      return { id: session.id, session } as Awaited<ReturnType<Context['agentLoop']['create']>>
     })()
-    : loop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+    : await loop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent }
 }
 
@@ -82,7 +84,7 @@ const testSignal = new AbortController().signal
 /** Start one continuable child through the real service path and await Activation release. */
 async function startChild(
   ctx: Context,
-  parent: ReturnType<Context['agentLoop']['create']>,
+  parent: Agent,
   label: string,
 ): Promise<SessionId> {
   const started = await ctx.subagents.startContinuable({
@@ -103,33 +105,60 @@ async function authorChild(
   id: string,
   header: Partial<SessionHeader>,
   events: SessionEvent[],
-  inheritedEventCount = SessionLogOffset(0),
+  inheritedEventCount?: number,
 ): Promise<SessionId> {
   const sessionId = SessionId(id)
-  await ctx.sessionPersistence.create({
+  await seedStoredSession(ctx.sessionPersistence, {
     version: SESSION_FORMAT_VERSION,
     id: sessionId,
     createdAt: 1,
-    isSeeded: false,
+    isSeeded: inheritedEventCount !== undefined,
     ...header,
-  }, header.isSeeded === true ? inheritedEventCount : undefined)
-  await ctx.sessionPersistence.append(sessionId, events)
+  }, events, inheritedEventCount === undefined ? undefined : SessionLogOffset(inheritedEventCount))
   return sessionId
 }
 
+/**
+ * Serve one cold session's point read (the open handle) with a transformed
+ * header while the enumeration listing keeps reporting the stored original —
+ * the re-published-lifecycle shape the sameLifecycle check exists for.
+ */
+function mutateStoredHeader(
+  ctx: Context,
+  target: SessionId,
+  mutate: (meta: SessionHeader) => SessionHeader,
+): void {
+  const originalOpen = ctx.sessionPersistence.open.bind(ctx.sessionPersistence)
+  ctx.sessionPersistence.open = async (sessionId, access, options) => {
+    const handle = await originalOpen(sessionId, access, options)
+    if (sessionId !== target) return handle
+    return {
+      id: handle.id,
+      access: handle.access,
+      header: mutate(handle.header),
+      inheritedEventCount: handle.inheritedEventCount,
+      read: (offset, length, readOptions) => handle.read(offset, length, readOptions),
+      append: (events, appendOptions) => handle.append(events, appendOptions),
+      flush: flushOptions => handle.flush(flushOptions),
+      close: () => handle.close(),
+      [Symbol.asyncDispose]: () => handle[Symbol.asyncDispose](),
+    }
+  }
+}
+
 /** Minimal complete-turn child log with one descriptor payload. */
 function childEvents(descriptor: unknown): SessionEvent[] {
   return [
-    { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
     {
       type: 'user/message',
-      seq: 1,
+      seq: SessionSeq(1),
       time: 2,
       data: createUserMessage({ content: [{ type: 'text', text: 'work' }], source: { kind: 'user' } }),
       surfaceOp: 'append',
     },
-    { type: 'subagent/descriptor', seq: 2, time: 3, data: descriptor },
-    { type: 'turn/end', seq: 3, time: 4, data: { turn: 1, reason: { kind: 'completed' } } },
+    { type: 'subagent/descriptor', seq: SessionSeq(2), time: 3, data: descriptor },
+    { type: 'turn/end', seq: SessionSeq(3), time: 4, data: { turn: 1, reason: { kind: 'completed' } } },
   ] as SessionEvent[]
 }
 
@@ -275,15 +304,14 @@ describe('SubagentRuntime.listChildren', () => {
     const { ctx } = await setup([])
     // A parent that exists only in persistence — the restart shape.
     const coldParent = SessionId('00000000-0000-4000-8000-00000000cccc')
-    await ctx.sessionPersistence.create({
+    await seedStoredSession(ctx.sessionPersistence, {
       version: SESSION_FORMAT_VERSION,
       id: coldParent,
       createdAt: 1,
       isSeeded: false,
-    })
-    await ctx.sessionPersistence.append(coldParent, [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
-      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    }, [
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
     ] as SessionEvent[])
     const childId = await authorChild(ctx, '00000000-0000-4000-8000-00000000cdcd', {
       parentSession: coldParent,
@@ -482,7 +510,7 @@ describe('SubagentRuntime.listChildren', () => {
     live.append('turn/start', { turn: 1 })
     live.append('subagent/descriptor', descriptorPayload('was valid'))
     expect(ctx.sessionProjections.snapshot(live).values.subagent)
-      .toEqual({ mode: 'continuable', label: 'was valid', seq: 1 })
+      .toEqual({ mode: 'continuable', label: 'was valid', seq: SessionSeq(1) })
     // Last-wins: the malformed follow-up resets the identity to the sentinel.
     live.append(
       'subagent/descriptor',
@@ -524,14 +552,14 @@ describe('SubagentRuntime.listChildren', () => {
       parentSession: parent.id,
       origin: 'subagent',
     }, childEvents(descriptorPayload('disk label')))
-    // The unseeded child's cut is exactly 0, so its cached identity is final
-    // and the log is never re-read — the
+    // seq 2 >= seedLength 0: the cached identity provably comes from the
+    // child's own suffix, so it is final and the log is never re-read — the
     // divergent label proves the row, not the log, produced the entry.
     ctx.sessionProjectionCache.cachedSnapshot = () => ({
       asOfSeq: SessionSeq(2),
       values: { subagent: { mode: 'continuable', label: 'cached own', seq: SessionSeq(2) } },
     })
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'open')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
       kind: 'child', id: child, label: 'cached own', mode: 'continuable',
       activity: 'inactive', hasChildren: false,
@@ -546,22 +574,21 @@ describe('SubagentRuntime.listChildren', () => {
     const seed = childEvents(descriptorPayload('ancestor label'))
     const events = [
       ...seed,
-      { type: 'turn/start', seq: 4, time: 5, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
-      { type: 'subagent/descriptor', seq: 5, time: 6, data: descriptorPayload('own label') },
-      { type: 'turn/end', seq: 6, time: 7, data: { turn: 2, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(4), time: 5, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'subagent/descriptor', seq: SessionSeq(5), time: 6, data: descriptorPayload('own label') },
+      { type: 'turn/end', seq: SessionSeq(6), time: 7, data: { turn: 2, reason: { kind: 'completed' } } },
     ] as SessionEvent[]
     const forkChild = await authorChild(ctx, '00000000-0000-4000-8000-00000000ae02', {
       parentSession: parent.id,
-      isSeeded: true,
       origin: 'subagent',
-    }, events, SessionLogOffset(seed.length))
-    // A seeded header does not expose the integer cut, so a misleading cached
-    // ANCESTOR identity is bypassed and authoritative preparation rules.
+    }, events, seed.length)
+    // A creation-window checkpoint carried the ANCESTOR identity: its seq 2
+    // fails the own-suffix gate (< seedLength 4), so preparation rules.
     ctx.sessionProjectionCache.cachedSnapshot = () => ({
       asOfSeq: SessionSeq(2),
       values: { subagent: { mode: 'continuable', label: 'ancestor label', seq: SessionSeq(2) } },
     })
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'open')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
       kind: 'child', id: forkChild, label: 'own label', mode: 'continuable',
       activity: 'inactive', hasChildren: false,
@@ -584,13 +611,8 @@ describe('SubagentRuntime.listChildren', () => {
       parentSession: parent.id,
       origin: 'subagent',
     }, childEvents(descriptorPayload('reborn child')))
-    const original = ctx.sessionPersistence.borrowSession.bind(ctx.sessionPersistence)
-    ctx.sessionPersistence.borrowSession = async (sessionId, signal) => {
-      const result = await original(sessionId, signal)
-      if (sessionId !== reborn) return result
-      // The id was re-published as a different lifecycle after enumeration.
-      return { ...result, inspection: { ...result.inspection, meta: mutate(result.inspection.meta) } }
-    }
+    // The id was re-published as a different lifecycle after enumeration.
+    mutateStoredHeader(ctx, reborn, mutate)
     const entries = await ctx.subagents.listChildren(parent.id)
     expect(entries).toContainEqual({ kind: 'diagnostic', id: reborn, reason: 'corrupt' })
     expect(entries).toContainEqual({
@@ -607,7 +629,7 @@ describe('SubagentRuntime.listChildren', () => {
     }, childEvents(descriptorPayload('actually valid')))
     // A stale cached sentinel must not out-rank the authoritative re-fold.
     ctx.sessionProjectionCache.cachedSnapshot = () => ({ asOfSeq: SessionSeq(0), values: { subagent: null } })
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'open')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
       kind: 'child', id: healthy, label: 'actually valid', mode: 'continuable',
       activity: 'inactive', hasChildren: false,
@@ -623,14 +645,14 @@ describe('SubagentRuntime.listChildren', () => {
       parentSession: parent.id,
       origin: 'subagent',
     }, [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
       {
         type: 'user/message',
-        seq: 1,
+        seq: SessionSeq(1),
         time: 2,
         data: createUserMessage({ content: [{ type: 'text', text: 'work' }], source: { kind: 'user' } }),
       },
-      { type: 'subagent/descriptor', seq: 2, time: 3, data: descriptorPayload('broken surface') },
+      { type: 'subagent/descriptor', seq: SessionSeq(2), time: 3, data: descriptorPayload('broken surface') },
     ] as SessionEvent[])
     const entries = await ctx.subagents.listChildren(parent.id)
     expect(entries).toEqual([{ kind: 'diagnostic', id: invalid, reason: 'corrupt' }])
@@ -666,9 +688,8 @@ describe('SubagentRuntime.listChildren', () => {
     const seed = childEvents(descriptorPayload('ancestor label'))
     const forkChild = await authorChild(ctx, '00000000-0000-4000-8000-0000000000f0', {
       parentSession: parent.id,
-      isSeeded: true,
       origin: 'subagent',
-    }, seed, SessionLogOffset(seed.length))
+    }, seed, seed.length)
     const entries = await ctx.subagents.listChildren(parent.id)
     expect(entries).toEqual([{ kind: 'diagnostic', id: forkChild, reason: 'corrupt' }])
   })
@@ -753,12 +774,12 @@ describe('SubagentRuntime.listChildren', () => {
       parentSession: parent.id,
       origin: 'subagent',
     }, childEvents(descriptorPayload('flaky storage')))
-    const original = ctx.sessionPersistence.borrowSession.bind(ctx.sessionPersistence)
-    ctx.sessionPersistence.borrowSession = (sessionId, signal) => {
+    const original = ctx.sessionPersistence.open.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.open = (sessionId, access, options) => {
       if (sessionId === flaky) {
         return Promise.reject(new Error('backend read failed'))
       }
-      return original(sessionId, signal)
+      return original(sessionId, access, options)
     }
     // Per-child isolation: the failed child degrades to one diagnostic while
     // the healthy sibling stays complete.
@@ -770,7 +791,7 @@ describe('SubagentRuntime.listChildren', () => {
     })
     // Nothing is memoized: with the backend healthy again, the next listing
     // folds the same child to its identity.
-    ctx.sessionPersistence.borrowSession = original
+    ctx.sessionPersistence.open = original
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toContainEqual({
       kind: 'child', id: flaky, label: 'flaky storage', mode: 'continuable',
       activity: 'inactive', hasChildren: false,
@@ -824,10 +845,10 @@ describe('SubagentRuntime.listChildren', () => {
       origin: 'subagent',
     }, childEvents(descriptorPayload('grandchild')))
     const inspected: SessionId[] = []
-    const original = ctx.sessionPersistence.borrowSession.bind(ctx.sessionPersistence)
-    ctx.sessionPersistence.borrowSession = (sessionId, signal) => {
+    const original = ctx.sessionPersistence.open.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.open = (sessionId, access, options) => {
       inspected.push(sessionId)
-      return original(sessionId, signal)
+      return original(sessionId, access, options)
     }
     const entries = await ctx.subagents.listChildren(parent.id)
     expect(entries).toEqual([
@@ -856,10 +877,10 @@ describe('SubagentRuntime.listChildren', () => {
     live.append('subagent/descriptor', descriptorPayload('live mixed child'))
 
     const inspected: SessionId[] = []
-    const original = ctx.sessionPersistence.borrowSession.bind(ctx.sessionPersistence)
-    ctx.sessionPersistence.borrowSession = (sessionId, signal) => {
+    const original = ctx.sessionPersistence.open.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.open = (sessionId, access, options) => {
       inspected.push(sessionId)
-      return original(sessionId, signal)
+      return original(sessionId, access, options)
     }
     const entries = await ctx.subagents.listChildren(parent.id)
     expect(entries).toHaveLength(3)
@@ -875,11 +896,11 @@ describe('SubagentRuntime.listChildren', () => {
     const childId = await startChild(ctx, parent, 'cached child')
     // The child's turn/end and disposal are the cache's mandatory checkpoint
     // points; both writes are fail-soft asynchronous, so wait for the row.
-    const header = (await ctx.sessionPersistence.list()).find(meta => meta.id === childId)
+    const header = (await ctx.sessionPersistence.list()).find(snapshot => snapshot.header.id === childId)?.header
     await vi.waitFor(() => {
       expect(ctx.sessionProjectionCache.cachedSnapshot(header!, SessionLogOffset(0))?.values.subagent).toBeDefined()
     }, { timeout: 5_000 })
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'open')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
       kind: 'child', id: childId, label: 'cached child', mode: 'continuable',
       activity: 'inactive', hasChildren: false,
@@ -898,7 +919,7 @@ describe('SubagentRuntime.listChildren', () => {
       activity: 'inactive', hasChildren: false,
     }]
     // No stored row at all for a foreign child this process never ran.
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'open')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual(expected)
     expect(inspect).toHaveBeenCalledTimes(1)
     // A stored row whose cut predates the descriptor: the subagent key is
@@ -915,7 +936,7 @@ describe('SubagentRuntime.listChildren', () => {
       parentSession: parent.id,
       origin: 'subagent',
     }, childEvents(descriptorPayload('uncacheable child')))
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'open')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
       kind: 'child', id: foreign, label: 'uncacheable child', mode: 'continuable',
       activity: 'inactive', hasChildren: false,
@@ -934,7 +955,7 @@ describe('SubagentRuntime.listChildren', () => {
       // is derived data, so its failure must not become a verdict.
       throw new Error('poisoned cache row')
     }
-    const inspect = vi.spyOn(ctx.sessionPersistence, 'borrowSession')
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'open')
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
       kind: 'child', id: recovered, label: 'recovered child', mode: 'continuable',
       activity: 'inactive', hasChildren: false,
@@ -948,8 +969,8 @@ describe('SubagentRuntime.listChildren', () => {
     await authorChild(ctx, '00000000-0000-4000-8000-0000000000f1', {
       parentSession: childId,
     }, [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
-      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
     ] as SessionEvent[])
 
     await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
@@ -989,10 +1010,10 @@ describe('SubagentRuntime.listChildren', () => {
     const { ctx, parent } = await setup([])
     const controller = new AbortController()
     const entered = Promise.withResolvers<undefined>()
-    ctx.sessionPersistence.list = (signal) => {
+    ctx.sessionPersistence.list = (options) => {
       entered.resolve(undefined)
       return new Promise((_resolve, reject) => {
-        signal?.addEventListener('abort', () => {
+        options?.signal?.addEventListener('abort', () => {
           reject(new Error('backend listing aborted'))
         }, { once: true })
       })
@@ -1013,10 +1034,10 @@ describe('SubagentRuntime.listChildren', () => {
     }, childEvents(descriptorPayload('cancelled cold read')))
     const controller = new AbortController()
     const entered = Promise.withResolvers<undefined>()
-    ctx.sessionPersistence.borrowSession = (_sessionId, signal) => {
+    ctx.sessionPersistence.open = (_sessionId, _access, options) => {
       entered.resolve(undefined)
       return new Promise((_resolve, reject) => {
-        signal?.addEventListener('abort', () => {
+        options?.signal?.addEventListener('abort', () => {
           reject(new Error('backend read aborted'))
         }, { once: true })
       })
@@ -1036,9 +1057,9 @@ describe('SubagentRuntime.listChildren', () => {
       origin: 'subagent',
     }, childEvents(descriptorPayload('cancelled mid-listing')))
     const controller = new AbortController()
-    const original = ctx.sessionPersistence.borrowSession.bind(ctx.sessionPersistence)
-    ctx.sessionPersistence.borrowSession = async (sessionId, signal) => {
-      const result = await original(sessionId, signal)
+    const original = ctx.sessionPersistence.open.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.open = async (sessionId, access, options) => {
+      const result = await original(sessionId, access, options)
       controller.abort()
       return result
     }
@@ -1055,7 +1076,7 @@ describe('SubagentRuntime.listChildren', () => {
       origin: 'subagent',
     }, childEvents(descriptorPayload('aborted behind a failure')))
     const controller = new AbortController()
-    ctx.sessionPersistence.borrowSession = () => {
+    ctx.sessionPersistence.open = () => {
       // The read fails while the caller aborts: cancellation normalization
       // must fail the listing rather than return a one-diagnostic success.
       controller.abort()
@@ -1241,8 +1262,8 @@ describe('SubagentRuntime.listDescendants', () => {
       createdAt: 1,
       origin: 'subagent',
     }, [
-      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
-      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+      { type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'turn/end', seq: SessionSeq(1), time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
     ] as SessionEvent[])
     const below = await authorChild(ctx, '00000000-0000-4000-8000-00000000eee2', {
       parentSession: bare,
@@ -1289,18 +1310,8 @@ describe('SubagentRuntime.listDescendants', () => {
       createdAt: 1,
       origin: 'subagent',
     }, childEvents(descriptorPayload('lineage checked')))
-    const realInspect = ctx.sessionPersistence.borrowSession.bind(ctx.sessionPersistence)
-    ctx.sessionPersistence.borrowSession = async (sessionId, signal) => {
-      const inspected = await realInspect(sessionId, signal)
-      // The exact read reports a different durable parent than enumeration did.
-      return {
-        ...inspected,
-        inspection: {
-          ...inspected.inspection,
-          meta: { ...inspected.inspection.meta, parentSession: SessionId('someone-else') },
-        },
-      }
-    }
+    // The exact read reports a different durable parent than enumeration did.
+    mutateStoredHeader(ctx, childId, meta => ({ ...meta, parentSession: SessionId('someone-else') }))
     await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([
       { kind: 'diagnostic', id: childId, reason: 'corrupt', parentId: parent.id, depth: 1 },
     ])
diff --git a/packages/subagent/subagent/tests/persistence-helpers.ts b/packages/subagent/subagent/tests/persistence-helpers.ts
new file mode 100644
index 0000000000..a23eede5a1
--- /dev/null
+++ b/packages/subagent/subagent/tests/persistence-helpers.ts
@@ -0,0 +1,33 @@
+/** Handle-based session-persistence helpers shared by the subagent test suites. */
+
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+
+/** Read one stored session's header and complete event log through a read handle. */
+export async function loadStoredSession(
+  persistence: SessionPersistence,
+  id: SessionId,
+): Promise<{ meta: SessionHeader; inheritedEventCount: SessionLogOffset; events: readonly SessionEvent[] }> {
+  const handle = await persistence.open(id, 'read')
+  try {
+    return { meta: handle.header, inheritedEventCount: handle.inheritedEventCount, events: await handle.read() }
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Author one stored session directly against the backend: create, append, flush, close. */
+export async function seedStoredSession(
+  persistence: SessionPersistence,
+  header: SessionHeader,
+  events: readonly SessionEvent[],
+  inheritedEventCount?: SessionLogOffset,
+): Promise<void> {
+  const handle = await persistence.create(header, inheritedEventCount === undefined ? {} : { inheritedEventCount })
+  try {
+    if (events.length > 0) await handle.append(events)
+    await handle.flush()
+  } finally {
+    await handle.close()
+  }
+}
diff --git a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
index d62e6a6ae7..8b190d8092 100644
--- a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
@@ -65,7 +65,7 @@ async function setupWith(adapter: MockAdapter | GatedAdapter) {
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(tool)
   ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   parkParent(ctx, parent)
   return { ctx, parent, adapter }
 }
diff --git a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
index 082dbde76e..021d64b6f6 100644
--- a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
@@ -19,6 +19,7 @@ import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-a
 import * as tool from '../src/index.ts'
 import { parkParent } from './park-parent.ts'
 import { TestSessionQuery } from './test-session-query.ts'
+import { loadStoredSession } from '../../subagent/tests/persistence-helpers.ts'
 
 /** One scripted response that may wait on a caller-released gate before streaming. */
 interface GatedEntry {
@@ -67,7 +68,7 @@ async function setupWith(adapter: MockAdapter | GatedAdapter, park = true) {
   await ctx.plugin(SubagentFork, { providerName: 'fork' })
   await ctx.plugin(tool)
   ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   if (park) parkParent(ctx, parent)
   return { ctx, parent, adapter }
 }
@@ -151,7 +152,7 @@ describe('dsh-tool-subagent-control', () => {
 
     release.resolve(undefined)
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const promptIndex = loaded.events.findIndex(event => event.type === 'user/message'
       && event.data.content.some(block => block.type === 'text' && block.text === 'fork task'))
     expect(loaded.meta.isSeeded).toBe(true)
@@ -167,7 +168,7 @@ describe('dsh-tool-subagent-control', () => {
 
   it('JSON-encodes a caller-supplied parent id in the initial return instruction', async () => {
     const { ctx } = await setup([textResponse('child done')])
-    const parent = ctx.agentLoop.create(SessionId('parent"\nagent'), { provider: 'mock', model: 'mock' })
+    const parent = await ctx.agentLoop.create(SessionId('parent"\nagent'), { provider: 'mock', model: 'mock' })
     parkParent(ctx, parent)
     const started = await ctx.subagents.startContinuable({
       provider: 'spawn',
@@ -176,7 +177,7 @@ describe('dsh-tool-subagent-control', () => {
       signal: testToolSignal,
     })
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const prompt = loaded.events.find(event => event.type === 'user/message'
       && event.data.content.some(block => block.type === 'text' && block.text === 'encoded task'))
     if (prompt?.type !== 'user/message') throw new Error('expected the encoded initial task')
@@ -247,7 +248,7 @@ describe('dsh-tool-subagent-control', () => {
     expect(text(result)).toBe(`message delivered to agent ${started.childId}`)
     await waitNoActivation(ctx, started.childId)
 
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const followUp = loaded.events.findLast(event => event.type === 'user/message')
     // The durable message source records the calling agent without granting authority.
     expect(followUp?.type === 'user/message' && followUp.data.source).toEqual({
@@ -278,7 +279,7 @@ describe('dsh-tool-subagent-control', () => {
     expect(result.isError).toBe(false)
 
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const prompts = loaded.events.flatMap(event => event.type === 'user/message' && event.data.source.kind !== 'plugin'
       ? event.data.content.flatMap(block => block.type === 'text'
         && !block.text.startsWith('Your parent agent id is ')
@@ -311,7 +312,7 @@ describe('dsh-tool-subagent-control', () => {
       signal: testToolSignal,
     })
     await waitNoActivation(ctx, started.childId)
-    const stranger = ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
+    const stranger = await ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
 
     const result = await callTool(ctx, 'send_message', {
       agent_id: started.childId,
@@ -401,7 +402,7 @@ describe('dsh-tool-subagent-control interrupt_agent', () => {
     }, parent)
     expect(waking.isError).toBe(false)
     await waitNoActivation(ctx, started.childId)
-    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     const prompts = loaded.events.flatMap(event => event.type === 'user/message' && event.data.source.kind !== 'plugin'
       ? event.data.content.flatMap(block => block.type === 'text'
         && !block.text.startsWith('Your parent agent id is ')
@@ -477,7 +478,7 @@ describe('dsh-tool-subagent-control interrupt_agent', () => {
     await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
     const targetAgent = ctx.agents.get(target.childId)!
     const siblingAgent = ctx.agents.get(sibling.childId)!
-    const stranger = ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
+    const stranger = await ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
     const cancelSpy = vi.spyOn(targetAgent, 'cancel')
 
     const self = await callTool(ctx, 'interrupt_agent', { agent_id: target.childId }, targetAgent)
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 7dccef4f41..e5f9502a43 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -19,6 +19,7 @@ import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import { loadStoredSession } from '../../subagent/tests/persistence-helpers.ts'
 import * as mock from './scripted-provider.ts'
 import * as tool from '../src/index.ts'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -1195,7 +1196,7 @@ describe('dsh-tool-subagent continuable background mode', () => {
     ctx.llm.registerAdapter(['mock'], new MockAdapter([
       textResponse('continuable answer'),
     ]))
-    const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+    const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
     return { ctx, parent }
   }
 
@@ -1245,7 +1246,7 @@ describe('dsh-tool-subagent continuable background mode', () => {
       expect(ctx.agents.get(SessionId(childId!))).toBeUndefined()
     }, { timeout: 5_000 })
     // The child id names a durable session carrying its continuation descriptor.
-    const loaded = await ctx.sessionPersistence.load(SessionId(childId!))
+    const loaded = await loadStoredSession(ctx.sessionPersistence, SessionId(childId!))
     expect(loaded.events.some(event => event.type === 'subagent/descriptor')).toBe(true)
     expect(loaded.events.some(event => event.type === 'assistant/message')).toBe(true)
   })
@@ -1322,7 +1323,7 @@ describe('dsh-tool-subagent continuable background mode', () => {
     expect(cancelledChildId).toBeDefined()
     expect(survivingChildId).toBeDefined()
     expect(ctx.agents.get(cancelledChildId!)).toBeUndefined()
-    await expect(ctx.sessionPersistence.load(cancelledChildId!)).rejects.toThrow(/not found/)
+    await expect(loadStoredSession(ctx.sessionPersistence, cancelledChildId!)).rejects.toThrow(/not found/)
 
     expect(succeeded.isError ? undefined : succeeded.value).toEqual({
       kind: 'continuable',
@@ -1331,7 +1332,7 @@ describe('dsh-tool-subagent continuable background mode', () => {
     await vi.waitFor(() => {
       expect(ctx.agents.get(survivingChildId!)).toBeUndefined()
     }, { timeout: 5_000 })
-    const loaded = await ctx.sessionPersistence.load(survivingChildId!)
+    const loaded = await loadStoredSession(ctx.sessionPersistence, survivingChildId!)
     expect(loaded.events.some(event => event.type === 'subagent/descriptor')).toBe(true)
     expect(loaded.events.some(event => event.type === 'assistant/message')).toBe(true)
   })
diff --git a/packages/test-support/loader-smoke/src/agent-turn.ts b/packages/test-support/loader-smoke/src/agent-turn.ts
index 5638445cbe..91e5ebebae 100644
--- a/packages/test-support/loader-smoke/src/agent-turn.ts
+++ b/packages/test-support/loader-smoke/src/agent-turn.ts
@@ -38,8 +38,21 @@ function assistantText(event: Extract<SessionEvent, { type: 'assistant/message'
   return blocks.length === 0 ? undefined : blocks.map(block => block.text).join('')
 }
 
-function onlyRootAgent(ctx: Context): Agent {
-  const agents = ctx.get('agents')?.roots() ?? []
+async function onlyRootAgent(ctx: Context): Promise<Agent> {
+  const registry = ctx.get('agents')
+  if (registry === undefined) throw new Error('fixture turn requires exactly one top-level agent, found 0')
+  // Configured agents publish asynchronously (persistence create/resume runs
+  // before publication), so a settled Loader does not imply a registered
+  // agent yet; wait for the first publication instead of requiring it.
+  if (registry.roots().length === 0) {
+    await new Promise<void>((resolve) => {
+      const dispose = ctx.on('agent/created', () => {
+        dispose()
+        resolve()
+      })
+    })
+  }
+  const agents = registry.roots()
   const [agent] = agents
   if (agent === undefined || agents.length !== 1) {
     throw new Error(`fixture turn requires exactly one top-level agent, found ${agents.length}`)
@@ -54,7 +67,7 @@ function onlyRootAgent(ctx: Context): Agent {
  * @returns the final assistant text and accumulated model usage.
  */
 export async function runFixtureTurn(ctx: Context, options: FixtureTurnOptions): Promise<FixtureTurnResult> {
-  const agent = onlyRootAgent(ctx)
+  const agent = await onlyRootAgent(ctx)
   await agent.whenIdle()
 
   const message = createUserMessage({
diff --git a/packages/test-support/loader-smoke/tests/agent-turn.spec.ts b/packages/test-support/loader-smoke/tests/agent-turn.spec.ts
index 4f04efc303..d5a83fb6e2 100644
--- a/packages/test-support/loader-smoke/tests/agent-turn.spec.ts
+++ b/packages/test-support/loader-smoke/tests/agent-turn.spec.ts
@@ -54,11 +54,33 @@ describe('runFixtureTurn', () => {
     ['no agent registry', undefined, 0],
     ['multiple roots', { roots: () => [{}, {}] }, 2],
   ])('rejects %s', async (_label, registry, count) => {
-    const ctx = { get: () => registry } as unknown as Context
+    const ctx = { get: () => registry, on: () => () => {} } as unknown as Context
     await expect(runFixtureTurn(ctx, { task: 'ignored' }))
       .rejects.toThrow(`fixture turn requires exactly one top-level agent, found ${count}`)
   })
 
+  it('waits for the configured agent to publish before requiring it', async () => {
+    // Configured agents publish asynchronously, so an initially empty registry
+    // waits for agent/created instead of rejecting.
+    const roots: object[] = []
+    let created: (() => void) | undefined
+    const dispose = vi.fn()
+    const ctx = {
+      get: (name: string) => name === 'agents' ? { roots: () => [...roots] } : undefined,
+      on: (name: string, callback: () => void) => {
+        if (name === 'agent/created') created = callback
+        return dispose
+      },
+    } as unknown as Context
+    const pending = runFixtureTurn(ctx, { task: 'ignored' })
+    // Publication with a second root still fails the exactly-one requirement,
+    // proving the count is re-checked after the wait.
+    roots.push({}, {})
+    created?.()
+    await expect(pending).rejects.toThrow('fixture turn requires exactly one top-level agent, found 2')
+    expect(dispose).toHaveBeenCalledOnce()
+  })
+
   it('observes only the owned interval and returns its final text and deduplicated usage', async () => {
     const harness = turnHarness()
     const observed: SessionEvent[] = []
diff --git a/packages/test-support/session-snapshot/tests/fixtures/subagent-durability-failure.ts b/packages/test-support/session-snapshot/tests/fixtures/subagent-durability-failure.ts
index 5c38967a12..7baaddb57a 100644
--- a/packages/test-support/session-snapshot/tests/fixtures/subagent-durability-failure.ts
+++ b/packages/test-support/session-snapshot/tests/fixtures/subagent-durability-failure.ts
@@ -13,7 +13,7 @@ export const inject = ['agents', 'sessionPersistence', 'subagents']
  *  - `PLACEHOLDER_CHILD_ID` in a scripted `send_message` is remapped to the real
  *    child so both follow-ups queue onto the same live inbox in FIFO order.
  *  - The unknown-id `send_message` (`UNKNOWN_CHILD_ID`) resolves through a
- *    persistence load fenced behind both accepted follow-ups, so the transcript
+ *    persistence stat fenced behind both accepted follow-ups, so the transcript
  *    records the same order on every runner.
  *  - The child's final continuation turn fails its durability checkpoint with a
  *    fixed message, so the scenario proves child-first disposal survives a failed
@@ -35,7 +35,7 @@ export function apply(ctx: Context): void {
   let parentClosed = false
   const publishedFailure = process.env.DSH_SUBAGENT_PUBLISHED_FAILURE === '1'
   const persistence = ctx.sessionPersistence
-  const load = persistence.load.bind(persistence)
+  const stat = persistence.stat.bind(persistence)
   const agents = ctx.agents
   const create = agents.create.bind(agents)
 
@@ -56,13 +56,13 @@ export function apply(ctx: Context): void {
 
   // The unavailable-child lookup is real asynchronous I/O. Fence it behind both
   // authored follow-ups so runner speed cannot reorder the exact log.
-  persistence.load = async (id) => {
+  persistence.stat = async (id, options) => {
     if (id === UNKNOWN_CHILD_ID) await followupsAccepted.promise
-    return load.call(persistence, id)
+    return stat(id, options)
   }
   ctx.effect(() => () => {
     agents.create = create
-    persistence.load = load
+    persistence.stat = stat
     followupsAccepted.resolve(undefined)
     parentTurnClosed.resolve(undefined)
   }, 'subagent snapshot ordering')
diff --git a/packages/todo/tool-todo/tests/integration.spec.ts b/packages/todo/tool-todo/tests/integration.spec.ts
index 2ca91bb10f..696a1ef99e 100644
--- a/packages/todo/tool-todo/tests/integration.spec.ts
+++ b/packages/todo/tool-todo/tests/integration.spec.ts
@@ -60,7 +60,7 @@ describe('todo_write tool through the agent loop', () => {
       textResponse('Plan recorded.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('it-todo'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('it-todo'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'plan a two-step task' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
@@ -88,7 +88,7 @@ describe('todo_write tool through the agent loop', () => {
       textResponse('Done planning.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(SessionId('it-todo-2'), { provider: 'mock', model: 'mock' })
+    const agent = await ctx.agentLoop.create(SessionId('it-todo-2'), { provider: 'mock', model: 'mock' })
 
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'plan then update' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
diff --git a/packages/workflow/workflow-worker-thread/tests/integration.spec.ts b/packages/workflow/workflow-worker-thread/tests/integration.spec.ts
index 686c342ad5..ed67dccc0a 100644
--- a/packages/workflow/workflow-worker-thread/tests/integration.spec.ts
+++ b/packages/workflow/workflow-worker-thread/tests/integration.spec.ts
@@ -42,7 +42,7 @@ async function setup(script: Script) {
   await ctx.plugin(spawn, { providerName: 'spawn' })
   await ctx.plugin(WorkerThreadWorkflowEngine, {})
   ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = await ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent, adapter }
 }
 
diff --git a/packages/workspace/workspace/src/index.ts b/packages/workspace/workspace/src/index.ts
index 87edb28cad..5e96de7ee4 100644
--- a/packages/workspace/workspace/src/index.ts
+++ b/packages/workspace/workspace/src/index.ts
@@ -126,11 +126,11 @@ export class WorkspaceRegistry extends Service {
     await this.recoverPendingMutation()
     this.validateStoredState(this.state)
     if (!this.state.initialized) {
-      const headers = await this.ctx.sessionPersistence.list()
+      const headers = await this.listStoredHeaders()
       await this.replaceHeaderIndex(headers)
       await this.bootstrap(headers)
     } else if (this.table.size > 0) {
-      await this.replaceHeaderIndex(await this.ctx.sessionPersistence.list())
+      await this.replaceHeaderIndex(await this.listStoredHeaders())
     }
 
     await this.indexLiveSessions()
@@ -263,7 +263,7 @@ export class WorkspaceRegistry extends Service {
   private async sessionKnown(id: SessionId): Promise<boolean> {
     if (this.ctx.get('sessions')?.get(id) !== undefined) return true
     if (this.headers.has(id)) return true
-    await this.indexHeaders(await this.ctx.sessionPersistence.list())
+    await this.indexHeaders(await this.listStoredHeaders())
     return this.headers.has(id)
   }
 
@@ -589,6 +589,12 @@ export class WorkspaceRegistry extends Service {
     }
   }
 
+  /** Every stored session's header, projected from the persistence snapshot listing. */
+  private async listStoredHeaders(): Promise<SessionHeader[]> {
+    const snapshots = await this.ctx.sessionPersistence.list()
+    return snapshots.map(snapshot => snapshot.header)
+  }
+
   private async indexLiveSessions(): Promise<void> {
     const sessions = this.ctx.get('sessions')
     if (sessions === undefined) return
@@ -621,7 +627,7 @@ export class WorkspaceRegistry extends Service {
     const cached = this.headers.get(id)
     if (cached !== undefined) return cached
 
-    const headers = await this.ctx.sessionPersistence.list()
+    const headers = await this.listStoredHeaders()
     await this.indexHeaders(headers)
     const header = this.headers.get(id)
     if (header === undefined) {
diff --git a/packages/workspace/workspace/tests/workspace.spec.ts b/packages/workspace/workspace/tests/workspace.spec.ts
index 49348cea2a..27571591c4 100644
--- a/packages/workspace/workspace/tests/workspace.spec.ts
+++ b/packages/workspace/workspace/tests/workspace.spec.ts
@@ -9,6 +9,8 @@ import { DomainFacility } from '@deepseek-ai/dsh-storage-domain'
 import type { DomainChanged } from '@deepseek-ai/dsh-storage-domain'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionPersistenceSnapshot } from '@deepseek-ai/dsh-session-persistence'
 import { MemoryMediaPool, MemoryStorageBackend } from '../../../storage/storage-domain/tests/helpers/memory-backend.ts'
 import WorkspaceRegistry, {
   WorkspaceId,
@@ -46,10 +48,11 @@ async function harness(options: HarnessOptions = {}) {
   ctx.provide('storageDomain', facility)
 
   let listed = options.sessions ?? []
-  const list = vi.fn(async () => listed)
-  const load = vi.fn(() => { throw new Error('event bodies must not be loaded') })
-  const inspect = vi.fn(() => { throw new Error('event bodies must not be inspected') })
-  ctx.provide('sessionPersistence', { list, load, inspect } as never)
+  const list = vi.fn(async (): Promise<SessionPersistenceSnapshot[]> =>
+    listed.map(header => ({ header, revision: SessionPersistenceRevision(`rev-${header.id}`) })))
+  const open = vi.fn(() => { throw new Error('event bodies must not be opened') })
+  const stat = vi.fn(() => { throw new Error('per-session stat must not be needed') })
+  ctx.provide('sessionPersistence', { list, open, stat } as never)
 
   if (options.sessionStore === true) {
     await ctx.plugin(SessionStore)
@@ -74,8 +77,8 @@ async function harness(options: HarnessOptions = {}) {
     changes,
     initChanges,
     list,
-    load,
-    inspect,
+    open,
+    stat,
     setSessions: (headers: SessionHeader[]) => { listed = headers },
   }
 }
@@ -192,7 +195,7 @@ describe('WorkspaceRegistry lifecycle and bootstrap', () => {
     expect(ctx.get('workspaceRegistry')).toBeUndefined()
     expect(pool.media.has('workspace')).toBe(false)
 
-    const list = vi.fn(async () => [] as SessionHeader[])
+    const list = vi.fn(async () => [] as SessionPersistenceSnapshot[])
     ctx.provide('sessionPersistence', { list } as never)
     await fiber.await()
     expect(ctx.workspaceRegistry.list()).toEqual([])
@@ -220,8 +223,8 @@ describe('WorkspaceRegistry lifecycle and bootstrap', () => {
     })
 
     expect(result.list).toHaveBeenCalledTimes(1)
-    expect(result.load).not.toHaveBeenCalled()
-    expect(result.inspect).not.toHaveBeenCalled()
+    expect(result.open).not.toHaveBeenCalled()
+    expect(result.stat).not.toHaveBeenCalled()
     expect(result.registry.list().map(workspace => workspace.path)).toEqual([newer, older])
     expect(result.registry.list().map(workspace => workspace.sessionIds)).toEqual([
       ['newer-only'],
@@ -491,8 +494,8 @@ describe('WorkspaceRegistry create and lookup', () => {
     expect(result.pool.media.get('workspace')!.tables.get('workspaces')!.has(workspace.id)).toBe(false)
     await expect(realpath(dir)).resolves.toBe(dir)
     expect(result.list).toHaveBeenCalledTimes(1)
-    expect(result.load).not.toHaveBeenCalled()
-    expect(result.inspect).not.toHaveBeenCalled()
+    expect(result.open).not.toHaveBeenCalled()
+    expect(result.stat).not.toHaveBeenCalled()
 
     const reregistered = await result.registry.create(dir)
     expect(reregistered.id).not.toBe(workspace.id)
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4521b1bbf4..91d39d1577 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -5600,9 +5600,6 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
         version: link:../../session/session-persistence-jsonl
@@ -5652,9 +5649,6 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
         version: link:../../session/session-persistence-jsonl
@@ -7616,9 +7610,6 @@ importers:
       '@deepseek-ai/dsh-llm':
         specifier: workspace:^
         version: link:../../llm/llm
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-shell':
         specifier: workspace:^
         version: link:../shell
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index e0f068e0d7..8290725faa 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -411,13 +411,17 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   CreateSessionOptions: 'persistence.md',
   PrepareSessionOptions: 'persistence.md',
   SessionHeader: 'persistence.md',
-  SessionInspection: 'persistence.md',
-  SessionEventSuffix: 'persistence.md',
-  BorrowedSessionSource: 'persistence.md',
   SessionLocation: 'persistence.md',
   SessionPreparation: 'persistence.md',
+  SessionAccess: 'persistence.md',
+  SessionHandle: 'persistence.md',
+  SessionPersistenceCreateOptions: 'persistence.md',
+  SessionPersistenceOpenOptions: 'persistence.md',
+  SessionPersistenceStatOptions: 'persistence.md',
+  SessionPersistenceListOptions: 'persistence.md',
   SessionPersistenceSnapshot: 'persistence.md',
-  SessionRawArtifact: 'persistence.md',
+  SessionInspection: 'persistence.md',
+  SessionStorageMetadata: 'persistence.md',
   ConfinedArgv: 'sandbox.md',
   SandboxExecutionPolicy: 'sandbox.md',
   SandboxMode: 'sandbox.md',
diff --git a/scripts/package-dependency-policy.ts b/scripts/package-dependency-policy.ts
index 63054fd183..11702c568a 100644
--- a/scripts/package-dependency-policy.ts
+++ b/scripts/package-dependency-policy.ts
@@ -51,6 +51,7 @@ const SAFE_HOST_DEPENDENCY_EXPORTS = {
 /** Runtime exports that require every consumer to resolve the provider's shared peer instance. */
 const PEER_REQUIRED_HOST_EXPORTS = {
   '@deepseek-ai/dsh-scope': ['carrierKeyOf', 'scopeOf', 'scopeTarget'],
+  '@deepseek-ai/dsh-session-persistence': ['SessionPersistenceNotFoundError'],
 } as const satisfies HostDependencyExports
 
 /** Exact import specifier to reviewed runtime exports. */
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 7def55bbee..a2ad93dd52 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -545,6 +545,11 @@
       "source": "packages/core/session/src/index.ts",
       "projection": "public-api"
     },
+    {
+      "doc": "docs/subsystems/persistence.md",
+      "symbol": "SessionHandle",
+      "source": "packages/session/session-persistence/src/handle.ts"
+    },
     {
       "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionHeader",
@@ -576,30 +581,10 @@
       "source": "packages/core/session/src/preparation.ts",
       "projection": "public-api"
     },
-    {
-      "doc": "docs/subsystems/persistence.md",
-      "symbol": "SessionStorageMetadata",
-      "source": "packages/session/session-persistence/src/index.ts"
-    },
-    {
-      "doc": "docs/subsystems/persistence.md",
-      "symbol": "SessionInspection",
-      "source": "packages/session/session-persistence/src/index.ts"
-    },
-    {
-      "doc": "docs/subsystems/persistence.md",
-      "symbol": "SessionEventSuffix",
-      "source": "packages/session/session-persistence/src/index.ts"
-    },
     {
       "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionLocation",
-      "source": "packages/session/session-persistence/src/index.ts"
-    },
-    {
-      "doc": "docs/subsystems/persistence.md",
-      "symbol": "SessionRawArtifact",
-      "source": "packages/session/session-persistence/src/index.ts"
+      "source": "packages/session/session-persistence/src/errors.ts"
     },
     {
       "doc": "docs/subsystems/session-query.md",
diff --git a/snapshots/web/navigation-panes/session.jsonl b/snapshots/web/navigation-panes/session.jsonl
index cdc6d9536a..eb63fd8bfb 100644
--- a/snapshots/web/navigation-panes/session.jsonl
+++ b/snapshots/web/navigation-panes/session.jsonl
@@ -1,6 +1,6 @@
 {"type":"session","version":0,"id":"{{session:1}}","createdAt":1785011380476,"cwd":"{{cwd}}/workspace"}
-{"type":"turn/start","data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user","rpcId":"{{rpc:1}}"}}}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"NavScenario: first run bash to print exactly NAVIGATION_OK, then read nav-a.md and nav-b.md using two read calls in ONE assistant message, then reply with the single word FIRST_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"}},"surfaceOp":"append"}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"user/message","data":{"content":[{"type":"text","text":"NavScenario: first run bash to print exactly NAVIGATION_OK, then read nav-a.md and nav-b.md using two read calls in ONE assistant message, then reply with the single word FIRST_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"NavScenario: first run bash to","messageSeqs":[1],"source":{"kind":"fallback"}}}
 {"type":"step/start","data":{"turn":1,"step":1}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}","messagePrefix":["{{messagePrefix}}"]},"reason":"initial"}}
@@ -18,13 +18,13 @@
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":3,"block":{"type":"tool-call","id":"call_02_k8Z6wGirxfnW96Iv8mkz9224","name":"read","arguments":"{\"file_path\": \"nav-b.md\"}"}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":140,"outputTokens":197,"cacheReadTokens":7680,"reasoningTokens":66}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to follow a specific navigation scenario. Let me:\n\n1. Run bash to print \"NAVIGATION_OK\"\n2. Read nav-a.md and nav-b.md in two read calls in ONE message\n3. Reply with \"FIRST_DONE\"\n\nLet me start with the bash command and the reads."},{"type":"tool-call","id":"call_00_kFKHaEXcTYEex0iDZw0C2432","name":"bash","arguments":"{\"command\": \"echo NAVIGATION_OK\", \"description\": \"Print NAVIGATION_OK\"}"},{"type":"tool-call","id":"call_01_tK4hIIRVTMgAvdzs7m9j6212","name":"read","arguments":"{\"file_path\": \"nav-a.md\"}"},{"type":"tool-call","id":"call_02_k8Z6wGirxfnW96Iv8mkz9224","name":"read","arguments":"{\"file_path\": \"nav-b.md\"}"}],"provenance":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"usage":{"inputTokens":140,"outputTokens":197,"cacheReadTokens":7680,"reasoningTokens":66}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132],"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":1,"usage":{"inputTokens":140,"outputTokens":197,"cacheReadTokens":7680,"reasoningTokens":66},"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to follow a specific navigation scenario. Let me:\n\n1. Run bash to print \"NAVIGATION_OK\"\n2. Read nav-a.md and nav-b.md in two read calls in ONE message\n3. Reply with \"FIRST_DONE\"\n\nLet me start with the bash command and the reads."},{"type":"tool-call","id":"call_00_kFKHaEXcTYEex0iDZw0C2432","name":"bash","arguments":"{\"command\": \"echo NAVIGATION_OK\", \"description\": \"Print NAVIGATION_OK\"}"},{"type":"tool-call","id":"call_01_tK4hIIRVTMgAvdzs7m9j6212","name":"read","arguments":"{\"file_path\": \"nav-a.md\"}"},{"type":"tool-call","id":"call_02_k8Z6wGirxfnW96Iv8mkz9224","name":"read","arguments":"{\"file_path\": \"nav-b.md\"}"}],"source":{"provider":"deepseek-official","model":"deepseek-v4-flash","kind":"model"},"id":"{{message:2}}"}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132],"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_kFKHaEXcTYEex0iDZw0C2432","name":"bash","arguments":"{\"command\": \"echo NAVIGATION_OK\", \"description\": \"Print NAVIGATION_OK\"}"}}
-{"type":"tool/result","data":{"turn":1,"step":1,"callId":"call_00_kFKHaEXcTYEex0iDZw0C2432","content":[{"type":"text","text":"NAVIGATION_OK\n"}],"isError":false},"sourceEventSeqs":[134],"surfaceOp":"append"}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"user","content":[{"type":"tool-result","toolCallId":"call_00_kFKHaEXcTYEex0iDZw0C2432","content":[{"type":"text","text":"NAVIGATION_OK\n"}],"isError":false}],"source":{"kind":"tool","callId":"call_00_kFKHaEXcTYEex0iDZw0C2432"},"id":"{{message:3}}"}},"sourceEventSeqs":[134],"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_01_tK4hIIRVTMgAvdzs7m9j6212","name":"read","arguments":"{\"file_path\": \"nav-a.md\"}"}}
 {"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_02_k8Z6wGirxfnW96Iv8mkz9224","name":"read","arguments":"{\"file_path\": \"nav-b.md\"}"}}
-{"type":"tool/result","data":{"turn":1,"step":1,"callId":"call_01_tK4hIIRVTMgAvdzs7m9j6212","content":[{"type":"text","text":"<path>{{cwd}}/workspace/nav-a.md</path>\n<type>file</type>\n<content>\n1: # alpha nav\n\n(End of file - total 1 lines)\n</content>"}],"isError":false},"sourceEventSeqs":[136],"surfaceOp":"append"}
-{"type":"tool/result","data":{"turn":1,"step":1,"callId":"call_02_k8Z6wGirxfnW96Iv8mkz9224","content":[{"type":"text","text":"<path>{{cwd}}/workspace/nav-b.md</path>\n<type>file</type>\n<content>\n1: # beta nav\n\n(End of file - total 1 lines)\n</content>"}],"isError":false},"sourceEventSeqs":[137],"surfaceOp":"append"}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"user","content":[{"type":"tool-result","toolCallId":"call_01_tK4hIIRVTMgAvdzs7m9j6212","content":[{"type":"text","text":"<path>{{cwd}}/workspace/nav-a.md</path>\n<type>file</type>\n<content>\n1: # alpha nav\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"source":{"kind":"tool","callId":"call_01_tK4hIIRVTMgAvdzs7m9j6212"},"id":"{{message:4}}"}},"sourceEventSeqs":[136],"surfaceOp":"append"}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"user","content":[{"type":"tool-result","toolCallId":"call_02_k8Z6wGirxfnW96Iv8mkz9224","content":[{"type":"text","text":"<path>{{cwd}}/workspace/nav-b.md</path>\n<type>file</type>\n<content>\n1: # beta nav\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"source":{"kind":"tool","callId":"call_02_k8Z6wGirxfnW96Iv8mkz9224"},"id":"{{message:5}}"}},"sourceEventSeqs":[137],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":1}}
 {"type":"step/start","data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
@@ -35,11 +35,11 @@
 {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"FIRST_DONE"}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":349,"outputTokens":56,"cacheReadTokens":7808,"reasoningTokens":51}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"All three calls succeeded:\n1. bash printed \"NAVIGATION_OK\"\n2. nav-a.md contains \"# alpha nav\"\n3. nav-b.md contains \"# beta nav\"\n\nNow I need to reply with the single word \"FIRST_DONE\"."},{"type":"text","text":"FIRST_DONE"}],"provenance":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"usage":{"inputTokens":349,"outputTokens":56,"cacheReadTokens":7808,"reasoningTokens":51}},"sourceEventSeqs":[142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202],"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":2,"usage":{"inputTokens":349,"outputTokens":56,"cacheReadTokens":7808,"reasoningTokens":51},"message":{"role":"assistant","content":[{"type":"reasoning","text":"All three calls succeeded:\n1. bash printed \"NAVIGATION_OK\"\n2. nav-a.md contains \"# alpha nav\"\n3. nav-b.md contains \"# beta nav\"\n\nNow I need to reply with the single word \"FIRST_DONE\"."},{"type":"text","text":"FIRST_DONE"}],"source":{"provider":"deepseek-official","model":"deepseek-v4-flash","kind":"model"},"id":"{{message:6}}"}},"sourceEventSeqs":[142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":2}}
 {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
-{"type":"turn/start","data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user","rpcId":"{{rpc:1}}"}}}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Reply in markdown with: a level-2 heading \"Navigation Summary\", a bulleted list of exactly two items, and a fenced code block containing echo WATERFALL. Then stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"}},"surfaceOp":"append"}
+{"type":"turn/start","data":{"turn":2}}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Reply in markdown with: a level-2 heading \"Navigation Summary\", a bulleted list of exactly two items, and a fenced code block containing echo WATERFALL. Then stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:7}}"},"surfaceOp":"append"}
 {"type":"step/start","data":{"turn":2,"step":1}}
 {"type":"assistant/chunk","data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
 {"type":"reasoning-chunks","data":{"turn":2,"step":1,"index":0,"dt":[125,23,1,0,0,88,0,0,5,0,1,0,0,7,0],"texts":["The"," user"," wants"," me"," to"," reply"," with"," a"," specific"," format","."," Let"," me"," do"," that","."]}}
@@ -49,6 +49,6 @@
 {"type":"assistant/chunk","data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"## Navigation Summary\n\n- alpha nav\n- beta nav\n\n```\necho WATERFALL\n```"}}}}
 {"type":"assistant/chunk","data":{"turn":2,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":141,"outputTokens":36,"cacheReadTokens":8064,"reasoningTokens":16}}}}
 {"type":"assistant/chunk","data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","data":{"turn":2,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with a specific format. Let me do that."},{"type":"text","text":"## Navigation Summary\n\n- alpha nav\n- beta nav\n\n```\necho WATERFALL\n```"}],"provenance":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"usage":{"inputTokens":141,"outputTokens":36,"cacheReadTokens":8064,"reasoningTokens":16}},"sourceEventSeqs":[209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249],"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":2,"step":1,"usage":{"inputTokens":141,"outputTokens":36,"cacheReadTokens":8064,"reasoningTokens":16},"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to reply with a specific format. Let me do that."},{"type":"text","text":"## Navigation Summary\n\n- alpha nav\n- beta nav\n\n```\necho WATERFALL\n```"}],"source":{"provider":"deepseek-official","model":"deepseek-v4-flash","kind":"model"},"id":"{{message:8}}"}},"sourceEventSeqs":[209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":2,"step":1}}
 {"type":"turn/end","data":{"turn":2,"reason":{"kind":"completed"}}}
diff --git a/snapshots/web/pwsh-terminal/session.jsonl b/snapshots/web/pwsh-terminal/session.jsonl
index 443a468d25..b417e1110b 100644
--- a/snapshots/web/pwsh-terminal/session.jsonl
+++ b/snapshots/web/pwsh-terminal/session.jsonl
@@ -1,6 +1,6 @@
 {"type":"session","version":0,"id":"{{session:1}}","createdAt":1784974100747}
-{"type":"turn/start","data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user","rpcId":"{{rpc:1}}"}}}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Run a PowerShell command that fails, then stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"}},"surfaceOp":"append"}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Run a PowerShell command that fails, then stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Run a PowerShell command","messageSeqs":[1],"source":{"kind":"fallback"}}}
 {"type":"step/start","data":{"turn":1,"step":1}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}","messagePrefix":["{{messagePrefix}}"]},"reason":"initial"}}
@@ -12,8 +12,8 @@
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_pwsh_fail_0001","name":"pwsh","arguments":"{\"command\": \"Get-Item missing.txt\", \"description\": \"Fail deliberately\"}"}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":96,"outputTokens":64,"cacheReadTokens":0,"reasoningTokens":10}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"Run the failing pwsh command."},{"type":"tool-call","id":"call_pwsh_fail_0001","name":"pwsh","arguments":"{\"command\": \"Get-Item missing.txt\", \"description\": \"Fail deliberately\"}"}],"provenance":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"usage":{"inputTokens":96,"outputTokens":64,"cacheReadTokens":0,"reasoningTokens":10}},"sourceEventSeqs":[5,6,7,8,9,10,11,12],"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":1,"usage":{"inputTokens":96,"outputTokens":64,"cacheReadTokens":0,"reasoningTokens":10},"message":{"role":"assistant","content":[{"type":"reasoning","text":"Run the failing pwsh command."},{"type":"tool-call","id":"call_pwsh_fail_0001","name":"pwsh","arguments":"{\"command\": \"Get-Item missing.txt\", \"description\": \"Fail deliberately\"}"}],"source":{"provider":"deepseek-official","model":"deepseek-v4-flash","kind":"model"},"id":"{{message:2}}"}},"sourceEventSeqs":[5,6,7,8,9,10,11,12],"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_pwsh_fail_0001","name":"pwsh","arguments":"{\"command\": \"Get-Item missing.txt\", \"description\": \"Fail deliberately\"}"}}
-{"type":"tool/result","data":{"turn":1,"step":1,"callId":"call_pwsh_fail_0001","content":[{"type":"text","text":"[stderr]\nGet-Item : Cannot find path 'missing.txt' because it does not exist.\n[exit code: 1]"}],"isError":false},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"user","content":[{"type":"tool-result","toolCallId":"call_pwsh_fail_0001","content":[{"type":"text","text":"[stderr]\nGet-Item : Cannot find path 'missing.txt' because it does not exist.\n[exit code: 1]"}],"isError":false}],"source":{"kind":"tool","callId":"call_pwsh_fail_0001"},"id":"{{message:3}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":1}}
 {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/web/seeded-history/session.jsonl b/snapshots/web/seeded-history/session.jsonl
index 445758f663..f1b1298e79 100644
--- a/snapshots/web/seeded-history/session.jsonl
+++ b/snapshots/web/seeded-history/session.jsonl
@@ -1,6 +1,6 @@
 {"type":"session","version":0,"id":"{{session:1}}","createdAt":1784974100747,"cwd":"{{cwd}}/workspace"}
-{"type":"turn/start","data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user","rpcId":"{{rpc:1}}"}}}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"}},"surfaceOp":"append"}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Use the read tool twice","messageSeqs":[1],"source":{"kind":"fallback"}}}
 {"type":"step/start","data":{"turn":1,"step":1}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}","messagePrefix":["{{messagePrefix}}"]},"reason":"initial"}}
@@ -15,11 +15,11 @@
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":2,"block":{"type":"tool-call","id":"call_01_Hw6AQjhf9gjxnOtppcGx0725","name":"read","arguments":"{\"file_path\": \"b.txt\"}"}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":124,"outputTokens":103,"cacheReadTokens":7680,"reasoningTokens":27}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to read a.txt and b.txt, then reply with \"DONE\". Let me do both reads in parallel."},{"type":"tool-call","id":"call_00_OsndvlcKnCcUmae7QXal8633","name":"read","arguments":"{\"file_path\": \"a.txt\"}"},{"type":"tool-call","id":"call_01_Hw6AQjhf9gjxnOtppcGx0725","name":"read","arguments":"{\"file_path\": \"b.txt\"}"}],"provenance":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"usage":{"inputTokens":124,"outputTokens":103,"cacheReadTokens":7680,"reasoningTokens":27}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63],"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":1,"usage":{"inputTokens":124,"outputTokens":103,"cacheReadTokens":7680,"reasoningTokens":27},"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to read a.txt and b.txt, then reply with \"DONE\". Let me do both reads in parallel."},{"type":"tool-call","id":"call_00_OsndvlcKnCcUmae7QXal8633","name":"read","arguments":"{\"file_path\": \"a.txt\"}"},{"type":"tool-call","id":"call_01_Hw6AQjhf9gjxnOtppcGx0725","name":"read","arguments":"{\"file_path\": \"b.txt\"}"}],"source":{"provider":"deepseek-official","model":"deepseek-v4-flash","kind":"model"},"id":"{{message:2}}"}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63],"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_OsndvlcKnCcUmae7QXal8633","name":"read","arguments":"{\"file_path\": \"a.txt\"}"}}
 {"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_01_Hw6AQjhf9gjxnOtppcGx0725","name":"read","arguments":"{\"file_path\": \"b.txt\"}"}}
-{"type":"tool/result","data":{"turn":1,"step":1,"callId":"call_00_OsndvlcKnCcUmae7QXal8633","content":[{"type":"text","text":"<path>{{cwd}}/workspace/a.txt</path>\n<type>file</type>\n<content>\n1: alpha\n\n(End of file - total 1 lines)\n</content>"}],"isError":false},"sourceEventSeqs":[65],"surfaceOp":"append"}
-{"type":"tool/result","data":{"turn":1,"step":1,"callId":"call_01_Hw6AQjhf9gjxnOtppcGx0725","content":[{"type":"text","text":"<path>{{cwd}}/workspace/b.txt</path>\n<type>file</type>\n<content>\n1: beta\n\n(End of file - total 1 lines)\n</content>"}],"isError":false},"sourceEventSeqs":[66],"surfaceOp":"append"}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"user","content":[{"type":"tool-result","toolCallId":"call_00_OsndvlcKnCcUmae7QXal8633","content":[{"type":"text","text":"<path>{{cwd}}/workspace/a.txt</path>\n<type>file</type>\n<content>\n1: alpha\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"source":{"kind":"tool","callId":"call_00_OsndvlcKnCcUmae7QXal8633"},"id":"{{message:3}}"}},"sourceEventSeqs":[65],"surfaceOp":"append"}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"user","content":[{"type":"tool-result","toolCallId":"call_01_Hw6AQjhf9gjxnOtppcGx0725","content":[{"type":"text","text":"<path>{{cwd}}/workspace/b.txt</path>\n<type>file</type>\n<content>\n1: beta\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"source":{"kind":"tool","callId":"call_01_Hw6AQjhf9gjxnOtppcGx0725"},"id":"{{message:4}}"}},"sourceEventSeqs":[66],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":1}}
 {"type":"step/start","data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
@@ -31,6 +31,6 @@
 {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":215,"outputTokens":32,"cacheReadTokens":7808,"reasoningTokens":29}}}}
 {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"Both files have been read. a.txt contains \"alpha\" and b.txt contains \"beta\". I'll now reply with DONE as instructed."},{"type":"text","text":"DONE"}],"provenance":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"usage":{"inputTokens":215,"outputTokens":32,"cacheReadTokens":7808,"reasoningTokens":29}},"sourceEventSeqs":[71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107],"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":2,"usage":{"inputTokens":215,"outputTokens":32,"cacheReadTokens":7808,"reasoningTokens":29},"message":{"role":"assistant","content":[{"type":"reasoning","text":"Both files have been read. a.txt contains \"alpha\" and b.txt contains \"beta\". I'll now reply with DONE as instructed."},{"type":"text","text":"DONE"}],"source":{"provider":"deepseek-official","model":"deepseek-v4-flash","kind":"model"},"id":"{{message:5}}"}},"sourceEventSeqs":[71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":2}}
 {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}

From a9e185f205169262ab39cbbda9fc48b16c37bbe9 Mon Sep 17 00:00:00 2001
From: imccyu <cc.yu@deepseek.com>
Date: Tue, 1 Sep 2026 23:17:11 +0800
Subject: [PATCH 37/37] release(dsh): 0.1.2-alpha.4

---
 apps/cli/package.json                                          | 2 +-
 apps/web/package.json                                          | 2 +-
 package.json                                                   | 2 +-
 packages/acp/acp/package.json                                  | 2 +-
 packages/api/gateway/package.json                              | 2 +-
 packages/api/remotes/package.json                              | 2 +-
 packages/api/session-controller/package.json                   | 2 +-
 packages/api/settings-controller/package.json                  | 2 +-
 packages/api/workspace-controller/package.json                 | 2 +-
 packages/attachment/attachment-local/package.json              | 2 +-
 packages/attachment/attachment/package.json                    | 2 +-
 packages/boot/app-boot/package.json                            | 2 +-
 packages/boot/cmdline/package.json                             | 2 +-
 packages/bundle/acp-app/package.json                           | 2 +-
 packages/bundle/base/package.json                              | 2 +-
 packages/bundle/headless/package.json                          | 2 +-
 packages/bundle/sdk-app/package.json                           | 2 +-
 packages/bundle/sdk-minimal/package.json                       | 2 +-
 packages/bundle/web-app/package.json                           | 2 +-
 packages/client/connection/package.json                        | 2 +-
 packages/client/hmr/package.json                               | 2 +-
 packages/client/locale/package.json                            | 2 +-
 packages/client/modules/package.json                           | 2 +-
 packages/client/store/package.json                             | 2 +-
 packages/client/ui-agent-preset/package.json                   | 2 +-
 packages/client/ui-approval/package.json                       | 2 +-
 packages/client/ui-attachment/package.json                     | 2 +-
 packages/client/ui-brand-official/package.json                 | 2 +-
 packages/client/ui-chat/package.json                           | 2 +-
 packages/client/ui-commands/package.json                       | 2 +-
 packages/client/ui-conversation/package.json                   | 2 +-
 packages/client/ui-deliverables/package.json                   | 2 +-
 packages/client/ui-directory-picker-browse/package.json        | 2 +-
 packages/client/ui-directory-picker-native/package.json        | 2 +-
 packages/client/ui-goal/package.json                           | 2 +-
 packages/client/ui-input-trigger/package.json                  | 2 +-
 packages/client/ui-jobs/package.json                           | 2 +-
 packages/client/ui-layout/package.json                         | 2 +-
 packages/client/ui-message-feedback/package.json               | 2 +-
 packages/client/ui-model-selection/package.json                | 2 +-
 packages/client/ui-permission-presets/package.json             | 2 +-
 packages/client/ui-plan/package.json                           | 2 +-
 packages/client/ui-primitives/package.json                     | 2 +-
 packages/client/ui-reference/package.json                      | 2 +-
 packages/client/ui-renderer/package.json                       | 2 +-
 packages/client/ui-schedule/package.json                       | 2 +-
 packages/client/ui-session/package.json                        | 2 +-
 packages/client/ui-settings-general/package.json               | 2 +-
 packages/client/ui-settings-models/package.json                | 2 +-
 packages/client/ui-settings-plugin-inventory/package.json      | 2 +-
 packages/client/ui-settings-plugins/package.json               | 2 +-
 packages/client/ui-settings/package.json                       | 2 +-
 packages/client/ui-sidebar/package.json                        | 2 +-
 packages/client/ui-skill/package.json                          | 2 +-
 packages/client/ui-slots/package.json                          | 2 +-
 packages/client/ui-subagent/package.json                       | 2 +-
 packages/client/ui-theme/package.json                          | 2 +-
 packages/client/ui-tool/package.json                           | 2 +-
 packages/client/ui-trajectory/package.json                     | 2 +-
 packages/client/ui-user-questions/package.json                 | 2 +-
 packages/client/ui-workflow-run/package.json                   | 2 +-
 packages/client/ui-workspace/package.json                      | 2 +-
 packages/client/web/package.json                               | 2 +-
 packages/code-runtime/code-runtime-worker-thread/package.json  | 2 +-
 packages/code-runtime/code-runtime/package.json                | 2 +-
 packages/compaction/command-compact/package.json               | 2 +-
 packages/compaction/compaction-basic/package.json              | 2 +-
 packages/compaction/compaction-tool-result-pruner/package.json | 2 +-
 packages/compaction/compaction/package.json                    | 2 +-
 packages/context/agent-instructions/package.json               | 2 +-
 packages/context/file-reference-local/package.json             | 2 +-
 packages/context/file-reference/package.json                   | 2 +-
 packages/context/session-reference/package.json                | 2 +-
 packages/context/time-context/package.json                     | 2 +-
 packages/context/tmux-context/package.json                     | 2 +-
 packages/core/agent-default-model/package.json                 | 2 +-
 packages/core/agent-loop/package.json                          | 2 +-
 packages/core/agent-tool-presentation/package.json             | 2 +-
 packages/core/agent/package.json                               | 2 +-
 packages/core/scope/package.json                               | 2 +-
 packages/core/session/package.json                             | 2 +-
 packages/core/system-prompt/package.json                       | 2 +-
 packages/core/tools/package.json                               | 2 +-
 packages/credentials/authorization/package.json                | 2 +-
 packages/credentials/credentials-local/package.json            | 2 +-
 packages/credentials/credentials/package.json                  | 2 +-
 packages/e2b/e2b/package.json                                  | 2 +-
 packages/e2b/fs-e2b/package.json                               | 2 +-
 packages/e2b/subprocess-e2b/package.json                       | 2 +-
 packages/experimental/agent-team-profile/package.json          | 2 +-
 packages/experimental/agent-team-web-profile/package.json      | 2 +-
 packages/experimental/agent-team/package.json                  | 2 +-
 packages/experimental/client-ui-agent-team/package.json        | 2 +-
 packages/experimental/code-runtime-python/package.json         | 2 +-
 packages/experimental/inspector/package.json                   | 2 +-
 packages/experimental/tool-agent-team/package.json             | 2 +-
 packages/experimental/webworker-packer/package.json            | 2 +-
 packages/experimental/webworker-runtime/package.json           | 2 +-
 packages/extensions/cordis-client-runner/package.json          | 2 +-
 packages/extensions/cordis-host-runner/package.json            | 2 +-
 packages/extensions/tool-cordis/package.json                   | 2 +-
 packages/extensions/ui-cordis/package.json                     | 2 +-
 packages/feedback/command-feedback/package.json                | 2 +-
 packages/feedback/message-feedback/package.json                | 2 +-
 packages/fs/fs-local/package.json                              | 2 +-
 packages/fs/fs-observation-policy/package.json                 | 2 +-
 packages/fs/fs-sandbox/package.json                            | 2 +-
 packages/fs/fs/package.json                                    | 2 +-
 packages/fs/tool-fs-search/package.json                        | 2 +-
 packages/fs/tool-fs/package.json                               | 2 +-
 packages/fs/tool-str-replace-editor/package.json               | 2 +-
 packages/goal/command-goal/package.json                        | 2 +-
 packages/goal/goal-round-driver/package.json                   | 2 +-
 packages/goal/goal/package.json                                | 2 +-
 packages/goal/tool-goal/package.json                           | 2 +-
 packages/guard/repeat-tool-reminder/package.json               | 2 +-
 packages/guard/timeout-policy/package.json                     | 2 +-
 packages/hooks/hook-protocol/package.json                      | 2 +-
 packages/hooks/hooks-claude-code/package.json                  | 2 +-
 packages/hooks/hooks-codex/package.json                        | 2 +-
 packages/host/directory-picker-auto/package.json               | 2 +-
 packages/host/directory-picker-browse/package.json             | 2 +-
 packages/host/directory-picker-native/package.json             | 2 +-
 packages/host/directory-picker/package.json                    | 2 +-
 packages/host/frontend-static/package.json                     | 2 +-
 packages/host/plugin-inventory/package.json                    | 2 +-
 packages/host/webserver/package.json                           | 2 +-
 packages/identity/anonymous-user-id/package.json               | 2 +-
 packages/interaction/commands/package.json                     | 2 +-
 packages/interaction/permission-presets/package.json           | 2 +-
 packages/interaction/tool-ask-user/package.json                | 2 +-
 packages/interaction/user-approval/package.json                | 2 +-
 packages/interaction/user-questions/package.json               | 2 +-
 packages/jobs/jobs-local/package.json                          | 2 +-
 packages/jobs/jobs/package.json                                | 2 +-
 packages/jobs/tool-jobs/package.json                           | 2 +-
 packages/llm/deepseek-llm-api-extensions/package.json          | 2 +-
 packages/llm/llm-deepseek/package.json                         | 2 +-
 packages/llm/llm-pi-ai/package.json                            | 2 +-
 packages/llm/llm-retry/package.json                            | 2 +-
 packages/llm/llm/package.json                                  | 2 +-
 packages/llm/plugin-package-inventory-deepseek/package.json    | 2 +-
 packages/llm/token-meter/package.json                          | 2 +-
 packages/lsp/lsp-stdio/package.json                            | 2 +-
 packages/lsp/lsp/package.json                                  | 2 +-
 packages/lsp/tool-lsp/package.json                             | 2 +-
 packages/mcp/mcp-client/package.json                           | 2 +-
 packages/plan/plan-mode/package.json                           | 2 +-
 packages/preset/agent-presets/package.json                     | 2 +-
 packages/preset/persona/package.json                           | 2 +-
 packages/runtime-diagnostics/invariants/package.json           | 2 +-
 packages/sandbox/sandbox-local/package.json                    | 2 +-
 packages/sandbox/sandbox-policy/package.json                   | 2 +-
 packages/sandbox/sandbox-windows-acl/package.json              | 2 +-
 packages/sandbox/sandbox/package.json                          | 2 +-
 packages/schedule/schedule/package.json                        | 2 +-
 packages/sdk/client/package.json                               | 2 +-
 packages/sdk/protocol/package.json                             | 2 +-
 packages/sdk/server/package.json                               | 2 +-
 packages/session-query/session-log-export/package.json         | 2 +-
 packages/session-query/session-query-sqlite/package.json       | 2 +-
 packages/session-query/session-query/package.json              | 2 +-
 packages/session-query/tool-session-query/package.json         | 2 +-
 packages/session/session-checkpoint-policy/package.json        | 2 +-
 packages/session/session-log-deepseek/package.json             | 2 +-
 packages/session/session-persistence-jsonl/package.json        | 2 +-
 packages/session/session-persistence/package.json              | 2 +-
 packages/session/session-projection-cache/package.json         | 2 +-
 packages/session/session-projection/package.json               | 2 +-
 packages/session/session-stats/package.json                    | 2 +-
 packages/session/session-telemetry-otel/package.json           | 2 +-
 packages/session/session-telemetry/package.json                | 2 +-
 packages/session/session-title-all-prompts-llm/package.json    | 2 +-
 packages/session/session-title-first-prompt-llm/package.json   | 2 +-
 packages/session/session-title-llm/package.json                | 2 +-
 packages/session/session-title/package.json                    | 2 +-
 packages/session/session-turn-outline/package.json             | 2 +-
 packages/settings/settings-file/package.json                   | 2 +-
 packages/settings/settings/package.json                        | 2 +-
 packages/shell/bash-local/package.json                         | 2 +-
 packages/shell/bash-sandbox/package.json                       | 2 +-
 packages/shell/pwsh-local/package.json                         | 2 +-
 packages/shell/pwsh-sandbox/package.json                       | 2 +-
 packages/shell/shell-env/package.json                          | 2 +-
 packages/shell/shell/package.json                              | 2 +-
 packages/shell/tool-bash-persistent/package.json               | 2 +-
 packages/shell/tool-bash/package.json                          | 2 +-
 packages/shell/tool-pwsh-persistent/package.json               | 2 +-
 packages/shell/tool-pwsh/package.json                          | 2 +-
 packages/skill/skill-badge/package.json                        | 2 +-
 packages/skill/skill-filesystem/package.json                   | 2 +-
 packages/skill/skill/package.json                              | 2 +-
 packages/skill/tool-skill/package.json                         | 2 +-
 packages/spill/spill-local/package.json                        | 2 +-
 packages/spill/spill-policy/package.json                       | 2 +-
 packages/spill/spill/package.json                              | 2 +-
 packages/storage/storage-domain/package.json                   | 2 +-
 packages/storage/storage-json/package.json                     | 2 +-
 packages/storage/storage-sqlite/package.json                   | 2 +-
 packages/storage/storage/package.json                          | 2 +-
 packages/subagent/subagent-acp/package.json                    | 2 +-
 packages/subagent/subagent-claude-code/package.json            | 2 +-
 packages/subagent/subagent-codex/package.json                  | 2 +-
 packages/subagent/subagent-dsh-sdk/package.json                | 2 +-
 packages/subagent/subagent-fork-in-process/package.json        | 2 +-
 packages/subagent/subagent-in-process-driver/package.json      | 2 +-
 packages/subagent/subagent-spawn-in-process/package.json       | 2 +-
 packages/subagent/subagent/package.json                        | 2 +-
 packages/subagent/tool-subagent-control/package.json           | 2 +-
 packages/subagent/tool-subagent/package.json                   | 2 +-
 packages/subprocess/subprocess-local/package.json              | 2 +-
 packages/subprocess/subprocess/package.json                    | 2 +-
 packages/subprocess/win32-process/package.json                 | 2 +-
 packages/terminal/terminal-bash/package.json                   | 2 +-
 packages/terminal/terminal/package.json                        | 2 +-
 packages/terminal/tool-terminal/package.json                   | 2 +-
 packages/test-support/agent-loop-testkit/package.json          | 2 +-
 packages/test-support/client-runtime/package.json              | 2 +-
 packages/test-support/llm-mock-server/package.json             | 2 +-
 packages/test-support/llm-replay/package.json                  | 2 +-
 packages/test-support/loader-smoke/package.json                | 2 +-
 packages/test-support/session-snapshot/package.json            | 2 +-
 packages/todo/tool-todo/package.json                           | 2 +-
 packages/typert/generator/package.json                         | 2 +-
 packages/typert/loader/package.json                            | 2 +-
 packages/typert/protocol/package.json                          | 2 +-
 packages/typert/registry/package.json                          | 2 +-
 packages/util/atomic-write/package.json                        | 2 +-
 packages/util/brand/package.json                               | 2 +-
 packages/util/crypto/package.json                              | 2 +-
 packages/util/deque/package.json                               | 2 +-
 packages/util/home-paths/package.json                          | 2 +-
 packages/util/launch-environment/package.json                  | 2 +-
 packages/util/native-command/package.json                      | 2 +-
 packages/util/output-retention/package.json                    | 2 +-
 packages/util/time/package.json                                | 2 +-
 packages/util/timeout/package.json                             | 2 +-
 packages/util/values/package.json                              | 2 +-
 packages/util/workspace-path/package.json                      | 2 +-
 packages/web/tool-web/package.json                             | 2 +-
 packages/web/web-fetch-http/package.json                       | 2 +-
 packages/web/web-search-deepseek/package.json                  | 2 +-
 packages/web/web-search-exa/package.json                       | 2 +-
 packages/web/web-search-perplexity/package.json                | 2 +-
 packages/web/web/package.json                                  | 2 +-
 packages/webhook/webhook-github/package.json                   | 2 +-
 packages/webhook/webhook/package.json                          | 2 +-
 packages/workflow/tool-ralph/package.json                      | 2 +-
 packages/workflow/tool-workflow/package.json                   | 2 +-
 packages/workflow/workflow-worker-thread/package.json          | 2 +-
 packages/workflow/workflow/package.json                        | 2 +-
 packages/workspace/workspace/package.json                      | 2 +-
 252 files changed, 252 insertions(+), 252 deletions(-)

diff --git a/apps/cli/package.json b/apps/cli/package.json
index 18224b9c82..ac50f4864a 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh",
   "description": "dsh CLI: profile boot, plugin management, and the browser UI alias",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/apps/web/package.json b/apps/web/package.json
index f993d39587..e65aea0049 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-web-frontend",
   "description": "Web application entry: vite build over the @deepseek-ai/dsh-client-web shell library; dist/ served by apps/cli's dsh web",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/package.json b/package.json
index d947add909..78502c93f2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-root",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "license": "MIT",
   "private": true,
   "type": "module",
diff --git a/packages/acp/acp/package.json b/packages/acp/acp/package.json
index 888a445294..6040163821 100644
--- a/packages/acp/acp/package.json
+++ b/packages/acp/acp/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-acp",
   "description": "Automation-only Agent Client Protocol server for driving DeepSeek Harness agents over JSON-RPC stdio",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/api/gateway/package.json b/packages/api/gateway/package.json
index db6163c18e..41d7c3b9b2 100644
--- a/packages/api/gateway/package.json
+++ b/packages/api/gateway/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-gateway",
   "description": "Typert Remote Host dispatcher and Client API endpoint",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json
index a08895b357..5940ea9594 100644
--- a/packages/api/remotes/package.json
+++ b/packages/api/remotes/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-remotes",
   "description": "Remote BFF assembly for application-selected Host capabilities",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/api/session-controller/package.json b/packages/api/session-controller/package.json
index fc1de04248..b1fe281a9e 100644
--- a/packages/api/session-controller/package.json
+++ b/packages/api/session-controller/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-session-controller",
   "description": "Session Remote commands, cold reads, and live control transport",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/api/settings-controller/package.json b/packages/api/settings-controller/package.json
index f8a3526f75..56602b6c58 100644
--- a/packages/api/settings-controller/package.json
+++ b/packages/api/settings-controller/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-settings-controller",
   "description": "Remote owner for the configuration surfaces over the settings-domain seams",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/api/workspace-controller/package.json b/packages/api/workspace-controller/package.json
index dda1e924fb..0a64db9665 100644
--- a/packages/api/workspace-controller/package.json
+++ b/packages/api/workspace-controller/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-workspace-controller",
   "description": "Workspace Remote commands and reconnect-safe state transport",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/attachment/attachment-local/package.json b/packages/attachment/attachment-local/package.json
index edc9ce41ef..e04af21abd 100644
--- a/packages/attachment/attachment-local/package.json
+++ b/packages/attachment/attachment-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-attachment-local",
   "description": "Private content-addressed DSH_HOME attachment storage",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/attachment/attachment/package.json b/packages/attachment/attachment/package.json
index 3f4735b18b..64220b8e77 100644
--- a/packages/attachment/attachment/package.json
+++ b/packages/attachment/attachment/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-attachment",
   "description": "Durable immutable attachment storage seam for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/boot/app-boot/package.json b/packages/boot/app-boot/package.json
index cf2674fd0f..4ec69c6079 100644
--- a/packages/boot/app-boot/package.json
+++ b/packages/boot/app-boot/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-app-boot",
   "description": "Shared boot glue for the app bins: .env loading, fail-loud Loader guards, snapshot-aware config resolution, and the Loader boot sequence",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/boot/cmdline/package.json b/packages/boot/cmdline/package.json
index 8bf6253142..0fe1c084c5 100644
--- a/packages/boot/cmdline/package.json
+++ b/packages/boot/cmdline/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-cmdline",
   "description": "Immutable command-line handoff from a dsh launcher to any app plugin that injects cmdlineArgs",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/bundle/acp-app/package.json b/packages/bundle/acp-app/package.json
index 7ac571cb98..56604d34c8 100644
--- a/packages/bundle/acp-app/package.json
+++ b/packages/bundle/acp-app/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-acp-app",
   "description": "The dsh ACP profile bundle: automation-only JSON-RPC stdio and process lifecycle over dsh-base",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json
index 88e5d27814..ebc86eb5eb 100644
--- a/packages/bundle/base/package.json
+++ b/packages/bundle/base/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-base",
   "description": "The shared dsh core as a profile bundle: the first patch layer of base-backed profiles, inserting core rows over the empty profile root",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/bundle/headless/package.json b/packages/bundle/headless/package.json
index 5d64116544..6a9785ddeb 100644
--- a/packages/bundle/headless/package.json
+++ b/packages/bundle/headless/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-headless",
   "description": "The dsh one-shot bundle: a direct core Agent/Session runner over dsh-base with no Host, HTTP, or browser layer",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/bundle/sdk-app/package.json b/packages/bundle/sdk-app/package.json
index 6be7d3e3ff..e7a97c337c 100644
--- a/packages/bundle/sdk-app/package.json
+++ b/packages/bundle/sdk-app/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sdk-app",
   "description": "The dsh SDK profile bundle: stdio JSON-RPC serving and process lifecycle over dsh-base",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/bundle/sdk-minimal/package.json b/packages/bundle/sdk-minimal/package.json
index 1e9444dae7..fa99da9163 100644
--- a/packages/bundle/sdk-minimal/package.json
+++ b/packages/bundle/sdk-minimal/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sdk-minimal",
   "description": "The standalone minimal SDK profile bundle: JSON-RPC, one DeepSeek adapter, persistent shell, editor, and JSONL sessions",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json
index 0063e7758b..77e803c655 100644
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-web-app",
   "description": "The dsh browser-surface bundle: the web patch layer over dsh-base plus the runtime glue plugin (frontend dist serving, web-surface prompt, bash runtime variables, URL line)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/connection/package.json b/packages/client/connection/package.json
index 954f034ab6..9214c8eaa9 100644
--- a/packages/client/connection/package.json
+++ b/packages/client/connection/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-connection",
   "description": "Authenticated RPC transport, generation lifecycle, and browser fixture",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/hmr/package.json b/packages/client/hmr/package.json
index 44435ef224..2e23f9fc4d 100644
--- a/packages/client/hmr/package.json
+++ b/packages/client/hmr/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-hmr",
   "description": "Dev-only hot-reload driver for script-loaded client entries: SSE rebuilt frames → invalidate/prefetch → fiber swap through the vendored Loader entry",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/locale/package.json b/packages/client/locale/package.json
index 739ab8110b..1de5c36ad5 100644
--- a/packages/client/locale/package.json
+++ b/packages/client/locale/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-locale",
   "description": "Locale plugin: Host-backed preference, extensible language catalog, browser fallback, and typed built-in dictionaries",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/modules/package.json b/packages/client/modules/package.json
index d0672fa18d..f9349f31a3 100644
--- a/packages/client/modules/package.json
+++ b/packages/client/modules/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-modules",
   "description": "Client module system, dual-face: node half composes the __DSH_BOOT__ entry graph (incremental dsh.client scan, bundle route, index tap, webPlugins service); browser half is the lazy-CJS module table the vendored cordis Loader consumes as its internal seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/store/package.json b/packages/client/store/package.json
index e3d64fcc0c..a0d44bd70f 100644
--- a/packages/client/store/package.json
+++ b/packages/client/store/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-store",
   "description": "React-free observable and snapshot-store contracts with the shared Zustand/Immer engine",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-agent-preset/package.json b/packages/client/ui-agent-preset/package.json
index 8a1d5540f3..3f7a158a1b 100644
--- a/packages/client/ui-agent-preset/package.json
+++ b/packages/client/ui-agent-preset/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-agent-preset",
   "description": "Agent-preset surfaces: the default for later sessions, this session's seat, and the composition editor",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-approval/package.json b/packages/client/ui-approval/package.json
index d28080371f..e79953516a 100644
--- a/packages/client/ui-approval/package.json
+++ b/packages/client/ui-approval/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-approval",
   "description": "Approval composer takeover over the scoped Remote Event waterfall",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-attachment/package.json b/packages/client/ui-attachment/package.json
index d92faee87b..fb6d39bf65 100644
--- a/packages/client/ui-attachment/package.json
+++ b/packages/client/ui-attachment/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-attachment",
   "description": "Dynamic attachment presentation plugin for conversation input, message-image, and trajectory image slots",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-brand-official/package.json b/packages/client/ui-brand-official/package.json
index c0b457b135..62ec39a204 100644
--- a/packages/client/ui-brand-official/package.json
+++ b/packages/client/ui-brand-official/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-brand-official",
   "description": "Official DeepSeek Harness brand occupants for the Web client's sidebar slots",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-chat/package.json b/packages/client/ui-chat/package.json
index e94269815a..8226e45380 100644
--- a/packages/client/ui-chat/package.json
+++ b/packages/client/ui-chat/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-chat",
   "description": "Chat Conversation target, node definitions, renderers, and details surface",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-commands/package.json b/packages/client/ui-commands/package.json
index 27d73f61eb..c7c0448ee9 100644
--- a/packages/client/ui-commands/package.json
+++ b/packages/client/ui-commands/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-commands",
   "description": "Client command surface: global directory cache, '/' source, three command UI kinds, popupSelect registry",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 3f0d12efdd..a8e73146af 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-conversation",
   "description": "Target-neutral Conversation assembly, shell, composer, queue, and view navigation",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-deliverables/package.json b/packages/client/ui-deliverables/package.json
index b5501d034b..44f7248e7d 100644
--- a/packages/client/ui-deliverables/package.json
+++ b/packages/client/ui-deliverables/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-deliverables",
   "description": "Produced-files turn tail and clickable final-response file references for Web",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-directory-picker-browse/package.json b/packages/client/ui-directory-picker-browse/package.json
index 7b172514c8..a30e4b90cc 100644
--- a/packages/client/ui-directory-picker-browse/package.json
+++ b/packages/client/ui-directory-picker-browse/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-directory-picker-browse",
   "description": "In-app directory browsing surface: the workspace directory-flow owner rendering the host's listing and creation primitives",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-directory-picker-native/package.json b/packages/client/ui-directory-picker-native/package.json
index 1a2d854b05..470c829b35 100644
--- a/packages/client/ui-directory-picker-native/package.json
+++ b/packages/client/ui-directory-picker-native/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-directory-picker-native",
   "description": "Native directory-picker surface: the renderless workspace directory-flow occupant driving the host's OS chooser",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-goal/package.json b/packages/client/ui-goal/package.json
index e5f04e48e7..b7d28df51b 100644
--- a/packages/client/ui-goal/package.json
+++ b/packages/client/ui-goal/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-goal",
   "description": "Session goal surface: GoalBar docked above the composer, read from the goal session projection",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-input-trigger/package.json b/packages/client/ui-input-trigger/package.json
index 5a01e3453d..8e87e0dec6 100644
--- a/packages/client/ui-input-trigger/package.json
+++ b/packages/client/ui-input-trigger/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-input-trigger",
   "description": "Input trigger pipeline: '/' and '@' detection, candidate menu, pick routing to registered sources",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-jobs/package.json b/packages/client/ui-jobs/package.json
index 338cc5e4bf..d3e3c31030 100644
--- a/packages/client/ui-jobs/package.json
+++ b/packages/client/ui-jobs/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-jobs",
   "description": "Session-header background-job list: live registry state mirrored from session/jobs frames",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
diff --git a/packages/client/ui-layout/package.json b/packages/client/ui-layout/package.json
index 4c1a0416b7..4a63c4e968 100644
--- a/packages/client/ui-layout/package.json
+++ b/packages/client/ui-layout/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-layout",
   "description": "Shell plugin: three-column AppFrame with drag handles, ctx.layout viewing-state service (navigation + panels)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-message-feedback/package.json b/packages/client/ui-message-feedback/package.json
index 82b59fb285..b2d0807e12 100644
--- a/packages/client/ui-message-feedback/package.json
+++ b/packages/client/ui-message-feedback/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-message-feedback",
   "description": "Per-message feedback controls contributed to the assistant-message action strip, backed by the messageFeedback Host Remote",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-model-selection/package.json b/packages/client/ui-model-selection/package.json
index 408ddf8e3f..84b4f3b5c7 100644
--- a/packages/client/ui-model-selection/package.json
+++ b/packages/client/ui-model-selection/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-model-selection",
   "description": "Model selection over the shared model catalog, Session projection, and session.selectModel",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-permission-presets/package.json b/packages/client/ui-permission-presets/package.json
index 3671f1623e..c05bd8d894 100644
--- a/packages/client/ui-permission-presets/package.json
+++ b/packages/client/ui-permission-presets/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-permission-presets",
   "description": "Permission surfaces: a new-session default in General settings and a current-session /permission popup over the permissions projection",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-plan/package.json b/packages/client/ui-plan/package.json
index 135c0db428..fd5a2dadc2 100644
--- a/packages/client/ui-plan/package.json
+++ b/packages/client/ui-plan/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-plan",
   "description": "Plan-mode composer control: the conversation.input.plan seat over the plan projection and the /plan command channel",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-primitives/package.json b/packages/client/ui-primitives/package.json
index 48d231bbb5..3206005953 100644
--- a/packages/client/ui-primitives/package.json
+++ b/packages/client/ui-primitives/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-primitives",
   "description": "Pure React atoms for the dsh web UI: controls, icons, markdown, and JSON inspectors (zero cordis)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-reference/package.json b/packages/client/ui-reference/package.json
index 9ef0d42535..20fdda586d 100644
--- a/packages/client/ui-reference/package.json
+++ b/packages/client/ui-reference/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-reference",
   "description": "Unified Web @file and @session reference source",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-renderer/package.json b/packages/client/ui-renderer/package.json
index 6dd17917d8..8d49ea11d4 100644
--- a/packages/client/ui-renderer/package.json
+++ b/packages/client/ui-renderer/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-renderer",
   "description": "Browser UI renderer: React slot bindings, ctx.uiRenderer, and the assembled application root",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-schedule/package.json b/packages/client/ui-schedule/package.json
index bd9548d9b4..7391fe6551 100644
--- a/packages/client/ui-schedule/package.json
+++ b/packages/client/ui-schedule/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-schedule",
   "description": "Read-only active Schedule catalog in the Web Session header",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
diff --git a/packages/client/ui-session/package.json b/packages/client/ui-session/package.json
index e383c0ad67..c1aa8090a3 100644
--- a/packages/client/ui-session/package.json
+++ b/packages/client/ui-session/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-session",
   "description": "Session Controller adapter for React and session-scoped slots",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-settings-general/package.json b/packages/client/ui-settings-general/package.json
index 9de1aa9a0a..24cf297b7d 100644
--- a/packages/client/ui-settings-general/package.json
+++ b/packages/client/ui-settings-general/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings-general",
   "description": "Settings ownerless-copy and product onboarding plugin: the General section, shell trigger/header chrome content, settings dictionaries, and the versioned welcome notice",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-settings-models/package.json b/packages/client/ui-settings-models/package.json
index b4152f3e33..6c983d881f 100644
--- a/packages/client/ui-settings-models/package.json
+++ b/packages/client/ui-settings-models/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings-models",
   "description": "Models settings and shared product-onboarding dialogs over existing settings and credential joins",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-settings-plugin-inventory/package.json b/packages/client/ui-settings-plugin-inventory/package.json
index 840ef95d10..0ee4218292 100644
--- a/packages/client/ui-settings-plugin-inventory/package.json
+++ b/packages/client/ui-settings-plugin-inventory/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings-plugin-inventory",
   "description": "Read-only Cordis Loader inventory tab in Web Plugins settings",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-settings-plugins/package.json b/packages/client/ui-settings-plugins/package.json
index 7ac6b4f194..c48afbddeb 100644
--- a/packages/client/ui-settings-plugins/package.json
+++ b/packages/client/ui-settings-plugins/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings-plugins",
   "description": "Plugins settings section with feature-owned tabs and configurable host-plane plugin cards",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-settings/package.json b/packages/client/ui-settings/package.json
index 9b038ed518..eba8fb5434 100644
--- a/packages/client/ui-settings/package.json
+++ b/packages/client/ui-settings/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings",
   "description": "Settings domain base plugin: the settings-namespace scope service and the canonical settings slot-type contract",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-sidebar/package.json b/packages/client/ui-sidebar/package.json
index 926bf5a4c1..1c82545cee 100644
--- a/packages/client/ui-sidebar/package.json
+++ b/packages/client/ui-sidebar/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-sidebar",
   "description": "Sidebar plugin: session multi-level tree, search, grouping, state dots",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-skill/package.json b/packages/client/ui-skill/package.json
index baa239713e..d95faad9ef 100644
--- a/packages/client/ui-skill/package.json
+++ b/packages/client/ui-skill/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-skill",
   "description": "Web skill references and the dedicated skill tool row",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-slots/package.json b/packages/client/ui-slots/package.json
index a5533321e2..741a154846 100644
--- a/packages/client/ui-slots/package.json
+++ b/packages/client/ui-slots/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-slots",
   "description": "Slot registry pure core: SlotMap declaration merging, single register composition API, four-share props types, store-seat types, renderer install seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-subagent/package.json b/packages/client/ui-subagent/package.json
index 419d7b25ea..e93425b433 100644
--- a/packages/client/ui-subagent/package.json
+++ b/packages/client/ui-subagent/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-subagent",
   "description": "Subagent conversation catalog, continuation routing UI, and '@' reference source",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-theme/package.json b/packages/client/ui-theme/package.json
index 405cd901b2..7b927856ec 100644
--- a/packages/client/ui-theme/package.json
+++ b/packages/client/ui-theme/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-theme",
   "description": "Theme plugin: Host bootstrap for the pre-plugin palette; DOM-free ThemeRuntime for light/dark/system state; --dsw-* token styles and Appearance settings row",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-tool/package.json b/packages/client/ui-tool/package.json
index 581d0dfeb8..d745d005c5 100644
--- a/packages/client/ui-tool/package.json
+++ b/packages/client/ui-tool/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-tool",
   "description": "Client Tool call-tree renderer and keyed per-tool presentation slot",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-trajectory/package.json b/packages/client/ui-trajectory/package.json
index e12e09a4a5..24c2906800 100644
--- a/packages/client/ui-trajectory/package.json
+++ b/packages/client/ui-trajectory/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-trajectory",
   "description": "Trajectory event ledger with an interactive timing overview: pure-consumer plugin registering into the conversation ViewMap (no service)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-user-questions/package.json b/packages/client/ui-user-questions/package.json
index ab087c3da8..a85dc2a477 100644
--- a/packages/client/ui-user-questions/package.json
+++ b/packages/client/ui-user-questions/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-user-questions",
   "description": "Web ask_user_question composer takeover and plan-review presentation UI",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-workflow-run/package.json b/packages/client/ui-workflow-run/package.json
index b4ba784a58..27151a3dc1 100644
--- a/packages/client/ui-workflow-run/package.json
+++ b/packages/client/ui-workflow-run/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-workflow-run",
   "description": "Durable workflow-run Conversation Node and nested member disclosure for dsh web",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/ui-workspace/package.json b/packages/client/ui-workspace/package.json
index b5adbb19bf..3ae0b8cc27 100644
--- a/packages/client/ui-workspace/package.json
+++ b/packages/client/ui-workspace/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-workspace",
   "description": "Workspace picker plugin: one WorkspacePicker registered into the sidebar and empty-state workspace slots",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/client/web/package.json b/packages/client/web/package.json
index b9474ee807..1d73253e9b 100644
--- a/packages/client/web/package.json
+++ b/packages/client/web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-web",
   "description": "Web boot kernel: static module table, Cordis loader, framework-free boot page, and UI-renderer handoff",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/code-runtime/code-runtime-worker-thread/package.json b/packages/code-runtime/code-runtime-worker-thread/package.json
index c01fa451b4..7e4a5f9267 100644
--- a/packages/code-runtime/code-runtime-worker-thread/package.json
+++ b/packages/code-runtime/code-runtime-worker-thread/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-code-runtime-worker-thread",
   "description": "Worker-thread implementation of the DeepSeek Harness code-execution seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/code-runtime/code-runtime/package.json b/packages/code-runtime/code-runtime/package.json
index 9545aba735..f458ee2162 100644
--- a/packages/code-runtime/code-runtime/package.json
+++ b/packages/code-runtime/code-runtime/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-code-runtime",
   "description": "Abstract code-execution seam (ctx.codeRuntime) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/compaction/command-compact/package.json b/packages/compaction/command-compact/package.json
index 12293889cb..167a207365 100644
--- a/packages/compaction/command-compact/package.json
+++ b/packages/compaction/command-compact/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-command-compact",
   "description": "Human-facing slash command for explicit session compaction",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/compaction/compaction-basic/package.json b/packages/compaction/compaction-basic/package.json
index afb153113d..d14a54e685 100644
--- a/packages/compaction/compaction-basic/package.json
+++ b/packages/compaction/compaction-basic/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-compaction-basic",
   "description": "Token-meter-driven compaction policy and LLM summarization backend for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/compaction/compaction-tool-result-pruner/package.json b/packages/compaction/compaction-tool-result-pruner/package.json
index 6c0222c04a..a02e77184b 100644
--- a/packages/compaction/compaction-tool-result-pruner/package.json
+++ b/packages/compaction/compaction-tool-result-pruner/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-compaction-tool-result-pruner",
   "description": "Replay-safe model-free head/middle/tail pruning for tool-result surface nodes",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/compaction/compaction/package.json b/packages/compaction/compaction/package.json
index 7dec4528ca..3d9c756297 100644
--- a/packages/compaction/compaction/package.json
+++ b/packages/compaction/compaction/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-compaction",
   "description": "Abstract compaction service seam (ctx.compaction) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/context/agent-instructions/package.json b/packages/context/agent-instructions/package.json
index a785eaa4cc..96ec478374 100644
--- a/packages/context/agent-instructions/package.json
+++ b/packages/context/agent-instructions/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-agent-instructions",
   "description": "Workspace context loader for AGENTS.md/CLAUDE.md instruction files",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/context/file-reference-local/package.json b/packages/context/file-reference-local/package.json
index 08f52af359..19869fb842 100644
--- a/packages/context/file-reference-local/package.json
+++ b/packages/context/file-reference-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-file-reference-local",
   "description": "Local-filesystem ctx.fileReferences provider with bounded fuzzy indexes",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/context/file-reference/package.json b/packages/context/file-reference/package.json
index 14e8eb9c8c..a01b6fea8a 100644
--- a/packages/context/file-reference/package.json
+++ b/packages/context/file-reference/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-file-reference",
   "description": "File-reference discovery contract and shared @file grammar",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/context/session-reference/package.json b/packages/context/session-reference/package.json
index 9fe631f399..ec2755683c 100644
--- a/packages/context/session-reference/package.json
+++ b/packages/context/session-reference/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-reference",
   "description": "Cross-session snapshot references and durable untrusted model context (ctx.sessionReferenceResolver)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/context/time-context/package.json b/packages/context/time-context/package.json
index 76f3550933..3bb8e9f281 100644
--- a/packages/context/time-context/package.json
+++ b/packages/context/time-context/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-time-context",
   "description": "Opt-in durable per-step context with the current time and elapsed time",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/context/tmux-context/package.json b/packages/context/tmux-context/package.json
index 392ddd266a..3e35684111 100644
--- a/packages/context/tmux-context/package.json
+++ b/packages/context/tmux-context/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tmux-context",
   "description": "Opt-in durable per-step context with this agent's tmux pane and window location",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/core/agent-default-model/package.json b/packages/core/agent-default-model/package.json
index 9fc5b7be9c..953074cb37 100644
--- a/packages/core/agent-default-model/package.json
+++ b/packages/core/agent-default-model/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-agent-default-model",
   "description": "Default model selection shared by Agent entry points",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/core/agent-loop/package.json b/packages/core/agent-loop/package.json
index 7df2edd3e0..3df5296e30 100644
--- a/packages/core/agent-loop/package.json
+++ b/packages/core/agent-loop/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-agent-loop",
   "description": "The concrete agent loop plugin for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/core/agent-tool-presentation/package.json b/packages/core/agent-tool-presentation/package.json
index 80f96eb88d..9b553895ed 100644
--- a/packages/core/agent-tool-presentation/package.json
+++ b/packages/core/agent-tool-presentation/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-agent-tool-presentation",
   "description": "Agent-plane presentation selector: composes one agent's tools as PTC mode, native, or both",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json
index 483d8c9eba..49b8612baf 100644
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-agent",
   "description": "Agent interface, registry, initiator scope, and event vocabulary for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/core/scope/package.json b/packages/core/scope/package.json
index a754c15c34..88dcf337e6 100644
--- a/packages/core/scope/package.json
+++ b/packages/core/scope/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-scope",
   "description": "Scoped-context registration primitive (scope tags, scope-filtered event dispatch) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/core/session/package.json b/packages/core/session/package.json
index 3e4be78030..4d4805f4b6 100644
--- a/packages/core/session/package.json
+++ b/packages/core/session/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/core/system-prompt/package.json b/packages/core/system-prompt/package.json
index 0844250704..312e27bafa 100644
--- a/packages/core/system-prompt/package.json
+++ b/packages/core/system-prompt/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-system-prompt",
   "description": "System prompt assembly registry for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/core/tools/package.json b/packages/core/tools/package.json
index 7a54429077..b22274e4aa 100644
--- a/packages/core/tools/package.json
+++ b/packages/core/tools/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tools",
   "description": "Tool registry and execution pipeline for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/credentials/authorization/package.json b/packages/credentials/authorization/package.json
index 42addb36fe..eec2248f0b 100644
--- a/packages/credentials/authorization/package.json
+++ b/packages/credentials/authorization/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-authorization",
   "description": "Authorization seam (ctx.authorization): plugin-owned flows that obtain a credential through a conversation with the human",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/credentials/credentials-local/package.json b/packages/credentials/credentials-local/package.json
index d45bf637e7..006e862171 100644
--- a/packages/credentials/credentials-local/package.json
+++ b/packages/credentials/credentials-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-credentials-local",
   "description": "File-backed credentials provider ($DSH_HOME/.env under the live process environment) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/credentials/credentials/package.json b/packages/credentials/credentials/package.json
index ed04cd225d..d1725fc989 100644
--- a/packages/credentials/credentials/package.json
+++ b/packages/credentials/credentials/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-credentials",
   "description": "Abstract credential seam (ctx.credentials): settings carry references to secrets, providers own the values",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
index a1aa7efb95..c25b5dcbf8 100644
--- a/packages/e2b/e2b/package.json
+++ b/packages/e2b/e2b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-e2b",
   "description": "Shared E2B sandbox lifecycle for DeepSeek Harness provider adapters",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/e2b/fs-e2b/package.json b/packages/e2b/fs-e2b/package.json
index 8c5fe3f6fe..5b9a76bdb3 100644
--- a/packages/e2b/fs-e2b/package.json
+++ b/packages/e2b/fs-e2b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-fs-e2b",
   "description": "E2B filesystem implementation for DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/e2b/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
index c9f5676ba0..ab11e46bf3 100644
--- a/packages/e2b/subprocess-e2b/package.json
+++ b/packages/e2b/subprocess-e2b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subprocess-e2b",
   "description": "E2B subprocess implementation for DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/experimental/agent-team-profile/package.json b/packages/experimental/agent-team-profile/package.json
index 69314dc11f..b0fff7c17c 100644
--- a/packages/experimental/agent-team-profile/package.json
+++ b/packages/experimental/agent-team-profile/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-agent-team-profile",
   "description": "Private profile bundle enabling Agent Teams over dsh-base",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "private": true,
   "repository": {
     "type": "git",
diff --git a/packages/experimental/agent-team-web-profile/package.json b/packages/experimental/agent-team-web-profile/package.json
index d4a8eea221..32be82b680 100644
--- a/packages/experimental/agent-team-web-profile/package.json
+++ b/packages/experimental/agent-team-web-profile/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-agent-team-web-profile",
   "description": "Private Web profile layer for Agent Teams Remote and UI plugins",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "private": true,
   "repository": {
     "type": "git",
diff --git a/packages/experimental/agent-team/package.json b/packages/experimental/agent-team/package.json
index 8d083c2723..35ba66e338 100644
--- a/packages/experimental/agent-team/package.json
+++ b/packages/experimental/agent-team/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-agent-team",
   "description": "Implicit-root Agent Teams roster, durable peer mailbox, and shared task DAG",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "private": true,
   "repository": {
     "type": "git",
diff --git a/packages/experimental/client-ui-agent-team/package.json b/packages/experimental/client-ui-agent-team/package.json
index 6629c62888..7e03052ea9 100644
--- a/packages/experimental/client-ui-agent-team/package.json
+++ b/packages/experimental/client-ui-agent-team/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-client-ui-agent-team",
   "description": "Web Agent Teams roster, task board, and teammate navigation",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "private": true,
   "repository": {
     "type": "git",
diff --git a/packages/experimental/code-runtime-python/package.json b/packages/experimental/code-runtime-python/package.json
index fe1e1c9e94..188128bf50 100644
--- a/packages/experimental/code-runtime-python/package.json
+++ b/packages/experimental/code-runtime-python/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-code-runtime-python",
   "description": "CPython subprocess implementation of the DeepSeek Harness code-execution seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
diff --git a/packages/experimental/inspector/package.json b/packages/experimental/inspector/package.json
index d88d6264f4..96363ede0b 100644
--- a/packages/experimental/inspector/package.json
+++ b/packages/experimental/inspector/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-inspector",
   "description": "Experimental cross-realm CDP hub for Host debugging and Client Runtime inspection",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "private": true,
   "repository": {
     "type": "git",
diff --git a/packages/experimental/tool-agent-team/package.json b/packages/experimental/tool-agent-team/package.json
index 145c5bcf25..e2b012d1ba 100644
--- a/packages/experimental/tool-agent-team/package.json
+++ b/packages/experimental/tool-agent-team/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-tool-agent-team",
   "description": "Scoped model-facing Agent Teams tools over ctx.agentTeams",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "private": true,
   "repository": {
     "type": "git",
diff --git a/packages/experimental/webworker-packer/package.json b/packages/experimental/webworker-packer/package.json
index c9e58381e1..61837e941b 100644
--- a/packages/experimental/webworker-packer/package.json
+++ b/packages/experimental/webworker-packer/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-webworker-packer",
   "description": "Build-time packer for the browser runtime's base VFS image and ordered data-overlay archives",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "private": true,
   "repository": {
     "type": "git",
diff --git a/packages/experimental/webworker-runtime/package.json b/packages/experimental/webworker-runtime/package.json
index 782e5ccddf..57b33b5d22 100644
--- a/packages/experimental/webworker-runtime/package.json
+++ b/packages/experimental/webworker-runtime/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-webworker-runtime",
   "description": "Browser-only harness runtime: in-memory VFS, module transform and loader, postMessage tunnel, and the dedicated Web Worker assembly, with the Node-compatibility layer that lets the host tree run unchanged",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "private": true,
   "repository": {
     "type": "git",
diff --git a/packages/extensions/cordis-client-runner/package.json b/packages/extensions/cordis-client-runner/package.json
index 947af0d02b..1236cfac34 100644
--- a/packages/extensions/cordis-client-runner/package.json
+++ b/packages/extensions/cordis-client-runner/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-cordis-client-runner",
   "description": "Browser half of dynamic dual-half plugin packages: event subscription, closure evaluation, guard facade, and loader entries",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/extensions/cordis-host-runner/package.json b/packages/extensions/cordis-host-runner/package.json
index 74c39bfd52..d53f017417 100644
--- a/packages/extensions/cordis-host-runner/package.json
+++ b/packages/extensions/cordis-host-runner/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-cordis-host-runner",
   "description": "Dynamic package definition registry, host-half sandbox lifecycle, and invoke handler table for model-mounted dual-half packages",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/extensions/tool-cordis/package.json b/packages/extensions/tool-cordis/package.json
index 1759d36c7f..855e6aedd1 100644
--- a/packages/extensions/tool-cordis/package.json
+++ b/packages/extensions/tool-cordis/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-cordis",
   "description": "Self-referential cordis toolset: inspect the live runtime, mount and dispose model-written plugins",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/extensions/ui-cordis/package.json b/packages/extensions/ui-cordis/package.json
index 7e7f3b7171..a2b1207a37 100644
--- a/packages/extensions/ui-cordis/package.json
+++ b/packages/extensions/ui-cordis/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-cordis",
   "description": "Cordis dynamic-plugin definition card: the keyed cordis_define tool row with its run/stop switch",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/feedback/command-feedback/package.json b/packages/feedback/command-feedback/package.json
index 60597b87cb..1b6b1e869b 100644
--- a/packages/feedback/command-feedback/package.json
+++ b/packages/feedback/command-feedback/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-command-feedback",
   "description": "Log-only session feedback producer and human-facing slash command",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/feedback/message-feedback/package.json b/packages/feedback/message-feedback/package.json
index 9ce5d934c2..594bb6a355 100644
--- a/packages/feedback/message-feedback/package.json
+++ b/packages/feedback/message-feedback/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-message-feedback",
   "description": "Lifecycle-bound per-message rating and note sidecar for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/fs/fs-local/package.json b/packages/fs/fs-local/package.json
index 2ea22eba4a..63c975a09a 100644
--- a/packages/fs/fs-local/package.json
+++ b/packages/fs/fs-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-fs-local",
   "description": "Local-filesystem implementation of the DeepSeek Harness filesystem seam (ctx.fs)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/fs/fs-observation-policy/package.json b/packages/fs/fs-observation-policy/package.json
index 4c24963319..09c3492c3b 100644
--- a/packages/fs/fs-observation-policy/package.json
+++ b/packages/fs/fs-observation-policy/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-fs-observation-policy",
   "description": "File-context policy plugin for the DeepSeek Harness — observed-state, read-before-edit, and version-guarded write/edit added over the ctx.fs provider seam through the fs/* event gate (no service API)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/fs/fs-sandbox/package.json b/packages/fs/fs-sandbox/package.json
index 31ec13c0aa..3b496f360e 100644
--- a/packages/fs/fs-sandbox/package.json
+++ b/packages/fs/fs-sandbox/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-fs-sandbox",
   "description": "Sandbox-enforcing implementation of the DeepSeek Harness filesystem seam: fences write/edit by the per-call sandbox mode (read-only denies mutation, workspace-write contains it to the workspace + temp roots) while reads pass through",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/fs/fs/package.json b/packages/fs/fs/package.json
index aefd3d759b..2584772eb8 100644
--- a/packages/fs/fs/package.json
+++ b/packages/fs/fs/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-fs",
   "description": "Abstract filesystem capability seam (ctx.fs) for the DeepSeek Harness — vocabulary types, the FileSystem service (text IO + optional version-guarded atomic mutations), and the fs/* policy event vocabulary",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/fs/tool-fs-search/package.json b/packages/fs/tool-fs-search/package.json
index 1fdd00df64..776f129dc1 100644
--- a/packages/fs/tool-fs-search/package.json
+++ b/packages/fs/tool-fs-search/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-fs-search",
   "description": "Model-facing filesystem discovery tools (glob, grep) backed by the packaged ripgrep binary (@vscode/ripgrep)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/fs/tool-fs/package.json b/packages/fs/tool-fs/package.json
index bec2796820..bd6c0fbb40 100644
--- a/packages/fs/tool-fs/package.json
+++ b/packages/fs/tool-fs/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-fs",
   "description": "Model-facing filesystem tools (read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/fs/tool-str-replace-editor/package.json b/packages/fs/tool-str-replace-editor/package.json
index 000a93f02f..cb89959c89 100644
--- a/packages/fs/tool-str-replace-editor/package.json
+++ b/packages/fs/tool-str-replace-editor/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-str-replace-editor",
   "description": "Model-facing view, create, literal replace, and line insert tool over the Harness filesystem service",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/goal/command-goal/package.json b/packages/goal/command-goal/package.json
index 3dd62e14de..36bafa1d0b 100644
--- a/packages/goal/command-goal/package.json
+++ b/packages/goal/command-goal/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-command-goal",
   "description": "Human-facing slash command for persisted same-session goals",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/goal/goal-round-driver/package.json b/packages/goal/goal-round-driver/package.json
index fed2823aca..4169d63dd7 100644
--- a/packages/goal/goal-round-driver/package.json
+++ b/packages/goal/goal-round-driver/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-goal-round-driver",
   "description": "Race-fenced same-session goal-round driver",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/goal/goal/package.json b/packages/goal/goal/package.json
index 819bdd2a15..2770c53221 100644
--- a/packages/goal/goal/package.json
+++ b/packages/goal/goal/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-goal",
   "description": "Event-sourced same-session goal state and lifecycle service for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/goal/tool-goal/package.json b/packages/goal/tool-goal/package.json
index da00f98a8a..b35bc1bf14 100644
--- a/packages/goal/tool-goal/package.json
+++ b/packages/goal/tool-goal/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-goal",
   "description": "Model-facing same-session goal tools with execution-time authority checks",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/guard/repeat-tool-reminder/package.json b/packages/guard/repeat-tool-reminder/package.json
index 3cabf70ff1..3ce8a31a8e 100644
--- a/packages/guard/repeat-tool-reminder/package.json
+++ b/packages/guard/repeat-tool-reminder/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-repeat-tool-reminder",
   "description": "Repeat-tool-call guard plugin: advisory reminders when an agent loops on identical tool calls",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/guard/timeout-policy/package.json b/packages/guard/timeout-policy/package.json
index b52f95b864..82e4eda1f4 100644
--- a/packages/guard/timeout-policy/package.json
+++ b/packages/guard/timeout-policy/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-call-timeout-policy",
   "description": "Tool-call timeout policy: a tools/execute wrapper that arms a per-tool deadline on exec.signal and returns TOOL_TIMEOUT when it wins",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/hooks/hook-protocol/package.json b/packages/hooks/hook-protocol/package.json
index d3b689ca6c..1bc5a5cb71 100644
--- a/packages/hooks/hook-protocol/package.json
+++ b/packages/hooks/hook-protocol/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-hook-protocol",
   "description": "Shared Claude Code / Codex hook wire protocol: matcher engine, stdin/exit-code/stdout codec, multi-hook merge, and hook/* session events",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/hooks/hooks-claude-code/package.json b/packages/hooks/hooks-claude-code/package.json
index 1514cb9da6..fe735edd9a 100644
--- a/packages/hooks/hooks-claude-code/package.json
+++ b/packages/hooks/hooks-claude-code/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-hooks-claude-code",
   "description": "Bridge plugin: run a Claude Code hooks.json / settings hook config on the DeepSeek Harness interception seams",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/hooks/hooks-codex/package.json b/packages/hooks/hooks-codex/package.json
index affd0cce6d..f0c96eeb14 100644
--- a/packages/hooks/hooks-codex/package.json
+++ b/packages/hooks/hooks-codex/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-hooks-codex",
   "description": "Bridge plugin: run a Codex hooks.json hook config on the DeepSeek Harness interception seams",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/host/directory-picker-auto/package.json b/packages/host/directory-picker-auto/package.json
index 9e24c4db3a..a4cf3d86ef 100644
--- a/packages/host/directory-picker-auto/package.json
+++ b/packages/host/directory-picker-auto/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-directory-picker-auto",
   "description": "Adaptive chooser of the directory-picker seam: resolves the host situation at boot and mounts the native or browse backend for the DeepSeek Harness web GUI host",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/host/directory-picker-browse/package.json b/packages/host/directory-picker-browse/package.json
index a4c72958d1..76fb715690 100644
--- a/packages/host/directory-picker-browse/package.json
+++ b/packages/host/directory-picker-browse/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-directory-picker-browse",
   "description": "In-app browsing backend of the directory-picker seam (listing/creation primitives over the host filesystem)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/host/directory-picker-native/package.json b/packages/host/directory-picker-native/package.json
index 1dbd2566e1..06044425ae 100644
--- a/packages/host/directory-picker-native/package.json
+++ b/packages/host/directory-picker-native/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-directory-picker-native",
   "description": "Native-OS-chooser backend of the directory-picker seam for the DeepSeek Harness web GUI host",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/host/directory-picker/package.json b/packages/host/directory-picker/package.json
index c6f82115da..fbf77d3b35 100644
--- a/packages/host/directory-picker/package.json
+++ b/packages/host/directory-picker/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-directory-picker",
   "description": "Abstract workspace-directory picking seam (ctx.directoryPicker) for the DeepSeek Harness web GUI host",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/host/frontend-static/package.json b/packages/host/frontend-static/package.json
index aaf5219df4..bb32254def 100644
--- a/packages/host/frontend-static/package.json
+++ b/packages/host/frontend-static/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-frontend-static",
   "description": "SPA dist server for the Web shell: owns the webserver fallback seat, serving explicit index entries and static assets with traversal rejection and 404 misses",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/host/plugin-inventory/package.json b/packages/host/plugin-inventory/package.json
index dd866ecac8..0bc31715d8 100644
--- a/packages/host/plugin-inventory/package.json
+++ b/packages/host/plugin-inventory/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-plugin-inventory",
   "description": "Read-only Remote projection of current Cordis Loader plugin state",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/host/webserver/package.json b/packages/host/webserver/package.json
index dab96c4973..9bade860f3 100644
--- a/packages/host/webserver/package.json
+++ b/packages/host/webserver/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-webserver",
   "description": "Web route-registration plugin: HTTP and upgrade routes, index transform taps, and static dist fallback; knows no harness concepts",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/identity/anonymous-user-id/package.json b/packages/identity/anonymous-user-id/package.json
index 770423bc6e..8489124caf 100644
--- a/packages/identity/anonymous-user-id/package.json
+++ b/packages/identity/anonymous-user-id/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-anonymous-user-id",
   "description": "Shared anonymous user identity for DeepSeek Harness telemetry and feedback correlation",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/interaction/commands/package.json b/packages/interaction/commands/package.json
index c3ebb0305a..6900a383c2 100644
--- a/packages/interaction/commands/package.json
+++ b/packages/interaction/commands/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-commands",
   "description": "Plugin-owned human command registry for DeepSeek Harness UIs",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/interaction/permission-presets/package.json b/packages/interaction/permission-presets/package.json
index 65f17dd8e7..fd6cb5b225 100644
--- a/packages/interaction/permission-presets/package.json
+++ b/packages/interaction/permission-presets/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-permission-presets",
   "description": "User-facing permission presets (ctx.permissionPresets) for the DeepSeek Harness: one product-level Permissions select bundling the sandbox-mode and approval-policy knobs, written through to their own session events",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/interaction/tool-ask-user/package.json b/packages/interaction/tool-ask-user/package.json
index 25fc9d60c5..b76839104e 100644
--- a/packages/interaction/tool-ask-user/package.json
+++ b/packages/interaction/tool-ask-user/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-ask-user",
   "description": "Model-facing ask_user_question tool over the ctx.userQuestions seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/interaction/user-approval/package.json b/packages/interaction/user-approval/package.json
index a4bd9e8d28..3983fa725b 100644
--- a/packages/interaction/user-approval/package.json
+++ b/packages/interaction/user-approval/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-user-approval",
   "description": "User-approval seam (ctx.approval) for the DeepSeek Harness: one-shot permission decisions dispatched to composed answerers over the approval/request waterfall, fail-closed by default",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/interaction/user-questions/package.json b/packages/interaction/user-questions/package.json
index a65665f0ab..a9c32ec8f0 100644
--- a/packages/interaction/user-questions/package.json
+++ b/packages/interaction/user-questions/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-user-questions",
   "description": "Abstract user-questions seam (ctx.userQuestions) for asking the human during agent runs",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/jobs/jobs-local/package.json b/packages/jobs/jobs-local/package.json
index 65ed7a09a6..f2d9acda50 100644
--- a/packages/jobs/jobs-local/package.json
+++ b/packages/jobs/jobs-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-jobs-local",
   "description": "Process-local implementation of the DeepSeek Harness background job registry seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/jobs/jobs/package.json b/packages/jobs/jobs/package.json
index 265f002981..2c03ff7e48 100644
--- a/packages/jobs/jobs/package.json
+++ b/packages/jobs/jobs/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-jobs",
   "description": "Background job registry (ctx.jobs) for the DeepSeek Harness — shared ids, owner isolation, polling, cancellation, and completion listeners for long-running tool work",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/jobs/tool-jobs/package.json b/packages/jobs/tool-jobs/package.json
index 29f84f44cb..c9893a441e 100644
--- a/packages/jobs/tool-jobs/package.json
+++ b/packages/jobs/tool-jobs/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-jobs",
   "description": "Model-facing background job control tools (job_output, job_list, job_kill) over the ctx.jobs registry",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/llm/deepseek-llm-api-extensions/package.json b/packages/llm/deepseek-llm-api-extensions/package.json
index 63ea6a85db..97c360d6f4 100644
--- a/packages/llm/deepseek-llm-api-extensions/package.json
+++ b/packages/llm/deepseek-llm-api-extensions/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-deepseek-llm-api-extensions",
   "description": "Additive request-field registry for the official DeepSeek LLM API adapter",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/llm/llm-deepseek/package.json b/packages/llm/llm-deepseek/package.json
index 7c42284248..a6978971ce 100644
--- a/packages/llm/llm-deepseek/package.json
+++ b/packages/llm/llm-deepseek/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm-deepseek",
   "description": "DeepSeek chat-completions adapter for the DeepSeek Harness LLM seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/llm/llm-pi-ai/package.json b/packages/llm/llm-pi-ai/package.json
index 02cdffdf0f..923654f98e 100644
--- a/packages/llm/llm-pi-ai/package.json
+++ b/packages/llm/llm-pi-ai/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm-pi-ai",
   "description": "pi-ai-backed DeepSeek adapter for the DeepSeek Harness LLM seam (design-verification twin of dsh-llm-deepseek)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/llm/llm-retry/package.json b/packages/llm/llm-retry/package.json
index cfd134f485..f1456d143e 100644
--- a/packages/llm/llm-retry/package.json
+++ b/packages/llm/llm-retry/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm-retry",
   "description": "Provider-routed LLM request retry policy for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/llm/llm/package.json b/packages/llm/llm/package.json
index ce1a4c466a..15aa6cddf4 100644
--- a/packages/llm/llm/package.json
+++ b/packages/llm/llm/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm",
   "description": "Provider-neutral LLM service interface for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/llm/plugin-package-inventory-deepseek/package.json b/packages/llm/plugin-package-inventory-deepseek/package.json
index 444c5f3f32..3af4e53894 100644
--- a/packages/llm/plugin-package-inventory-deepseek/package.json
+++ b/packages/llm/plugin-package-inventory-deepseek/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-plugin-package-inventory-deepseek",
   "description": "Active Loader-backed plugin package inventory for official DeepSeek LLM API requests",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/llm/token-meter/package.json b/packages/llm/token-meter/package.json
index 027a241e3f..0fe423246f 100644
--- a/packages/llm/token-meter/package.json
+++ b/packages/llm/token-meter/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-token-meter",
   "description": "Replay-aware token measurement service (ctx.tokenMeter) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/lsp/lsp-stdio/package.json b/packages/lsp/lsp-stdio/package.json
index 983bcec9cf..3d5b3bea02 100644
--- a/packages/lsp/lsp-stdio/package.json
+++ b/packages/lsp/lsp-stdio/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-lsp-stdio",
   "description": "Generic stdio language-server provider for the DeepSeek Harness LSP capability seam (ctx.lsp) — spawns configured servers, translates JSON-RPC, and serves transient-open goToDefinition/findReferences/goToImplementation/hover queries in the host filesystem namespace",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/lsp/lsp/package.json b/packages/lsp/lsp/package.json
index c56210657f..8a1cbf9972 100644
--- a/packages/lsp/lsp/package.json
+++ b/packages/lsp/lsp/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-lsp",
   "description": "Abstract LSP capability seam (ctx.lsp) for the DeepSeek Harness — language-server provider registry keyed by branded id and extension mapping, order-independent per-query selection, normalized definition/references/implementation/hover requests and results, and the LspError taxonomy",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/lsp/tool-lsp/package.json b/packages/lsp/tool-lsp/package.json
index fe21fa9991..d31a6465f5 100644
--- a/packages/lsp/tool-lsp/package.json
+++ b/packages/lsp/tool-lsp/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-lsp",
   "description": "Model-facing lsp tool over the DeepSeek Harness LSP capability seam (ctx.lsp) — one read-only tool with goToDefinition/findReferences/goToImplementation/hover operations, one-based UTF-16 cursor coordinates, bounded location rendering, and hover normalization",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/mcp/mcp-client/package.json b/packages/mcp/mcp-client/package.json
index 79d78bae8e..badc29437d 100644
--- a/packages/mcp/mcp-client/package.json
+++ b/packages/mcp/mcp-client/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-mcp-client",
   "description": "MCP client bridge: connects to MCP servers and registers their tools on ctx.tools",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/plan/plan-mode/package.json b/packages/plan/plan-mode/package.json
index c78fcb10e2..a28bf79dd9 100644
--- a/packages/plan/plan-mode/package.json
+++ b/packages/plan/plan-mode/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-plan-mode",
   "description": "Logged per-agent plan mode with deployment guidance, a direct slash command, and a user-reviewed exit",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/preset/agent-presets/package.json b/packages/preset/agent-presets/package.json
index 92fa0d62ba..ffda101c80 100644
--- a/packages/preset/agent-presets/package.json
+++ b/packages/preset/agent-presets/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-agent-presets",
   "description": "Per-session agent composition from preset cordis.yml files for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/preset/persona/package.json b/packages/preset/persona/package.json
index d2447cb467..67480ddd74 100644
--- a/packages/preset/persona/package.json
+++ b/packages/preset/persona/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-persona",
   "description": "Composition-authored deployment persona section for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/runtime-diagnostics/invariants/package.json b/packages/runtime-diagnostics/invariants/package.json
index 0c05b9d91c..4a6ecf7d2a 100644
--- a/packages/runtime-diagnostics/invariants/package.json
+++ b/packages/runtime-diagnostics/invariants/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-invariants",
   "description": "Registry service for package-owned DeepSeek Harness runtime invariants",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/sandbox/sandbox-local/package.json b/packages/sandbox/sandbox-local/package.json
index c35ee48c22..6135d81948 100644
--- a/packages/sandbox/sandbox-local/package.json
+++ b/packages/sandbox/sandbox-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sandbox-local",
   "description": "Local process-sandbox backends for the DeepSeek Harness sandbox seam: bwrap, the npm-distributed landlock-run launcher, macOS Seatbelt, or the Windows ACL restricted-token runner — functionally probed, fail-closed",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/sandbox/sandbox-policy/package.json b/packages/sandbox/sandbox-policy/package.json
index 62e1f278a7..aca9b6b291 100644
--- a/packages/sandbox/sandbox-policy/package.json
+++ b/packages/sandbox/sandbox-policy/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sandbox-policy",
   "description": "Per-call sandbox policy resolver and current model context: deployment fallbacks plus each session's mode and workspace root, shared by every enforcing capability family",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/sandbox/sandbox-windows-acl/package.json b/packages/sandbox/sandbox-windows-acl/package.json
index a35e4bd547..92569fbcc2 100644
--- a/packages/sandbox/sandbox-windows-acl/package.json
+++ b/packages/sandbox/sandbox-windows-acl/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sandbox-windows-acl",
   "description": "Windows ACL write-restriction sandbox backend (restricted-token spawn with capability-SID write allowlist) for the DeepSeek Harness sandbox seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/sandbox/sandbox/package.json b/packages/sandbox/sandbox/package.json
index 153cfc8be1..0a55d592b1 100644
--- a/packages/sandbox/sandbox/package.json
+++ b/packages/sandbox/sandbox/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sandbox",
   "description": "Abstract process-sandbox seam (ctx.sandbox) for the DeepSeek Harness: same-world confinement vocabulary and the SandboxProvider contract",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/schedule/schedule/package.json b/packages/schedule/schedule/package.json
index bbeca31693..a91310aba1 100644
--- a/packages/schedule/schedule/package.json
+++ b/packages/schedule/schedule/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-schedule",
   "description": "Agent-scoped durable after, at, and fixed-rate reminders over the session event log",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/sdk/client/package.json b/packages/sdk/client/package.json
index 1bfe2e5730..806593fe8b 100644
--- a/packages/sdk/client/package.json
+++ b/packages/sdk/client/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sdk-client",
   "description": "TypeScript client SDK for driving a DeepSeek Harness runtime subprocess over stdio JSON-RPC: the DeepSeekHarness high-level turns API and the lower-level HarnessClient",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/sdk/protocol/package.json b/packages/sdk/protocol/package.json
index 3d725cf2ca..854fd9ec48 100644
--- a/packages/sdk/protocol/package.json
+++ b/packages/sdk/protocol/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sdk-protocol",
   "description": "Shared wire protocol for the DeepSeek Harness SDK runtime: the newline-delimited JSON-RPC stdio transport and the named request, result, and notification types spoken between the runtime server and SDK clients",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/sdk/server/package.json b/packages/sdk/server/package.json
index 4036246e61..163217d352 100644
--- a/packages/sdk/server/package.json
+++ b/packages/sdk/server/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sdk-jsonrpc-server",
   "description": "Stdio JSON-RPC server plugin for out-of-process DeepSeek Harness SDK clients",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session-query/session-log-export/package.json b/packages/session-query/session-log-export/package.json
index 9fd76fcf84..468e59ffb8 100644
--- a/packages/session-query/session-log-export/package.json
+++ b/packages/session-query/session-log-export/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-log-export",
   "description": "Web Session-log export command and shared download dialog",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session-query/session-query-sqlite/package.json b/packages/session-query/session-query-sqlite/package.json
index dc97d845fe..b637b13a7e 100644
--- a/packages/session-query/session-query-sqlite/package.json
+++ b/packages/session-query/session-query-sqlite/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-query-sqlite",
   "description": "Concrete ctx.sessionQuery backend with SQLite FTS5 search",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session-query/session-query/package.json b/packages/session-query/session-query/package.json
index a9a8fca896..14013226c3 100644
--- a/packages/session-query/session-query/package.json
+++ b/packages/session-query/session-query/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-query",
   "description": "Combined session query service contract with concrete reads, traces, and filters",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session-query/tool-session-query/package.json b/packages/session-query/tool-session-query/package.json
index 380d71864e..e6291db04a 100644
--- a/packages/session-query/tool-session-query/package.json
+++ b/packages/session-query/tool-session-query/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-session-query",
   "description": "Workspace-authorized model-facing session history search, trace, and event read tools",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-checkpoint-policy/package.json b/packages/session/session-checkpoint-policy/package.json
index 967235b31e..7f3533befe 100644
--- a/packages/session/session-checkpoint-policy/package.json
+++ b/packages/session/session-checkpoint-policy/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-checkpoint-policy",
   "description": "Semantic session durability checkpoints before model requests and tool side effects",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-log-deepseek/package.json b/packages/session/session-log-deepseek/package.json
index 4746305509..a5cad9a5d8 100644
--- a/packages/session/session-log-deepseek/package.json
+++ b/packages/session/session-log-deepseek/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-log-deepseek",
   "description": "Incremental lossless session-log request extension for the official DeepSeek LLM API",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-persistence-jsonl/package.json b/packages/session/session-persistence-jsonl/package.json
index ae8967fdf1..a3bd097d83 100644
--- a/packages/session/session-persistence-jsonl/package.json
+++ b/packages/session/session-persistence-jsonl/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-persistence-jsonl",
   "description": "JSONL durable session persistence backend for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-persistence/package.json b/packages/session/session-persistence/package.json
index bd4c053688..1b4802d57c 100644
--- a/packages/session/session-persistence/package.json
+++ b/packages/session/session-persistence/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-persistence",
   "description": "Abstract durable session persistence seam (ctx.sessionPersistence) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-projection-cache/package.json b/packages/session/session-projection-cache/package.json
index 6ab2ec0469..73ce9ea58d 100644
--- a/packages/session/session-projection-cache/package.json
+++ b/packages/session/session-projection-cache/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-projection-cache",
   "description": "Persisted projection cache (ctx.sessionProjectionCache): durable per-session checkpoint records on the session_projcache storage domain (per-record layout), throttled write-behind, and the cached listing read",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-projection/package.json b/packages/session/session-projection/package.json
index c7ee0d1feb..547fc90ed1 100644
--- a/packages/session/session-projection/package.json
+++ b/packages/session/session-projection/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-projection",
   "description": "Session-projection seam: the merge-extensible projection type table, the provider contract, and the ctx.sessionProjections registry serving whole current values of log-derived per-session state",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-stats/package.json b/packages/session/session-stats/package.json
index 6b3c4bc173..d8c9fb3804 100644
--- a/packages/session/session-stats/package.json
+++ b/packages/session/session-stats/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-stats",
   "description": "Whole-log conversation counts and wall times projection (sessionStats) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-telemetry-otel/package.json b/packages/session/session-telemetry-otel/package.json
index b91a9a3cf3..b7b306e510 100644
--- a/packages/session/session-telemetry-otel/package.json
+++ b/packages/session/session-telemetry-otel/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-telemetry-otel",
   "description": "OpenTelemetry backend for the DeepSeek Harness telemetry seam: hands captured session records to the OTel JS SDK's log pipeline",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-telemetry/package.json b/packages/session/session-telemetry/package.json
index 5905bbd56d..65f4c5b478 100644
--- a/packages/session/session-telemetry/package.json
+++ b/packages/session/session-telemetry/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-telemetry",
   "description": "SessionTelemetryBackend seam for the DeepSeek Harness: session-event capture, projection, redaction, and handoff to a reporting backend",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-title-all-prompts-llm/package.json b/packages/session/session-title-all-prompts-llm/package.json
index 9979912745..197b4ee8bb 100644
--- a/packages/session/session-title-all-prompts-llm/package.json
+++ b/packages/session/session-title-all-prompts-llm/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-title-all-prompts-llm",
   "description": "All-user-messages LLM provider plugin for DeepSeek Harness session titles",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-title-first-prompt-llm/package.json b/packages/session/session-title-first-prompt-llm/package.json
index cfa113ee01..bc64fbf187 100644
--- a/packages/session/session-title-first-prompt-llm/package.json
+++ b/packages/session/session-title-first-prompt-llm/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-title-first-prompt-llm",
   "description": "First-message LLM provider plugin for DeepSeek Harness session titles",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-title-llm/package.json b/packages/session/session-title-llm/package.json
index 5e38f5ccf8..949f393365 100644
--- a/packages/session/session-title-llm/package.json
+++ b/packages/session/session-title-llm/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-title-llm",
   "description": "Shared LLM generation policy for DeepSeek Harness session-title providers",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-title/package.json b/packages/session/session-title/package.json
index ce206ca9dc..4c6bc9999c 100644
--- a/packages/session/session-title/package.json
+++ b/packages/session/session-title/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-title",
   "description": "Log-backed session title service and provider registry for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/session/session-turn-outline/package.json b/packages/session/session-turn-outline/package.json
index 0509312909..f50b13ca8c 100644
--- a/packages/session/session-turn-outline/package.json
+++ b/packages/session/session-turn-outline/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-turn-outline",
   "description": "Whole-log turn outline projection (turnOutline) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/settings/settings-file/package.json b/packages/settings/settings-file/package.json
index 3df6f6a40f..1fac8b8c7d 100644
--- a/packages/settings/settings-file/package.json
+++ b/packages/settings/settings-file/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-settings-file",
   "description": "File-backed settings provider (settings.yaml) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/settings/settings/package.json b/packages/settings/settings/package.json
index ee38a5b8ba..f370cc7636 100644
--- a/packages/settings/settings/package.json
+++ b/packages/settings/settings/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-settings",
   "description": "Abstract user-settings seam (ctx.settings) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/bash-local/package.json b/packages/shell/bash-local/package.json
index 910449b7d7..d89cc6ebe1 100644
--- a/packages/shell/bash-local/package.json
+++ b/packages/shell/bash-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-bash-local",
   "description": "Local-subprocess implementation of the DeepSeek Harness bash executor seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/bash-sandbox/package.json b/packages/shell/bash-sandbox/package.json
index 15162efc66..43b3a18aec 100644
--- a/packages/shell/bash-sandbox/package.json
+++ b/packages/shell/bash-sandbox/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-bash-sandbox",
   "description": "Sandbox-consuming implementation of the DeepSeek Harness bash executor seam (confines every command via ctx.sandbox, reports denial/enforcement result facts)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/pwsh-local/package.json b/packages/shell/pwsh-local/package.json
index 57927f8fa6..241ed04e89 100644
--- a/packages/shell/pwsh-local/package.json
+++ b/packages/shell/pwsh-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-pwsh-local",
   "description": "Local PowerShell implementation of the DeepSeek Harness bash executor seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/pwsh-sandbox/package.json b/packages/shell/pwsh-sandbox/package.json
index 4d021dc313..eb1f323fc4 100644
--- a/packages/shell/pwsh-sandbox/package.json
+++ b/packages/shell/pwsh-sandbox/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-pwsh-sandbox",
   "description": "Sandbox-consuming implementation of the DeepSeek Harness PowerShell executor seam (confines every command via ctx.sandbox, reports denial/enforcement result facts)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/shell-env/package.json b/packages/shell/shell-env/package.json
index 98bc4bdbc9..4b2bfce68b 100644
--- a/packages/shell/shell-env/package.json
+++ b/packages/shell/shell-env/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-shell-env",
   "description": "Tool-independent managed DSH_* shell environment registry",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/shell/package.json b/packages/shell/shell/package.json
index 41b0178965..a2fd9d37cf 100644
--- a/packages/shell/shell/package.json
+++ b/packages/shell/shell/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-shell",
   "description": "Abstract bash executor seam (ctx.shell) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/tool-bash-persistent/package.json b/packages/shell/tool-bash-persistent/package.json
index 2e2902059d..42b1958e25 100644
--- a/packages/shell/tool-bash-persistent/package.json
+++ b/packages/shell/tool-bash-persistent/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-bash-persistent",
   "description": "Model-facing owner-scoped persistent Bash tool backed by the Harness PTY service",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/tool-bash/package.json b/packages/shell/tool-bash/package.json
index cd66c744ce..68774b0c49 100644
--- a/packages/shell/tool-bash/package.json
+++ b/packages/shell/tool-bash/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-bash",
   "description": "Model-facing bash tool with optional generic background-job and sandbox-escalation support",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/tool-pwsh-persistent/package.json b/packages/shell/tool-pwsh-persistent/package.json
index 793096cb44..4cd2cabc85 100644
--- a/packages/shell/tool-pwsh-persistent/package.json
+++ b/packages/shell/tool-pwsh-persistent/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-pwsh-persistent",
   "description": "Model-facing owner-scoped persistent PowerShell tool backed by the Harness PTY service",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/shell/tool-pwsh/package.json b/packages/shell/tool-pwsh/package.json
index 07cd41cd10..83ad8bc0e4 100644
--- a/packages/shell/tool-pwsh/package.json
+++ b/packages/shell/tool-pwsh/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-pwsh",
   "description": "Model-facing pwsh tool over the bash executor seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/skill/skill-badge/package.json b/packages/skill/skill-badge/package.json
index 4afb2fb628..662f2fbc52 100644
--- a/packages/skill/skill-badge/package.json
+++ b/packages/skill/skill-badge/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-skill-badge",
   "description": "Bundled dsh badge skill provider for DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/skill/skill-filesystem/package.json b/packages/skill/skill-filesystem/package.json
index 3d5ba9452c..90204f193f 100644
--- a/packages/skill/skill-filesystem/package.json
+++ b/packages/skill/skill-filesystem/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-skill-filesystem",
   "description": "Local filesystem skill provider for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/skill/skill/package.json b/packages/skill/skill/package.json
index 122c338895..0691320c01 100644
--- a/packages/skill/skill/package.json
+++ b/packages/skill/skill/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-skill",
   "description": "Agent skill provider registry for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/skill/tool-skill/package.json b/packages/skill/tool-skill/package.json
index bffdcc40a3..da592a0ec5 100644
--- a/packages/skill/tool-skill/package.json
+++ b/packages/skill/tool-skill/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-skill",
   "description": "Model-facing skill loading tool for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/spill/spill-local/package.json b/packages/spill/spill-local/package.json
index 913bc26eb1..e2e9ee1427 100644
--- a/packages/spill/spill-local/package.json
+++ b/packages/spill/spill-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-spill-local",
   "description": "Local-filesystem implementation of the DeepSeek Harness spill storage seam (private session-scoped files)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/spill/spill-policy/package.json b/packages/spill/spill-policy/package.json
index 87b8cd05b7..bec3f69135 100644
--- a/packages/spill/spill-policy/package.json
+++ b/packages/spill/spill-policy/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-spill-policy",
   "description": "Tool-result spill policy for the DeepSeek Harness — replaces oversized plain-text tool results with a retained preview plus a spill-file path (no service API)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/spill/spill/package.json b/packages/spill/spill/package.json
index fb2276fce8..d61cf92ffa 100644
--- a/packages/spill/spill/package.json
+++ b/packages/spill/spill/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-spill",
   "description": "Abstract spill storage seam (ctx.spillStore) for the DeepSeek Harness — save oversized tool text and return a retrieval locator",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/storage/storage-domain/package.json b/packages/storage/storage-domain/package.json
index 2b99e2f67e..64b233b49c 100644
--- a/packages/storage/storage-domain/package.json
+++ b/packages/storage/storage-domain/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-storage-domain",
   "description": "Domain data form (ctx.storage.domain): schema-validated, event-emitting KV domains over storage backends for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/storage/storage-json/package.json b/packages/storage/storage-json/package.json
index e8448da8d8..a3bbc4be5d 100644
--- a/packages/storage/storage-json/package.json
+++ b/packages/storage/storage-json/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-storage-json",
   "description": "JSON file KV storage backend for the DeepSeek Harness storage hub",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/storage/storage-sqlite/package.json b/packages/storage/storage-sqlite/package.json
index 53f0a43ea6..d3e708627d 100644
--- a/packages/storage/storage-sqlite/package.json
+++ b/packages/storage/storage-sqlite/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-storage-sqlite",
   "description": "SQLite storage backend (kv facet) for the DeepSeek Harness storage hub",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/storage/storage/package.json b/packages/storage/storage/package.json
index ab4a14543c..9abe2460a5 100644
--- a/packages/storage/storage/package.json
+++ b/packages/storage/storage/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-storage",
   "description": "Storage hub (ctx.storage): named backend registry plus mounted data-form facilities for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/subagent-acp/package.json b/packages/subagent/subagent-acp/package.json
index 8d21c5b108..bb050d095b 100644
--- a/packages/subagent/subagent-acp/package.json
+++ b/packages/subagent/subagent-acp/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-acp",
   "description": "Out-of-process ACP subagent backend: drives a child agent in a spawned subprocess over the Agent Client Protocol",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/subagent-claude-code/package.json b/packages/subagent/subagent-claude-code/package.json
index b2b5827978..7abbd315d1 100644
--- a/packages/subagent/subagent-claude-code/package.json
+++ b/packages/subagent/subagent-claude-code/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-claude-code",
   "description": "One-shot Claude Code subagent provider over the official Agent SDK",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/subagent-codex/package.json b/packages/subagent/subagent-codex/package.json
index 4b8689e6be..0524fa8cfe 100644
--- a/packages/subagent/subagent-codex/package.json
+++ b/packages/subagent/subagent-codex/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-codex",
   "description": "One-shot Codex subagent provider over the official app-server protocol",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/subagent-dsh-sdk/package.json b/packages/subagent/subagent-dsh-sdk/package.json
index 564c02a694..43adf4c56f 100644
--- a/packages/subagent/subagent-dsh-sdk/package.json
+++ b/packages/subagent/subagent-dsh-sdk/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-dsh-sdk",
   "description": "Out-of-process SDK subagent backend: drives a child DeepSeek Harness runtime subprocess over stdio JSON-RPC through the TypeScript SDK client",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/subagent-fork-in-process/package.json b/packages/subagent/subagent-fork-in-process/package.json
index 1408bbbcff..62fd0f37c0 100644
--- a/packages/subagent/subagent-fork-in-process/package.json
+++ b/packages/subagent/subagent-fork-in-process/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-fork-in-process",
   "description": "In-process fork subagent backend: runs a child agent seeded with a prefix of the parent's log",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/subagent-in-process-driver/package.json b/packages/subagent/subagent-in-process-driver/package.json
index 11e6b84b63..dd1c59b1e6 100644
--- a/packages/subagent/subagent-in-process-driver/package.json
+++ b/packages/subagent/subagent-in-process-driver/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-in-process-driver",
   "description": "Shared in-process subagent run driver: drives a child agent on ctx.agents (used by the spawn and fork backends)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/subagent-spawn-in-process/package.json b/packages/subagent/subagent-spawn-in-process/package.json
index bdefd24a61..86485a17b6 100644
--- a/packages/subagent/subagent-spawn-in-process/package.json
+++ b/packages/subagent/subagent-spawn-in-process/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-spawn-in-process",
   "description": "In-process spawn subagent backend: runs a fresh child agent on ctx.agents",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/subagent/package.json b/packages/subagent/subagent/package.json
index fa6b7a5e67..b19a2ae48c 100644
--- a/packages/subagent/subagent/package.json
+++ b/packages/subagent/subagent/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent",
   "description": "Abstract subagent seam (ctx.subagents): named-provider registry for delegating to child agents",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/tool-subagent-control/package.json b/packages/subagent/tool-subagent-control/package.json
index db88b40c24..b5d2c05742 100644
--- a/packages/subagent/tool-subagent-control/package.json
+++ b/packages/subagent/tool-subagent-control/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-subagent-control",
   "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subagent/tool-subagent/package.json b/packages/subagent/tool-subagent/package.json
index 8160177479..34318e3aa1 100644
--- a/packages/subagent/tool-subagent/package.json
+++ b/packages/subagent/tool-subagent/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-subagent",
   "description": "Model-facing subagent delegation tool over the ctx.subagents seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subprocess/subprocess-local/package.json b/packages/subprocess/subprocess-local/package.json
index c7f08fbe68..70663bb503 100644
--- a/packages/subprocess/subprocess-local/package.json
+++ b/packages/subprocess/subprocess-local/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subprocess-local",
   "description": "Local-subprocess implementation of the DeepSeek Harness subprocess seam",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subprocess/subprocess/package.json b/packages/subprocess/subprocess/package.json
index a5e0e51dad..92cfa8131c 100644
--- a/packages/subprocess/subprocess/package.json
+++ b/packages/subprocess/subprocess/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subprocess",
   "description": "Subprocess seam (ctx.subprocess) for the DeepSeek Harness — managed process groups, bounded spill-backed output, and escalated kills behind one abstract service",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/subprocess/win32-process/package.json b/packages/subprocess/win32-process/package.json
index db1ec249a0..c90551d1d4 100644
--- a/packages/subprocess/win32-process/package.json
+++ b/packages/subprocess/win32-process/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-win32-process",
   "description": "Low-level Win32 process, stdio, and Job Object primitives for the DeepSeek Harness Windows sandbox",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/terminal/terminal-bash/package.json b/packages/terminal/terminal-bash/package.json
index c8db9f36e7..fbdb39ff0b 100644
--- a/packages/terminal/terminal-bash/package.json
+++ b/packages/terminal/terminal-bash/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-terminal-bash",
   "description": "Persistent shell PTY backend over the DeepSeek Harness subprocess terminal primitive",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/terminal/terminal/package.json b/packages/terminal/terminal/package.json
index d361453e05..02cd59fba0 100644
--- a/packages/terminal/terminal/package.json
+++ b/packages/terminal/terminal/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-terminal",
   "description": "Persistent PTY session seam for the DeepSeek Harness — owner-scoped ids, backend registry, interactive sends, reads, signals, and awaited cleanup",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/terminal/tool-terminal/package.json b/packages/terminal/tool-terminal/package.json
index faac799c2f..bb75c1ae2d 100644
--- a/packages/terminal/tool-terminal/package.json
+++ b/packages/terminal/tool-terminal/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-terminal",
   "description": "Six model-facing persistent PTY tools with owner isolation and generic background-job integration",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/test-support/agent-loop-testkit/package.json b/packages/test-support/agent-loop-testkit/package.json
index a2cd0fa6c7..33dad665e7 100644
--- a/packages/test-support/agent-loop-testkit/package.json
+++ b/packages/test-support/agent-loop-testkit/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-agent-loop-testkit",
   "description": "Shared prerequisite mounting for tests that exercise the concrete agent loop",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/test-support/client-runtime/package.json b/packages/test-support/client-runtime/package.json
index ef4f621c8c..acf24e1e33 100644
--- a/packages/test-support/client-runtime/package.json
+++ b/packages/test-support/client-runtime/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-test-runtime",
   "description": "jsdom slot test runtime: real Cordis Context + SlotRegistry + UI renderer with test-owned session/workspace doubles for feature specs",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/test-support/llm-mock-server/package.json b/packages/test-support/llm-mock-server/package.json
index faa1e42c64..13b7b55205 100644
--- a/packages/test-support/llm-mock-server/package.json
+++ b/packages/test-support/llm-mock-server/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm-mock-server",
   "description": "Scriptable OpenAI-compatible HTTP/SSE fault server for LLM recovery tests",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/test-support/llm-replay/package.json b/packages/test-support/llm-replay/package.json
index 9716020e79..de87ab8353 100644
--- a/packages/test-support/llm-replay/package.json
+++ b/packages/test-support/llm-replay/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm-replay",
   "description": "Replay LLM plugin: short-circuits llm/stream with model chunks reconstructed from a recorded session JSONL (keyless snapshot tests)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/test-support/loader-smoke/package.json b/packages/test-support/loader-smoke/package.json
index a519c2ae4d..1c79647f5c 100644
--- a/packages/test-support/loader-smoke/package.json
+++ b/packages/test-support/loader-smoke/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-loader-smoke",
   "description": "Shared subprocess and direct-agent harness for keyless real-Loader example smoke tests",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/test-support/session-snapshot/package.json b/packages/test-support/session-snapshot/package.json
index a526db3ee6..cd0c39aad6 100644
--- a/packages/test-support/session-snapshot/package.json
+++ b/packages/test-support/session-snapshot/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-snapshot",
   "description": "Session-log snapshot core with an ACP protocol adapter, expected-output normalization, and fixture invariants",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/todo/tool-todo/package.json b/packages/todo/tool-todo/package.json
index 1b2f215c2f..a5ffb42878 100644
--- a/packages/todo/tool-todo/package.json
+++ b/packages/todo/tool-todo/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-todo",
   "description": "Model-facing todo_write tool over the DeepSeek Harness event-sourced session log",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/typert/generator/package.json b/packages/typert/generator/package.json
index 54ef5e5fff..4ff26d9cb3 100644
--- a/packages/typert/generator/package.json
+++ b/packages/typert/generator/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-typert-generator",
   "description": "TypeScript project analyzer and model-driven Typert artifact generator",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/typert/loader/package.json b/packages/typert/loader/package.json
index f3ebdb56c9..5a77a4e4da 100644
--- a/packages/typert/loader/package.json
+++ b/packages/typert/loader/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-typert-loader",
   "description": "Loader integration for generated Typert package contributions",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/typert/protocol/package.json b/packages/typert/protocol/package.json
index 6fc93642e7..dcab658721 100644
--- a/packages/typert/protocol/package.json
+++ b/packages/typert/protocol/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-typert-protocol",
   "description": "Compiler-independent Remote metadata and Typert provider protocols",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/typert/registry/package.json b/packages/typert/registry/package.json
index e00070683e..0ba8c0ef78 100644
--- a/packages/typert/registry/package.json
+++ b/packages/typert/registry/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-typert-registry",
   "description": "Runtime registry for generated package reflection and Zod schemas",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/atomic-write/package.json b/packages/util/atomic-write/package.json
index ed12e9fb6f..71a3730a24 100644
--- a/packages/util/atomic-write/package.json
+++ b/packages/util/atomic-write/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-atomic-write",
   "description": "Zero-dependency atomic file replacement: exclusive-create random-suffix temp + rename carrying the caller-stated permissions (writeFileAtomic)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/brand/package.json b/packages/util/brand/package.json
index b6d049357b..e8c4d3108d 100644
--- a/packages/util/brand/package.json
+++ b/packages/util/brand/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-brand",
   "description": "Stateless branded primitive types for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/crypto/package.json b/packages/util/crypto/package.json
index 17154a248d..99f93075af 100644
--- a/packages/util/crypto/package.json
+++ b/packages/util/crypto/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-util-crypto",
   "description": "Zero-dependency browser-safe UUID and byte-encoding helpers",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/deque/package.json b/packages/util/deque/package.json
index 4ead44b3ba..53237374e2 100644
--- a/packages/util/deque/package.json
+++ b/packages/util/deque/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-deque",
   "description": "Zero-dependency circular deque with amortized constant-time end operations and bounded vacant storage",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/home-paths/package.json b/packages/util/home-paths/package.json
index 0d35a36878..863f54c5fa 100644
--- a/packages/util/home-paths/package.json
+++ b/packages/util/home-paths/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-home-paths",
   "description": "Shared filesystem path helpers for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/launch-environment/package.json b/packages/util/launch-environment/package.json
index 40572af43e..ced5ca67c4 100644
--- a/packages/util/launch-environment/package.json
+++ b/packages/util/launch-environment/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-launch-environment",
   "description": "Immutable DeepSeek Harness launch environment that records which layer supplied each value",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/native-command/package.json b/packages/util/native-command/package.json
index 4a07e80668..0359f5b21e 100644
--- a/packages/util/native-command/package.json
+++ b/packages/util/native-command/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-native-command",
   "description": "Host-native command and path-opening utilities with shell-free execution, cancellation, desktop detection, and WSL handoff",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/output-retention/package.json b/packages/util/output-retention/package.json
index fe671c17e1..fc97c68978 100644
--- a/packages/util/output-retention/package.json
+++ b/packages/util/output-retention/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-output-retention",
   "description": "Zero-dependency bounded-retention primitive: ItemRetainer/TextRetainer + neutral notice helpers (what did we keep, what did we omit)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/time/package.json b/packages/util/time/package.json
index d477b0ab93..1a75d46c5a 100644
--- a/packages/util/time/package.json
+++ b/packages/util/time/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-util-time",
   "description": "Zero-dependency time vocabulary shared by wire boundaries: canonicalClientTimeZone (IANA zone validation and canonicalization only, no formatting)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/timeout/package.json b/packages/util/timeout/package.json
index da427e1c80..fe8a05aa6f 100644
--- a/packages/util/timeout/package.json
+++ b/packages/util/timeout/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-timeout",
   "description": "Zero-dependency timeout/deadline primitive: clampTimeout, deadline, timeoutOf, TimeoutReason (timing + classification only, no termination)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/values/package.json b/packages/util/values/package.json
index bb65c9c60c..4f5a0e7497 100644
--- a/packages/util/values/package.json
+++ b/packages/util/values/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-util-values",
   "description": "Duplicate-install-safe value primitives for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/util/workspace-path/package.json b/packages/util/workspace-path/package.json
index 33711e9b28..dfba2de7fb 100644
--- a/packages/util/workspace-path/package.json
+++ b/packages/util/workspace-path/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-util-workspace-path",
   "description": "Browser-safe Workspace path and display helpers",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/web/tool-web/package.json b/packages/web/tool-web/package.json
index 041c13e3ce..6689dbc553 100644
--- a/packages/web/tool-web/package.json
+++ b/packages/web/tool-web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-web",
   "description": "Model-facing web tools (web_search, web_fetch) over the DeepSeek Harness web capability seam (ctx.web)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/web/web-fetch-http/package.json b/packages/web/web-fetch-http/package.json
index de94c879c1..ac827505e1 100644
--- a/packages/web/web-fetch-http/package.json
+++ b/packages/web/web-fetch-http/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-web-fetch-http",
   "description": "Anonymous public HTTP(S) fetch provider for the DeepSeek Harness web capability seam (ctx.web)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/web/web-search-deepseek/package.json b/packages/web/web-search-deepseek/package.json
index c3948d15ba..70a6b2559e 100644
--- a/packages/web/web-search-deepseek/package.json
+++ b/packages/web/web-search-deepseek/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-web-search-deepseek",
   "description": "DeepSeek-backed search provider (native web_search via the Anthropic-compatible API) for the DeepSeek Harness web capability seam (ctx.web)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/web/web-search-exa/package.json b/packages/web/web-search-exa/package.json
index c0d0fc7a14..604d0e89f8 100644
--- a/packages/web/web-search-exa/package.json
+++ b/packages/web/web-search-exa/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-web-search-exa",
   "description": "Exa-backed search provider for the DeepSeek Harness web capability seam (ctx.web)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/web/web-search-perplexity/package.json b/packages/web/web-search-perplexity/package.json
index 8c444637fc..9e273bdf65 100644
--- a/packages/web/web-search-perplexity/package.json
+++ b/packages/web/web-search-perplexity/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-web-search-perplexity",
   "description": "Perplexity-backed search provider for the DeepSeek Harness web capability seam (ctx.web)",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/web/web/package.json b/packages/web/web/package.json
index 85ae73a41e..faa6d421a9 100644
--- a/packages/web/web/package.json
+++ b/packages/web/web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-web",
   "description": "Abstract web access capability seam (ctx.web) for the DeepSeek Harness — search/fetch provider registry, registration-order-independent selection, request/result vocabulary, and the WebError taxonomy",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/webhook/webhook-github/package.json b/packages/webhook/webhook-github/package.json
index beb50a0933..42e2b50afa 100644
--- a/packages/webhook/webhook-github/package.json
+++ b/packages/webhook/webhook-github/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-webhook-github",
   "description": "Signed GitHub HTTP webhook adapter for the DeepSeek Harness webhook runtime",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/webhook/webhook/package.json b/packages/webhook/webhook/package.json
index 65175c91ab..242ba27f2e 100644
--- a/packages/webhook/webhook/package.json
+++ b/packages/webhook/webhook/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-webhook",
   "description": "Fire-and-forget webhook rule runtime that creates Workspace-backed DeepSeek Harness Sessions",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/workflow/tool-ralph/package.json b/packages/workflow/tool-ralph/package.json
index 7f512c0b0e..051fd07de1 100644
--- a/packages/workflow/tool-ralph/package.json
+++ b/packages/workflow/tool-ralph/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-ralph",
   "description": "Model-facing fresh-agent Ralph loop over the workflow and subagent seams",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/workflow/tool-workflow/package.json b/packages/workflow/tool-workflow/package.json
index 688e97bacb..a7354b805e 100644
--- a/packages/workflow/tool-workflow/package.json
+++ b/packages/workflow/tool-workflow/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-workflow",
   "description": "Model-facing workflow tool: run a JavaScript orchestration script over ctx.workflowEngine",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/workflow/workflow-worker-thread/package.json b/packages/workflow/workflow-worker-thread/package.json
index bd169cd18a..7ad89934b2 100644
--- a/packages/workflow/workflow-worker-thread/package.json
+++ b/packages/workflow/workflow-worker-thread/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-workflow-worker-thread",
   "description": "worker-thread workflow engine: executes model-written orchestration scripts off the host event loop, bridging agent() calls back to ctx.subagents",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/workflow/workflow/package.json b/packages/workflow/workflow/package.json
index d7785293e5..eff283a88f 100644
--- a/packages/workflow/workflow/package.json
+++ b/packages/workflow/workflow/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-workflow",
   "description": "Workflow capability seam: ctx.workflowEngine service, run vocabulary, and workflow/* events",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
diff --git a/packages/workspace/workspace/package.json b/packages/workspace/workspace/package.json
index 43dba0a32a..677e92d4b5 100644
--- a/packages/workspace/workspace/package.json
+++ b/packages/workspace/workspace/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-workspace",
   "description": "Workspace entity registry (ctx.workspaceRegistry): durable workspace records with validated session attachment over the domain data form for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },